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 --ci, 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 --ci
  - 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 --ci 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 --ci

The --ci flag 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 --ci automatically — you only need this flag when running archgate check manually.

Machine-readable output

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

- run: archgate check --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 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 --ci

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 --ci

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 --ci

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 --ci

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 --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 governance 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.