GitHub CI Integration

What the GitHub Actions workflow does

A typical GitHub Actions workflow runs archpilot validate --ci on pull requests and on pushes to main.

On pushes to main, it can upload the validated governance snapshot when the workflow has an ArchPilot Cloud URL and organization API token.

CI validation is available on all plans. Automatic CI-to-Cloud upload on main is available on paid plans.

The same workflow also refreshes the ArchPilot badge and commits the updated badge and validation artifacts back to the branch on main.

Permissions and prerequisites

• GitHub Actions must be enabled for the repository, and the repository must allow workflows to run.
• The workflow needs enough repository permission to update validation artifacts on main and support pull-request-oriented workflows.
• Validation is the blocking architecture step. Upload happens only after validation succeeds.
• Cloud upload should stay main-branch only unless your team intentionally chooses a different release branch.
• CI validation is available on all plans. Automatic CI-to-Cloud upload on main is available on paid plans.
• If your repository does not have a baseline yet, validate still runs. Baseline-related commands are separate follow-up workflows, not a prerequisite for the CI workflow to start.

Set up GitHub Actions step by step

CI validation is available on all plans. Automatic CI-to-Cloud upload on main is available on paid plans.

1. Open the repository on GitHub.
2. Go to Settings, then Secrets and variables, then Actions.
3. Add the ArchPilot Cloud URL with https://api.archpilot.org.
4. Add an organization API token created in ArchPilot Cloud from Settings, Tokens.
5. Commit the ArchPilot workflow to your repository.
6. Open a pull request and confirm archpilot validate --ci runs.
7. Merge or push to main and confirm validation runs first, then governance upload runs when the Cloud connection is configured and the organization plan allows CI upload.

https://api.archpilot.org

name: ArchPilot CI Governance

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  validate-architecture:
    if: github.event_name != 'push' || !contains(github.event.head_commit.message, '[skip archpilot badge sync]')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          run_install: false
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
          cache-dependency-path: pnpm-lock.yaml
      - name: Install dependencies
        run: pnpm install --frozen-lockfile
      - name: Build repository
        run: pnpm run build
      - name: Run ArchPilot CI validation
        run: archpilot validate --ci
      - name: Upload ArchPilot governance snapshot
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        run: archpilot governance upload --server "<archpilot-cloud-url>" --token "<organization-api-token>"
      - name: Refresh ArchPilot badge
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        run: archpilot badges publish

Required connection values

API tokens support manual uploads on all plans. Automated CI uploads require a paid plan.

• ArchPilot Cloud URL: the Cloud destination for governance upload.
• Organization API token: the upload credential created in ArchPilot Cloud.

https://api.archpilot.org

PR comments and review publishing

The standard workflow focuses on deterministic validation, optional main-branch upload, and badge or artifact refresh on main.

If you add review or comment publishing, keep those steps best-effort so they do not hide a real architecture validation failure. Validation should remain the source of truth for pass or fail.

Troubleshooting

• Workflow generated but upload skipped: check whether the GitHub repository has both the ArchPilot Cloud URL and organization API token configured.
• Workflow reached upload on main but the API rejected it: confirm whether the organization is on the Free plan. Manual governance upload is available on all plans, and automatic CI upload is available on paid plans.
• Token value wrong: regenerate or revoke the token in ArchPilot Cloud and update the saved token value.
• Cloud URL wrong: use https://api.archpilot.org.
• Validate failed but upload never ran: this is expected. Validation runs first and blocks the rest of the architecture workflow.
• PR comments not appearing: confirm whether your team has enabled PR comment publishing in the workflow.
• No repository appears in Cloud after main push: confirm validation succeeded, upload was not skipped, the token is still active, and the repository identity resolved from the Git remote is the one you expect.

Workflow file

Use your ArchPilot workflow as the source of truth for GitHub Actions setup.

Keep validation first, then upload the governance snapshot only after validation succeeds.