Integração com CI

As verificações do Archgate funcionam em qualquer sistema de CI que respeite códigos de saída. Adicione um único passo ao seu pipeline e as violações bloquearão merges automaticamente.

GitHub Actions

A forma mais rápida de adicionar o Archgate ao GitHub Actions é com a action oficial archgate/check-action. Ela instala o CLI, executa archgate check --ci e exibe violações como anotações inline na aba “Files changed” do pull request:

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

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

Isso é tudo — sem configuração de Node.js, sem passo de instalação. Se qualquer regra reportar uma violação com severidade error, o job falha com código de saída 1.

Fixar uma versão

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

Action apenas de setup

Se você precisa executar comandos do Archgate além do check (ex: archgate adr list --json), use archgate/setup-action para instalar o CLI e adicioná-lo ao PATH, e depois execute os comandos necessários:

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

Workflow multiplataforma

Ambas as actions suportam runners Ubuntu, macOS e Windows:

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

Configuração manual

Se você preferir não usar as actions oficiais, pode instalar o Archgate manualmente:

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

Anotações do GitHub Actions

Use --ci para exibir violações como anotações de workflow do GitHub Actions. Elas aparecem inline na aba “Files changed” do pull request, apontando diretamente para o arquivo e a linha com o problema.

- run: archgate check --ci

A flag --ci produz anotações ::error e ::warning no formato esperado pelo GitHub Actions. Cada anotação inclui o ID do ADR, o ID da regra, o caminho do arquivo e o número da linha.

Nota

A archgate/check-action passa --ci automaticamente — você só precisa dessa flag ao executar archgate check manualmente.

Saída legível por máquina

Use --json para saída estruturada que outras ferramentas podem processar:

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

A saída JSON inclui:

{
  "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
}

Códigos de saída

Código	Significado	Comportamento no CI
0	Todas as verificações passaram	Job bem-sucedido
1	Violações encontradas	Job falha
2	Erro interno	Job falha

Avisos (severidade warning) são registrados, mas não afetam o código de saída. Apenas violações com severidade error causam o código de saída 1.

Reduzindo o escopo

Verificar apenas arquivos staged

Use --staged para limitar a verificação aos arquivos staged no git. Isso é útil em hooks de pre-commit ou quando você deseja validar apenas o que está prestes a ser commitado:

- run: archgate check --staged

Verificar um ADR específico

Use --adr <id> para executar regras de um único ADR:

- run: archgate check --adr ARCH-006

Isso é útil quando um PR altera apenas arquivos governados por um ADR e você deseja feedback mais rápido.

Adicionando a um pipeline existente

Se você já tem uma configuração de CI, adicione o Archgate como um único passo após o 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

Nenhuma dependência adicional ou arquivo de configuração é necessário além do diretório .archgate/ que já está no seu repositório.

Cache da instalação

Faça cache do diretório ~/.archgate para acelerar instalações repetidas:

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

Instalador standalone (sem Node.js)

Se seu ambiente de CI não possui Node.js, use o instalador standalone para baixar um binário pré-compilado diretamente das 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

Isso funciona em qualquer ambiente com curl e tar — sem dependências de runtime. Você pode fixar uma versão com a variável de ambiente ARCHGATE_VERSION:

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

CI baseado em Bun

Se seu CI já usa Bun, instale o Archgate com bun ao invés de 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

Outros sistemas de CI

O Archgate funciona com qualquer sistema de CI que consiga executar comandos shell. O padrão é sempre o mesmo:

1. Instalar: npm install -g archgate, bun install -g archgate, ou use o instalador standalone
2. Executar: archgate check
3. Verificar o código de saída (0 = aprovado, 1 = violações, 2 = erro)

Para sistemas que suportam anotações (Azure DevOps, Buildkite, etc.), use --json para processar a saída e emitir anotações no formato esperado pelo seu CI.

Hooks de pre-commit

Você também pode executar o Archgate como um hook de pre-commit local. Adicione isso a .git/hooks/pre-commit (ou use um gerenciador de hooks como Husky ou Lefthook):

#!/bin/sh
archgate check --staged

A flag --staged garante que apenas os arquivos prestes a serem commitados sejam verificados, mantendo o hook rápido.

Saída detalhada

Use --verbose para ver as regras aprovadas e informações de tempo junto com as falhas. Isso é útil para debugar verificações lentas ou confirmar que as regras estão rodando como esperado:

- run: archgate check --verbose

Adicione governança de IA ao seu fluxo de trabalho

O CI detecta violações no momento do merge. Plugins de editor detectam no momento da codificação. Com o plugin Claude Code ou Cursor, seu agente de IA lê os ADRs antes de escrever código e valida a conformidade antes mesmo de você commitar. Inscreva-se para acesso beta.