GitHub CI Integration

What the GitHub Actions workflow does

The VS Code Setup GitHub CI Validation + Upload action generates `.github/workflows/archpilot-ci.yml`. The workflow runs on pull_request, pushes to main, and manual workflow_dispatch runs.

It checks out the repository with enough Git history, runs repository-specific setup inferred when the workflow is generated, runs ArchPilot CI validation, and then resolves the final workflow result.

On pull requests, successful validation is followed by a structural architecture baseline check, PR architecture review generation, and ArchPilot PR comment publishing. Review and comment publishing are reporting behavior and do not fail an otherwise successful validation solely because reporting failed.

On successful pushes to main, it can upload the validated governance snapshot to ArchPilot Cloud when the workflow has the ARCHPILOT_API_TOKEN repository secret.

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

The generated workflow does not commit badges, reports, validation artifacts, or generated files back to main.

Permissions and prerequisites

• GitHub Actions must be enabled for the repository, and the repository must allow workflows to run.
• The generated workflow uses contents: read and pull-requests: write permissions.
• 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.

Why validation uses finalization

The generated YAML may use continue-on-error: true on validation and reporting steps so ArchPilot can still publish review context and resolve the final result deliberately.

That does not make architecture validation non-blocking. The final result step checks the validation outcome and fails the job when architecture validation failed.

Baseline drift is separate: missing or invalid baseline state is setup guidance, detected drift follows the selected drift policy, and reporting failures remain non-blocking when validation itself passed.

Workflow generation and replacement

Generate the workflow from VS Code after ArchPilot has been initialized. If `.github/workflows/archpilot-ci.yml` does not exist, ArchPilot creates it.

If that workflow already exists, ArchPilot asks whether to replace it. Replacement overwrites the file only after explicit confirmation; cancelling preserves the existing workflow. ArchPilot does not silently merge custom workflow changes.

Repository setup inference and customization

The workflow is repository-aware at generation time. ArchPilot inspects local repository evidence and generates a best-effort setup starting point for detected Node/TypeScript, Java, Python, PHP, Go, Terraform, Ansible, monorepo/workspace, package-manager, build-tool, and Prisma signals.

For Node repositories, package manager selection follows repository evidence such as packageManager metadata and lockfiles. Generated install, build, and ArchPilot CLI commands can therefore vary between npm, pnpm, Yarn, and workspace layouts.

Common generated ArchPilot invocation styles include `npx @archpilotlabs/archpilot`, `pnpm dlx @archpilotlabs/archpilot`, and `yarn dlx @archpilotlabs/archpilot`. Users do not need a global ArchPilot install or a package script just to use the generated workflow.

• Adapt repository setup for required environment variables, databases or service containers, private registry authentication, generated code, unusual monorepo filters, custom build commands, project-specific working directories, and credentials required by your own build.
• Preserve the ArchPilot validation, baseline check, PR review/reporting, final result, and optional governance-upload order unless your team intentionally changes those semantics.

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. Initialize ArchPilot in VS Code.
2. Validate locally and review setup gaps before relying on CI.
3. Run Setup GitHub CI Validation + Upload.
4. Inspect `.github/workflows/archpilot-ci.yml` and adapt repository setup where necessary.
5. If automatic Cloud governance upload is desired, add an organization API token from ArchPilot Cloud as the ARCHPILOT_API_TOKEN repository secret.
6. Commit the workflow to your repository.
7. Open a pull request and confirm ArchPilot CI validation runs.
8. Merge or push to main and confirm validation runs first, then governance upload runs when ARCHPILOT_API_TOKEN is configured and the organization plan allows CI upload.

name: ArchPilot CI Governance

on:
  pull_request:
  workflow_dispatch:
    inputs:
      drift_policy:
        description: 'How baseline drift should affect the workflow result'
        required: false
        default: 'warn'
        type: choice
        options:
          - 'warn'
          - 'fail'
  push:
    branches:
      - main

