Integração com CI

As verificações do Archgate rodam em qualquer sistema de CI que respeite códigos de saída. Adicione um único passo ao seu pipeline e as violações de arquitetura passam a bloquear merges automaticamente — o mesmo archgate check que sua equipe executa localmente, agora aplicado em cada pull request.

Este guia cobre as duas GitHub Actions oficiais, archgate/check-action e archgate/setup-action. Para a superfície completa de comandos (flags, schema JSON, códigos de saída), o guia de integração com CI da CLI em cli.archgate.dev é a referência autoritativa.

As duas actions oficiais

O Archgate publica duas GitHub Actions compostas. Escolha com base em se você só precisa executar uma verificação ou se precisa da CLI no PATH para outros comandos.

archgate/check-action Verificação em um passo. Instala a CLI e executa `archgate check --ci`, emitindo anotações inline do GitHub no PR. Falha o job em violações de severidade error.

archgate/setup-action Instala a CLI do Archgate e a adiciona ao PATH. Execute em seguida os comandos que precisar — `check`, `adr list`, `adr import`, etc.

Ambas as actions são licenciadas sob Apache-2.0, suportam runners Ubuntu, macOS e Windows, e aceitam um único input opcional version (com padrão latest).

Início rápido: check-action

A forma mais rápida de gatear merges é archgate/check-action. Ela executa o setup-action por baixo dos panos e então roda 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

Sem configuração de Node.js, sem passo de instalação, sem arquivos de configuração extras — a action lê o diretório .archgate/ já versionado no seu repositório. Se qualquer regra reportar uma violação de severidade error, o job sai com código 1 e o merge é bloqueado. As violações aparecem como anotações inline na aba Files changed do pull request, apontando para o arquivo e a linha problemáticos.

Nota

O check-action passa --ci por você, que é o que produz as anotações de workflow do GitHub (::error / ::warning). Você só precisa da flag --ci ao invocar archgate check manualmente via setup-action.

Fixar uma versão

Fixe a CLI em um release conhecido como estável para um CI reprodutível:

- uses: archgate/check-action@v1
  with:
    version: v0.14.0 # opcional, padrão é latest

Matriz multiplataforma

Ambas as actions instalam o binário correto por SO do runner, então o mesmo workflow roda nas três plataformas:

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

Quando você precisa de mais do que check: setup-action

O check-action só executa archgate check. Se o seu workflow precisar de comandos adicionais — listar ADRs como JSON, importar packs ou rodar uma verificação com flags personalizadas — use archgate/setup-action para colocar a CLI no PATH e então execute os comandos como passos comuns:

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

Por baixo dos panos, o setup-action baixa o binário da plataforma a partir do instalador standalone (cli.archgate.dev/install-unix no Linux/macOS, cli.archgate.dev/install-windows no Windows), adiciona ~/.archgate/bin ao GITHUB_PATH e verifica a instalação com archgate --version.

Restringindo o escopo da verificação

Repositórios grandes se beneficiam de verificar apenas o que mudou no pull request. A CLI expõe flags para isso — veja a referência da CLI para a lista completa. Os padrões comuns:

Alterações vs. branch base

Compare contra a branch base do PR para que as regras de dependência entre arquivos vejam o diff completo:

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

Um único ADR

Execute as regras de um único ADR quando um PR só toca arquivos governados por ele:

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

Apenas arquivos staged

Limite a verificação aos arquivos no stage do git (espelha o comportamento de pre-commit):

- run: archgate check --ci --staged

Códigos de saída

Os códigos de saída do Archgate determinam o comportamento de aprovação/falha no CI:

Código	Significado	Comportamento no CI
0	Todas verificações passam	Job tem sucesso
1	Violações encontradas	Job falha
2	Erro interno	Job falha

Apenas violações de severidade error causam o código de saída 1. Achados de severidade warning são registrados, mas não fazem o job falhar.

Adicionando a um pipeline existente

Se você já tem um workflow de CI, adicione o Archgate como um passo após o checkout — ele não precisa de nada além do diretório .archgate/ no seu repositório:

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

  # Adicione o gate do Archgate
  - uses: archgate/check-action@v1

Outros sistemas de CI

As actions oficiais são específicas do GitHub, mas o Archgate funciona em qualquer lugar onde você possa executar um comando de shell. O padrão é sempre o mesmo:

1. Instale a CLI — via o instalador standalone, npm install -g archgate ou bun install -g archgate.

2. Execute archgate check.

3. Leia o código de saída — 0 passou, 1 violações, 2 erro.

Para métodos de instalação que funcionam sem Node.js (o instalador de binário standalone), GitLab CI e pipelines baseados em Bun, siga o guia de integração com CI da CLI — ele documenta em detalhe cada caminho fora do GitHub.

Pegue violações mais cedo

O CI pega violações no momento do merge. Os plugins de editor as pegam no momento da codificação, e os pre-commit hooks as pegam antes que saiam da sua máquina. Combine os três para que o gate de CI seja a última linha de defesa, e não a primeira.

Relacionados

Pre-commit hooks Bloqueie commits que violam regras localmente, antes que cheguem ao CI.

Guia de migração Adote o Archgate em um repositório existente.

Referência de CI da CLI Documentação autoritativa de flags, JSON e instalador.