CI Integration

Archgate checks fit into any CI system that respects exit codes. Add a single step to your pipeline and violations will block merges automatically.

GitHub Actions

The fastest way to add Archgate to GitHub Actions is with the official archgate/check-action. It installs the CLI, runs archgate check --output github, and outputs violations as inline annotations on the pull request’s “Files changed” tab:

name: Archgate
on:
  pull_request:
  push:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archgate/check-action@v1

That’s it. No Node.js setup, no install step. If any rule reports a violation with error severity, the job fails with exit code 1.

Pin a version

- uses: archgate/check-action@v1
  with:
    version: v0.15.0

Setup-only action

If you need to run Archgate commands beyond check (e.g. archgate adr list --json), use archgate/setup-action to install the CLI and add it to PATH, then run whatever commands you need:

steps:
  - uses: actions/checkout@v4
  - uses: archgate/setup-action@v1
  - run: archgate check --output github
  - run: archgate adr list --json

Cross-platform workflow

Both actions support Ubuntu, macOS, and Windows runners:

jobs:
  check:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: archgate/check-action@v1

Manual setup

If you prefer not to use the official actions, you can install Archgate manually:

steps:
  - uses: actions/checkout@v4
  - run: npm install -g archgate
  - run: archgate check

GitHub Actions annotations

Use --output github to output violations as GitHub Actions workflow annotations. These appear inline on the pull request’s “Files changed” tab, pointing directly to the offending file and line.

- run: archgate check --output github

The github format produces ::error and ::warning annotations in the format GitHub Actions expects. Each annotation includes the ADR ID, rule ID, file path, and line number.

Note

The archgate/check-action passes --output github automatically. You only need this flag when running archgate check manually.

SARIF output for Code Scanning

Use --output sarif to emit SARIF 2.1.0, the format GitHub’s Code Scanning and Code Quality features ingest. Unlike github annotations (which only appear on the PR diff), SARIF results also populate the repository’s Security tab and persist across runs.

permissions:
  contents: read
  security-events: write

steps:
  - name: Run archgate check
    run: archgate check --output sarif > results.sarif

  - name: Upload SARIF to GitHub Security tab
    if: success() || failure()
    uses: github/codeql-action/upload-sarif@7188fc363630916deb702c7fdcf4e481b751f97a # v4.37.1
    with:
      sarif_file: results.sarif

Two details matter here: the upload step needs if: success() || failure(), because archgate check exits 1 on violations and the findings must still reach the Security tab when there are findings (prefer this over always(), which would also run for cancelled jobs); and the job needs the security-events: write permission, or the upload is rejected.

Every rule violation becomes a SARIF result; advisory findings (briefing-budget, suppression, and unparsed-ADR warnings) are included too, as synthetic results under dedicated rule IDs, always at warning level. --output sarif is opt-in only — it is never auto-detected. See archgate check — SARIF output for the full field mapping.

Machine-readable output

Use --output json for structured output that other tools can parse:

- run: archgate check --output json > results.json

The JSON output includes:

{
  "pass": false,
  "total": 6,
  "passed": 5,
  "failed": 1,
  "warnings": 0,
  "errors": 1,
  "infos": 0,
  "ruleErrors": 0,
  "truncated": false,
  "results": [
    {
      "adrId": "ARCH-006",
      "ruleId": "no-unapproved-deps",
      "description": "Production dependencies must be on the approved list",
      "status": "fail",
      "totalViolations": 1,
      "shownViolations": 1,
      "violations": [
        {
          "message": "Unapproved production dependency: \"chalk\"",
          "file": "package.json",
          "severity": "error"
        }
      ],
      "durationMs": 18
    }
  ],
  "durationMs": 142
}

Exit codes

Code	Meaning	CI behavior
0	All checks pass	Job succeeds
1	Violations found	Job fails
2	Internal error	Job fails

Warnings (severity warning) are logged but do not affect the exit code. Only error-severity violations cause exit code 1.

Narrowing scope

Check files changed in the PR

Use --base to compare against the PR’s base branch. This gives cross-file dependency rules the full picture of what changed:

- run: archgate check --base origin/${{ github.base_ref }}

Without --base, the base branch is auto-detected from origin/HEAD. The explicit form is recommended in CI for deterministic behavior.

Check only staged files

Use --staged to limit checking to git-staged files. This is useful in pre-commit hooks or when you only want to validate what is about to be committed:

- run: archgate check --staged

Check a specific ADR

Use --adr <id> to run rules from a single ADR:

- run: archgate check --adr ARCH-006

This is useful when a PR only touches files governed by one ADR and you want faster feedback.

Adding to an existing pipeline

If you already have a CI configuration, add Archgate as a single step after your checkout:

# Existing pipeline
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: "22"
  - run: npm ci
  - run: npm test

  # Add Archgate check
  - run: npm install -g archgate
  - run: archgate check --output github

No additional dependencies or configuration files are needed beyond the .archgate/ directory already in your repository.

Caching the installation

Cache the ~/.archgate directory to speed up repeated installs:

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Cache Archgate
        uses: actions/cache@v4
        with:
          path: ~/.archgate
          key: archgate-${{ runner.os }}

      - run: npm install -g archgate
      - run: archgate check --output github

GitLab CI

adr-compliance:
  image: node:22
  script:
    - npm install -g archgate
    - archgate check

Standalone installer (no Node.js)

If your CI environment does not have Node.js, use the standalone installer to download a pre-built binary directly from GitHub Releases:

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: curl -fsSL https://cli.archgate.dev/install-unix | sh
      - run: ~/.archgate/bin/archgate check --output github

This works in any environment with curl and tar, no runtime dependencies needed. You can pin a version with the ARCHGATE_VERSION environment variable:

- run: curl -fsSL https://raw.githubusercontent.com/archgate/cli/main/install.sh | ARCHGATE_VERSION=v0.11.2 sh

Bun-based CI

If your CI already uses Bun, install Archgate with bun instead of npm:

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install -g archgate
      - run: archgate check --output github

Other CI systems

Archgate works with any CI system that can run shell commands. The pattern is always the same:

1. Install: npm install -g archgate, bun install -g archgate, or use the standalone installer
2. Run: archgate check
3. Check the exit code (0 = pass, 1 = violations, 2 = error)

For systems that support annotations (Azure DevOps, Buildkite, etc.), use --output json to parse the output and emit annotations in the format your CI expects.

Pre-commit hooks

You can also run Archgate as a local pre-commit hook. Add this to .git/hooks/pre-commit (or use a hook manager like Husky or Lefthook):

#!/bin/sh
archgate check --staged

The --staged flag ensures only files about to be committed are checked, keeping the hook fast.

Verbose output

Use --verbose to see passing rules and timing information alongside failures. This is helpful for debugging slow checks or confirming that rules are running as expected:

- run: archgate check --verbose

Add AI guardrails to your workflow

CI catches violations at merge time. Editor plugins catch them at coding time. With the Claude Code or Cursor plugin, your AI agent reads ADRs before writing code and validates compliance before you even commit. Sign up for beta access.