jobs:
  validate-architecture:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
          cache-dependency-path: pnpm-lock.yaml
      - name: Prepare pnpm
        run: corepack prepare [email protected] --activate
      - name: Install dependencies
        run: pnpm install --frozen-lockfile
      - name: Build repository
        run: pnpm run build
      - name: Run ArchPilot CI validation
        id: archpilot_validate
        continue-on-error: true
        run: pnpm dlx @archpilotlabs/archpilot validate --ci
      - name: Run ArchPilot baseline drift check
        if: github.event_name == 'pull_request' && steps.archpilot_validate.outcome == 'success'
        id: archpilot_baseline
        continue-on-error: true
        shell: bash
        run: |
          set +e
          pnpm dlx @archpilotlabs/archpilot baseline check
          drift_exit=$?
          echo "exit_code=$drift_exit" >> "$GITHUB_OUTPUT"
          exit "$drift_exit"
      - name: Generate ArchPilot PR review
        if: github.event_name == 'pull_request' && steps.archpilot_validate.outcome == 'success'
        id: archpilot_pr_review
        continue-on-error: true
        run: pnpm dlx @archpilotlabs/archpilot review pr
      - name: Publish ArchPilot PR comment
        if: github.event_name == 'pull_request' && steps.archpilot_validate.outcome == 'success'
        id: archpilot_pr_comment
        continue-on-error: true
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: pnpm dlx @archpilotlabs/archpilot ci github
      - name: Upload ArchPilot governance snapshot
        if: steps.archpilot_validate.outcome == 'success' && github.event_name == 'push' && github.ref == 'refs/heads/main'
        env:
          ARCHPILOT_API_TOKEN: ${{ secrets.ARCHPILOT_API_TOKEN }}
          ARCHPILOT_UPLOAD_MODE: ci
          CI: "true"
        shell: bash
        run: |
          if [ -z "$ARCHPILOT_API_TOKEN" ]; then
            echo "ArchPilot governance upload skipped because ARCHPILOT_API_TOKEN secret is not configured."
            exit 0
          fi

          pnpm dlx @archpilotlabs/archpilot governance upload --token "${ARCHPILOT_API_TOKEN}"
      - name: Finalize workflow result
        if: always()
        env:
          VALIDATION_OUTCOME: ${{ steps.archpilot_validate.outcome }}
          BASELINE_OUTCOME: ${{ steps.archpilot_baseline.outcome }}
          BASELINE_EXIT_CODE: ${{ steps.archpilot_baseline.outputs.exit_code }}
          PR_REVIEW_OUTCOME: ${{ steps.archpilot_pr_review.outcome }}
          PR_COMMENT_OUTCOME: ${{ steps.archpilot_pr_comment.outcome }}
          DRIFT_POLICY: ${{ github.event_name == 'workflow_dispatch' && inputs.drift_policy || 'warn' }}
        run: |
          if [ "$VALIDATION_OUTCOME" = "failure" ]; then
            echo "ArchPilot validation failed."
            exit 1
          fi

          if [ "$BASELINE_OUTCOME" = "failure" ] && [ "$BASELINE_EXIT_CODE" = "1" ] && [ "$DRIFT_POLICY" = "fail" ]; then
            echo "ArchPilot baseline drift detected and drift policy is fail."
            exit 1
          fi

          echo "ArchPilot workflow completed successfully."

Required connection values

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

• ARCHPILOT_API_TOKEN: the GitHub repository secret used for main-branch governance upload.
• Architecture validation runs locally in GitHub Actions and does not require Cloud.
• Governance upload sends the validated snapshot to the official ArchPilot Cloud/API service when the token is configured.

PR comments and review publishing

`archpilot ci github` publishes or updates the ArchPilot GitHub pull-request comment. It is not the CLI equivalent of generating the workflow YAML.

The VS Code action generates `.github/workflows/archpilot-ci.yml`. Inside the generated workflow, PR review generation and comment publishing run after successful validation and are treated as reporting/integration behavior.

Troubleshooting

• Workflow generated but upload skipped: check whether the GitHub repository has the ARCHPILOT_API_TOKEN secret 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.
• 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 the workflow ran on a pull_request event and has pull-requests: write permission.
• 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.