CI Integration

Archgate checks run in any CI system that respects exit codes. Add a single step to your pipeline and architecture violations block merges automatically — the same archgate check your team runs locally, now enforced on every pull request.

This guide covers the two official GitHub Actions, archgate/check-action and archgate/setup-action. For the full command surface (flags, JSON schema, exit codes), the CLI CI integration guide at cli.archgate.dev is the authoritative reference.

The two official actions

Archgate publishes two composite GitHub Actions. Pick based on whether you only need to run a check or you need the CLI on PATH for further commands.

archgate/check-action One-step check. Installs the CLI and runs `archgate check --ci`, emitting inline GitHub annotations on the PR. Fails the job on error-severity violations.

archgate/setup-action Installs the Archgate CLI and adds it to PATH. Run whatever commands you need afterward — `check`, `adr list`, `adr import`, etc.

Both actions are Apache-2.0 licensed, support Ubuntu, macOS, and Windows runners, and accept a single optional version input (defaults to latest).

Quick start: check-action

The fastest way to gate merges is archgate/check-action. It runs setup-action under the hood, then executes archgate check --ci:

.github/workflows/archgate.yml

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

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

No Node.js setup, no install step, no extra configuration files — the action reads the .archgate/ directory already committed to your repository. If any rule reports an error-severity violation, the job exits with code 1 and the merge is blocked. Violations appear as inline annotations on the pull request’s Files changed tab, pointing at the offending file and line.

Note

check-action passes --ci for you, which is what produces the GitHub workflow annotations (::error / ::warning). You only need the --ci flag when invoking archgate check manually via setup-action.

Pin a version

Pin the CLI to a known-good release for reproducible CI:

- uses: archgate/check-action@v1
  with:
    version: v0.14.0 # optional, defaults to latest

Cross-platform matrix

Both actions install the right binary per runner OS, so the same workflow runs on all three platforms:

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

When you need more than check: setup-action

check-action only runs archgate check. If your workflow needs additional commands — listing ADRs as JSON, importing packs, or running a check with custom flags — use archgate/setup-action to put the CLI on PATH, then run commands as ordinary steps:

steps:
  - uses: actions/checkout@v4
  - uses: archgate/setup-action@v1
    with:
      version: v0.14.0 # optional
  - run: archgate check --ci
  - run: archgate adr list --json

Under the hood setup-action downloads the platform binary from the standalone installer (cli.archgate.dev/install-unix on Linux/macOS, cli.archgate.dev/install-windows on Windows), appends ~/.archgate/bin to GITHUB_PATH, and verifies the install with archgate --version.

Narrowing the check scope

Large repositories benefit from checking only what changed in the pull request. The CLI exposes flags for this — see the CLI reference for the full list. The common patterns:

Changed vs. base branch

Compare against the PR’s base branch so cross-file dependency rules see the full diff:

steps:
  - uses: actions/checkout@v4
  - uses: archgate/setup-action@v1
  - run: archgate check --ci --base origin/${{ github.base_ref }}

A single ADR

Run rules from one ADR when a PR only touches files governed by it:

- run: archgate check --ci --adr ARCH-006

Staged files only

Limit checking to git-staged files (mirrors the pre-commit behavior):

- run: archgate check --ci --staged

Exit codes

Archgate’s exit codes drive CI pass/fail behavior:

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

Only error-severity violations cause exit code 1. warning-severity findings are logged but do not fail the job.

Adding to an existing pipeline

If you already have a CI workflow, add Archgate as one step after checkout — it needs nothing beyond the .archgate/ directory in your repo:

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

  # Add the Archgate gate
  - uses: archgate/check-action@v1

Other CI systems

The official actions are GitHub-specific, but Archgate works anywhere you can run a shell command. The pattern is always the same:

1. Install the CLI — via the standalone installer, npm install -g archgate, or bun install -g archgate.

2. Run archgate check.

3. Read the exit code — 0 pass, 1 violations, 2 error.

For installation methods that work without Node.js (the standalone binary installer), GitLab CI, and Bun-based pipelines, follow the CLI CI integration guide — it documents each non-GitHub path in detail.

Catch violations earlier

CI catches violations at merge time. Editor plugins catch them at coding time, and pre-commit hooks catch them before they leave your machine. Layer all three so the CI gate is the backstop, not the first line of defense.

Related

Pre-commit hooks Block violating commits locally before they reach CI.

Migration guide Adopt Archgate into an existing repository.

CLI CI reference Authoritative flag, JSON, and installer documentation.