Phase 19 - Lesson 16

Capstone 16 — Agente Autônomo GitHub Issue-to-PR

O AWS Remote SWE Agents, o Cursor Background Agents, a nuvem OpenAI Codex e o Google Jules entregam o mesmo formato de produto em 2026: rotule uma issue e receba um PR. Execute um agente em um sandbox na nuvem, verifique se os testes passam e envie um PR pronto para revisão com a justificativa (rationale). As partes difíceis são reproduzir o ambiente de build do repositório automaticamente, evitar o vazamento de credenciais, aplicar orçamentos por repositório e garantir que o agente não possa realizar force-push. Este capstone constrói a versão auto-hospedada (self-hosted) e a compara em custo e taxa de sucesso com as alternativas hospedadas.

Tipo: Capstone Idiomas: Python (agente), TypeScript (GitHub App), YAML (Actions) Pré-requisitos: Fase 11 (engenharia de LLM), Fase 13 (ferramentas), Fase 14 (agentes), Fase 15 (autônomo), Fase 17 (infraestrutura) Fases exercitadas: P11 · P13 · P14 · P15 · P17 Tempo: 30 horas

Problema

O agente de codificação assíncrono na nuvem é uma categoria de produto separada dos agentes de codificação interativos (capstone 01). A experiência do usuário (UX) é uma etiqueta (label) no GitHub. Você rotula uma issue como @agent fix this, um worker é iniciado em um sandbox na nuvem, clona o repositório, roda testes, edita arquivos, verifica e abre um PR com a justificativa do agente no corpo. Sem loop interativo, sem terminal. AWS Remote SWE Agents, Cursor Background Agents, nuvem OpenAI Codex, Google Jules e Factory Droids convergem todos para isso.

Os desafios de engenharia são concretos: reprodução do ambiente (o agente tem que construir o repositório do zero sem uma imagem de desenvolvimento em cache), testes instáveis (flaky tests, que devem ser executados novamente ou isolados), escopo de credenciais (um GitHub App com permissões refinadas mínimas), aplicação de orçamento por repositório por dia e política de proibição de force-push. O capstone mede a taxa de sucesso (pass rate), custo e segurança em relação às alternativas hospedadas.

Conceito

O gatilho (trigger) é um webhook do GitHub (etiqueta de issue ou comentário de PR). Um despachante (dispatcher) enfileira o trabalho no ECS Fargate ou Lambda. O worker puxa o repositório para um sandbox Daytona ou E2B com um Dockerfile genérico inferido a partir do repositório (idioma, framework). O agente executa um loop do mini-swe-agent ou SWE-agent v2 contra o Claude Opus 4.7 ou GPT-5.4-Codex. Ele realiza iterações: lê código, propõe correção, aplica patch, roda testes.

A verificação é a etapa restritiva (gate). O CI completo deve passar no sandbox antes que o PR seja aberto. O delta de cobertura é calculado; se for negativo além de um limite, o PR é aberto, mas recebe a etiqueta needs-review. O agente publica a justificativa como a descrição do PR, além de uma thread @agent que o revisor pode marcar para acompanhamentos.

A segurança tem seu escopo definido por meio de duas superfícies diferentes do GitHub: o App fornece um token de instalação de curta duração com permissões de workflows: read e escopos restritos de conteúdo de repositório/PR; a proteção de branch (e não as permissões do app) impõe "nenhuma gravação direta na main" e "nenhum force-push" — o app nunca é adicionado à lista de desvio (bypass list). O acesso somente leitura com escopo de caminho para .github/workflows não é uma primitiva real de GitHub App, de modo que a lista de permissões (allow-list) do agente para edições de arquivos deve impor isso diretamente no worker. Os tetos de orçamento por repositório por dia são aplicados no dispatcher (por exemplo, no máximo 5 PRs por repositório por dia,

0 por PR).

Arquitetura

GitHub issue labeled `@agent fix` or PR comment
            |
            v
    GitHub App webhook -> AWS Lambda dispatcher
            |
            v
    ECS Fargate task (or GitHub Actions self-hosted runner)
       - pull repo
       - infer Dockerfile (language, package manager)
       - Daytona / E2B sandbox with target runtime
       - clone -> git worktree -> agent branch
            |
            v
    mini-swe-agent / SWE-agent v2 loop
       Claude Opus 4.7 or GPT-5.4-Codex
       tools: ripgrep, tree-sitter, read/edit, run_tests, git
            |
            v
    verify CI passes in-sandbox + coverage delta check
            |
            v (verified)
    git push + open PR via GitHub App
       PR body = rationale + diff summary + trace URL
       label: needs-review
            |
            v
    operator reviews; can @-mention agent for follow-ups

Pilha

