Pular para conteúdo

AUR-440 — A Action revisa pull requests automaticamente

Documento histórico do board. Pode descrever componentes removidos; para uso atual, consulte o guia do produto.

O que este card entrega

Um workflow de exemplo, .github/workflows/examples/code-review.yml, que o usuario copia para o repositorio dele como .github/workflows/code-review.yml. A partir da copia, todo pull request aberto, sincronizado ou reaberto e revisado pelo AurumCode e recebe o resultado como comentario no proprio pull request, sem ninguem rodar comando.

A arquitetura decidida: evento nativo, sem servidor proprio

O GitHub Actions dispara nativamente no evento pull_request e o job publica com o token da propria Action (github.token). Nao existe servidor de webhook self-hosted nem validacao HMAC neste desenho: esse segundo modelo de gatilho (internal/git/webhook, cmd/server) ficou fora do escopo desta rodada e permanece recuperavel do commit c12d7ab se um card futuro precisar dele. A decisao esta registrada no card AUR-440.

O binario de review e construido do checkout da release Mpaape/AurumCode na tag v1 — codigo confiavel e pinado. O codigo do pull request e apenas DADO para o job: e lido como diff git, nunca compilado nem executado. Um PR malicioso nao ganha execucao de build script sob um token com escrita.

Divergencia registrada: --publish pertence ao AUR-438

O Escopo do card menciona chamar o binario "com --publish". Esse flag nao existe no binario da arvore que a tag v1 publica, nem em nenhum flag ja publicado por cmd/aurumcode — o nome em portugues e --publicar, nao --publish. A publicacao atraves do proprio binario (--publicar, com --pr/--repo) pertence ao card AUR-438, que depende do cliente GitHub restaurado pelo AUR-437. AUR-438 esta done: cmd/aurumcode ja publica --pr, --repo, --publicar e --na-linha (cmd/aurumcode/pr.go, cmd/aurumcode/main.go). Um workflow que passasse o flag inexistente --publish sairia com exit 2 (flag desconhecido) em todo run de usuario — um exemplo quebrado por construcao, independente do estado do AUR-438.

Por isso este workflow entrega o Outcome com o que existe em v1: o binario revisa (review --base) e a publicacao e feita pelo passo seguinte com gh pr comment, sob a permissao pull-requests: write do job. As tres lanes deste card travam o conjunto de flags da invocacao em {--base, --fail-on}: qualquer flag fora do conjunto — --publish incluido — reprova o aceite. AUR-438 ja entregou a publicacao nativa em cmd/aurumcode (--pr, --repo, --publicar, --na-linha), mas este workflow de exemplo ainda nao foi migrado para usa-la — code-review.yml continua chamando review --base e publicando com gh pr comment. Migrar o exemplo e afrouxar/ajustar esse conjunto de flags trancado continua sendo trabalho de um card proprio, distinto deste.

Como usar

  1. Copie .github/workflows/examples/code-review.yml para o seu repositorio como .github/workflows/code-review.yml, sem editar nada.
  2. Configure dois secrets de repositorio: LLM_API_KEY e LLM_BASE_URL (endpoint compativel com OpenAI). Opcionalmente a variavel de repositorio LLM_MODEL (default do binario: gpt-4).
  3. Abra um pull request. O job review roda sozinho e publica o comentario ### AurumCode code review com os findings (ou No issues found.).

Exemplo executavel sem segredo: sem LLM_API_KEY/LLM_BASE_URL configurados, o passo de review falha com ::error::LLM_API_KEY and LLM_BASE_URL must be configured as repository secrets e exit 1 — nunca um check verde para um review que nao rodou.

Permissoes (privilegio minimo)

  • Nivel do workflow: contents: read e nada mais. Nenhuma entrada pull-requests existe no topo.
  • Job review (o unico job, e o unico lugar com escrita):
  • contents: read — faz os dois checkouts;
  • pull-requests: write — e o que permite gh pr comment publicar o comentario. Remover essa permissao faz a validacao de manifesto deste repositorio falhar com AUR-440/AC-001/MUT-001 (mutacao cetica do card) e faz o GitHub recusar a publicacao em runtime.

Pull request de fork: o GitHub retem os secrets e rebaixa o token para somente leitura no evento pull_request. O passo de review entao falha com a mensagem de secret ausente — falha visivel, nunca check verde silencioso. O exemplo nao usa pull_request_target de proposito: aquele evento entrega token com escrita a codigo vindo de fork.

Exit codes observaveis no job

O binario aurumcode review (ver docs/specs/AUR-430.md e docs/specs/AUR-431.md):

  • 0 — review rodou; findings (ou a linha No issues found.) impressos e publicados como comentario.
  • 1 — o review em si falhou (provider indisponivel, resposta invalida, diff ilegivel); o job falha e nada e publicado.
  • 2 — erro de uso; nao ocorre com a copia intacta do exemplo.

Passos do workflow: exit 1 quando os secrets faltam, quando o binario nao produz saida, ou quando gh pr comment e recusado (por exemplo sem pull-requests: write).

Publicar a tag v1 e acao humana

O workflow referencia Mpaape/AurumCode em ref: v1, a tag semver publicavel — nunca um SHA local de trabalho e nunca um branch mutavel. A publicacao da tag v1 e um ato humano do mantenedor, fora de qualquer run de CI e fora do aceite hermetico deste card (o sandbox nega rede). O aceite (tests/acceptance/AUR-440.sh) prova estaticamente, por parse YAML real (yaml.v3, arvore de nos), que o manifesto copiado entrega o contrato; ele nunca finge provar uma publicacao viva. Politica de pin imutavel? Troque a tag pelo SHA que ela resolve no momento da sua revisao.

Diagnostico de falha

  • LLM_API_KEY and LLM_BASE_URL must be configured... — configure os dois secrets no repositorio que copiou o workflow.
  • gh: ... (HTTP 403) no passo de publicacao — a permissao pull-requests: write foi removida do job, ou o PR vem de fork (token somente leitura). Restaure a permissao do exemplo.
  • aurumcode review: no LLM provider configured — o secret chegou vazio ao binario; verifique o nome exato dos secrets.
  • Job nem dispara — o arquivo precisa estar em .github/workflows/ do branch default, e o evento coberto e pull_request (opened, synchronize, reopened).

Validacao deste card

  • Unit: tests/unit/AUR-440.go::TestAUR440 — o documento do workflow, parseado de verdade, declara gatilho, permissoes, pins e passos.
  • Integration: tests/integration/AUR-440.go::IntegrationAUR440 — contrato cruzado com go.mod (owner/repo e diretiva go) e com action.yml (a composite raiz e o gerador de documentacao e nao revisa; nenhum passo pode delega-la).
  • E2E: tests/e2e/AUR-440.sh::E2EAUR440 — copia byte-identica para um repositorio de usuario de scratch, validador compilado rodado duas vezes com saida deterministica.
  • Accept: ./.board/bin/oci-run --profile bootstrap-readonly-v1 --card AUR-440.