Axiom Refract + GitHub Actions

Add automated architectural analysis to your GitHub Actions CI/CD pipeline

How It Works

1

Create Workflow File

Add a GitHub Actions workflow file (.github/workflows/axiom-scan.yml) that triggers Axiom scans on push, pull request, or on a schedule.

2

Configure API Credentials

Store your Axiom Refract API credentials as GitHub repository secrets. The workflow uses these credentials to authenticate scan requests.

3

Define Trigger Conditions

Configure the workflow to run on your preferred triggers — every push to main, every pull request, weekly schedule, or manual dispatch.

4

Add Quality Gates

Optionally configure the workflow to fail if architectural metrics exceed thresholds — SPOF count limits, blast radius maximums, or dead code percentages.

What You Can Do

PR-Level Architecture Review

Run Axiom scans on pull requests to catch architectural regressions before they merge. Comment scan summaries directly on the PR.

Scheduled Architectural Monitoring

Run scans on a cron schedule (weekly, monthly) to track architectural health trends over time without manual intervention.

Architectural Quality Gates

Fail workflows when architectural metrics exceed defined thresholds. Prevent SPOF growth, dead code accumulation, and coupling increases from reaching production.

Artifact Archiving

Store scan results as GitHub Actions artifacts. Access architectural reports, dependency graphs, and C4 diagrams from the workflow run page.

Setup

Create the workflow file at .github/workflows/axiom-scan.yml in your repository. Add your Axiom customer ID as a GitHub repository secret (Settings > Secrets > AXIOM_CUSTOMER_ID). Push the workflow file to your repository. The scan will trigger on the next push to main, pull request, or Monday morning schedule.

# .github/workflows/axiom-scan.yml
name: Axiom Refract Architecture Scan

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 6 * * 1'  # Weekly on Monday at 6am UTC

jobs:
  architecture-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Axiom Scan
        run: |
          RESPONSE=$(curl -s -X POST https://axiomrefract.com/api/v1/jobs \
            -H "Content-Type: application/json" \
            -d '{
              "repo_source": "${{ github.server_url }}/${{ github.repository }}",
              "repo_type": "github",
              "customer_id": "${{ secrets.AXIOM_CUSTOMER_ID }}"
            }')
          echo "Job ID: $(echo $RESPONSE | jq -r '.id')"
          echo "JOB_ID=$(echo $RESPONSE | jq -r '.id')" >> $GITHUB_ENV

      - name: Wait for Scan Completion
        run: |
          for i in {1..60}; do
            STATUS=$(curl -s https://axiomrefract.com/api/v1/jobs/$JOB_ID | jq -r '.status')
            if [ "$STATUS" = "complete" ]; then echo "Scan complete"; exit 0; fi
            if [ "$STATUS" = "failed" ]; then echo "Scan failed"; exit 1; fi
            sleep 30
          done
          echo "Scan timed out"; exit 1

Why This Matters

GitHub Actions is the most widely adopted CI/CD platform for GitHub-hosted projects. Integrating Axiom Refract into your Actions pipeline means every push, every PR, or every release is automatically assessed for architectural health — catching regressions before they accumulate into technical debt.

Read the Docs →