Construção

  1. GitHub App. Token de instalação refinado: leitura+gravação de issues, gravação de pull_requests, leitura+gravação de contents, leitura de workflows. A proteção de branch (a única superfície que pode fazer isso) impõe "nenhum push direto para a main" e "nenhum force-push"; o app não está na lista de desvio. O worker impõe "nenhuma gravação sob .github/workflows" como uma verificação de lista de permissões no diff proposto, já que as permissões do GitHub App não possuem escopo de caminho.

  2. Receptor de webhook. Função Lambda aceita webhooks de etiqueta de issue / comentário de PR. Filtra pela etiqueta @agent fix this. Enfileira no SQS.

  3. Despachante (Dispatcher). Retira tarefas do SQS. Aplica o orçamento por repositório por dia. Inicia uma tarefa no ECS Fargate com a URL do repositório, corpo da issue e um sandbox Daytona novo.

  4. Inferência de ambiente. Detecta o idioma (Python, Node, Go, Rust) e o gerenciador de pacotes (uv, pnpm, go mod, cargo). Gera um Dockerfile dinamicamente se não existir um.

  5. Loop do agente. mini-swe-agent ou SWE-agent v2 com Claude Opus 4.7. Ferramentas: ripgrep, repo-map com tree-sitter, read_file, edit_file, run_tests, git. Limites estritos: custo de 0, 30 minutos de tempo de execução real (wall-clock), 30 turnos do agente.

  6. Verificação. Após a conclusão do loop, execute a suíte de testes completa no sandbox. Calcule o delta de cobertura via jacoco / coverage.py. Se o CI estiver vermelho: interrompa, não abra o PR. Se a cobertura cair mais de 2%: abra o PR com a etiqueta needs-review.

  7. Envio do PR. Faz push da branch do agente. Abre o PR via API do GitHub com: título, justificativa, resumo do diff, URL do rastreamento (trace URL), custo, turnos.

  8. Higiene de credenciais. O worker é executado com um token de instalação do GitHub App de curta duração. Os logs são limpos de segredos antes do arquivamento.

  9. Avaliação (Eval). 30 issues internas semeadas de várias dificuldades. Meça a taxa de sucesso (pass rate), qualidade do PR (tamanho do diff, estilo, cobertura), custo, latência. Compare com o Cursor Background Agents e o AWS Remote SWE Agents nas mesmas issues.

Uso

# on github.com
  - user labels issue #842 with `@agent fix this`
  - PR #1903 appears 14 minutes later
  - body:
    > Fixed NPE in widget.dedupe() caused by null comparator entry.
    > Added regression test widget_test.go::TestDedupeNullComparator.
    > Coverage delta: +0.12%
    > Turns: 7  Cost: 
.80  Trace: langfuse:...
    > Label: needs-review

Entrega

outputs/skill-issue-to-pr.md é o entregável. Um GitHub App + worker assíncrono na nuvem que transforma issues rotuladas em PRs prontos para revisão com custo limitado e credenciais com escopo definido.

Peso Critério Como é medido
25 Taxa de sucesso em 30 issues Sucesso de ponta a ponta (CI verde + cobertura OK)
20 Qualidade do PR Tamanho do diff, delta de cobertura, conformidade de estilo
20 Custo e latência por issue resolvida Custo ($) e tempo de execução real por PR
20 Segurança Token com escopo, orçamento por repositório, sem force-push, higiene de credenciais
15 UX do operador Comentários de justificativa, recurso de nova tentativa, acompanhamento via menção com @
100

Exercícios

  1. Adicione um modo "corrigir teste instável": a etiqueta @agent stabilize-flake TestX executa o teste 50 vezes no sandbox e propõe uma alteração mínima que o estabiliza.

  2. Compare o custo em relação ao Cursor Background Agents em três issues compartilhadas. Relate quais ferramentas vencem em cada situação.

  3. Implemente um painel (dashboard) de orçamento: custo por repositório por dia, custo por usuário. Alerte em caso de anomalia.

  4. Crie um modo de "execução simulada" (dry-run) que abre um rascunho de PR (draft PR) sem executar o CI, permitindo que os revisores analisem o plano de forma econômica.

  5. Adicione uma política de retenção: branches de PR com mais de 7 dias sem merge são excluídas automaticamente.

Termos-Chave

Termo O que dizem O que realmente significa
GitHub App "Identidade de bot com escopo" App com permissões refinadas + token de instalação de curta duração
Agente assíncrono na nuvem "Agente em segundo plano" Worker não interativo que roda em um sandbox na nuvem, não em um terminal
Inferência de ambiente "Síntese de Dockerfile" Detecta idioma + gerenciador de pacotes, gera um Dockerfile se ausente
Verificação "CI no sandbox" Executa a suíte de testes completa dentro do worker antes de abrir um PR
Delta de cobertura "Preservação de cobertura" Alteração na porcentagem (%) de cobertura de teste da base para a branch do agente
Orçamento por repositório "Teto diário" Limite de dólares e contagem de PRs aplicado no despachante (dispatcher)
Justificativa "Explicação no corpo do PR" Resumo do agente sobre o que mudou e o porquê; obrigatório no corpo do PR

Leituras Adicionais