Agentes de IA abrindo pull requests com controles seguros

Agentes de IA que abrem pull requests por meio de uma API podem economizar um tempo considerável da engenharia, mas somente se o repositório tratar cada mudança gerada como uma contribuição não confiável, com um autor rastreável. O limite útil é simples: um agente pode preparar uma mudança proposta; as pessoas e os controles do repositório decidem se ela pertence à base de código.

Já vi equipes tornarem esse processo inseguro ao se concentrarem na qualidade do código do modelo e ignorarem as permissões ao redor dele. As falhas mais graves costumam ser banais. Uma tarefa destinada a um serviço de staging chega a um repositório de produção. Um token amplo concede silenciosamente acesso de escrita a todos os projetos. Um agente abre dez pull requests quase idênticos depois de um timeout. Alguém faz merge de um deles porque o título parece plausível.

Uma configuração segura não depende de o agente ser cuidadoso. Ela limita onde o agente pode agir, força a mudança a passar pela revisão normal e deixa um registro suficientemente bom para uma investigação posterior.

O escopo do repositório precisa ser explícito e aplicado por máquina

Um agente deve receber permissão para um conjunto nomeado de repositórios, não um escopo curinga para toda a organização que alguém pretende restringir mais tarde. O escopo responde a uma pergunta concreta: em quais bases de código esse processo pode ler, criar branches e abrir pull requests?

Mantenha a lista de permissões fora do texto de instruções do agente. Prompts podem orientar o comportamento, mas não impõem autorização. O componente que mantém a credencial do repositório ou faz a requisição à API precisa rejeitar qualquer repositório que não esteja na lista permitida.

Para cada repositório permitido, defina as branches-base e o namespace de escrita autorizados. Um registro útil seria:

repositories:
  - name: acme/payments-api
    base_branches: ["main", "release/2025.1"]
    write_branch_prefix: "agent/"
    pull_request_drafts: true
  - name: acme/docs
    base_branches: ["main"]
    write_branch_prefix: "agent/"
    pull_request_drafts: false

Esse trecho evita uma falha comum: o agente recebe uma solicitação para «corrigir o texto do checkout», encontra um arquivo semelhante em um repositório que pode pesquisar e escreve nele porque sua credencial permite. A lista de permissões transforma isso em uma requisição negada, não em um trabalho de limpeza para outra pessoa.

O escopo também inclui as operações do repositório. A maioria dos agentes precisa ler arquivos, criar uma branch, enviar commits, ler verificações e criar ou atualizar um pull request. Raramente precisam alterar configurações do repositório, registrar webhooks, modificar regras de proteção de branches, adicionar chaves de implantação, gerenciar membros ou fazer merge. Não conceda essas permissões apenas porque vieram junto com um token amplo e conveniente.

Use uma identidade de bot separada, em vez do token pessoal de um desenvolvedor. Um token pessoal dificulta a atribuição, continua válido mesmo quando a tarefa muda e costuma carregar permissões que ninguém se lembra de ter concedido. Uma identidade de bot oferece um único ator para suspender quando algo der errado.

O acesso de leitura merece a mesma atenção que o de escrita. Um agente que pode inspecionar todos os repositórios privados pode expor código-fonte ou configurações nos próprios logs, no contexto da tarefa e nas respostas. Dê a ele o menor conjunto útil de repositórios, mesmo que nunca receba uma credencial de escrita direta.

Um prefixo de branch é um limite de execução, não uma preferência de nomenclatura

O agente deve criar branches apenas abaixo de um prefixo dedicado, como agent/, e o servidor do repositório deve impor essa restrição. Uma convenção escrita em um prompt será quebrada mais cedo ou mais tarde, seja por uma chamada de ferramenta malformada, um erro de nova tentativa ou uma tentativa do agente de cumprir uma tarefa ampla demais.

Proteja main, branches de release, branches de ambiente e qualquer branch que faça implantação automática. O agente não deve poder enviar alterações para elas, fazer force push ou alterar as regras que as protegem.

Torne os nomes das branches determinísticos o suficiente para investigação e únicos o suficiente para evitar colisões. Inclua uma referência da tarefa e um sufixo aleatório curto ou um identificador da execução:

agent/OPS-1842-retry-payment-7f3a

Não deixe o agente usar títulos de issues diretamente como nomes de branches. Títulos podem conter segredos, nomes de clientes, caracteres perigosos ou linguagem enganosa. Gere o nome da branch no controlador e passe-o ao agente como um valor imutável.

O commit-base também precisa de uma regra explícita. Quando o controlador iniciar uma execução, deve resolver a branch-base aprovada para um SHA de commit e registrá-lo. O agente cria sua branch a partir desse SHA, não do significado que main tiver depois de uma longa execução de geração de código. Isso não elimina a divergência, mas torna o problema visível e reproduzível.

Uma branch deve conter apenas os commits associados à tarefa atribuída. Isso significa nada de varredura oportunista de formatação, atualização de dependência sem relação ou tentativa de «limpar» código próximo porque ele parecia estranho. Mudanças geradas costumam parecer confiantes, e os revisores deixam passar alterações sem relação quando elas aparecem dentro de um patch razoável.

Defina um orçamento de mudança antes do início do trabalho. Ele pode limitar arquivos alterados, o total de linhas ou caminhos fora do componente solicitado. O limite não mede o risco por si só. Ele funciona como um alerta que manda o agente parar e solicitar uma nova tarefa, em vez de transformar silenciosamente um pequeno reparo em uma reescrita do repositório inteiro.

A criação do pull request precisa de uma transação de API verificada

Uma resposta HTTP bem-sucedida não prova que o agente abriu o pull request correto. O controlador deve verificar o repositório, a branch de origem, a branch-base, o SHA do commit e o identificador do pull request retornado antes de informar sucesso.

Em uma API no estilo do GitHub, os campos relevantes da requisição são o título proposto, head, base, o corpo e o status de rascunho. O endpoint exato varia conforme a plataforma, mas as verificações de segurança não:

{
  "title": "OPS-1842: retry transient payment gateway failures",
  "head": "agent/OPS-1842-retry-payment-7f3a",
  "base": "main",
  "body": "Task: OPS-1842\nBase commit: 4b2c...\nTests: unit payment retry suite\nLimits: no configuration changes",
  "draft": true
}

Antes de enviar essa requisição, consulte a branch e confirme que seu SHA de ponta corresponde ao commit registrado pela execução. Depois de receber a resposta, busque o pull request e compare head, base e o estado com a requisição. Registre o número imutável do pull request ou o identificador de nó da plataforma, não apenas sua URL.

As novas tentativas exigem tratamento especial. Timeouts de rede criam o problema clássico de pull requests duplicados: o servidor pode ter criado o pull request 418, mas o cliente não recebeu a resposta e tenta novamente. Mantenha um registro de idempotência no controlador com o ID da tarefa, o repositório, a branch, o SHA-base e o número do pull request. Em uma nova tentativa, procure a branch e o pull request aberto existente antes de emitir uma chamada de criação.

Não use o título da tarefa como único valor de idempotência. Uma solicitação recorrente como «atualizar a documentação gerada» colidirá com uma execução anterior. O ID da execução deve identificar uma execução específica, enquanto o ID da tarefa ajuda as pessoas a relacionar trabalhos semelhantes.

Pull requests em rascunho são um bom padrão para o trabalho de agentes. Eles avisam aos revisores que a mudança existe, mas ainda não passou pelo critério de conclusão declarado pelo próprio criador. Um agente só pode marcar o pull request como pronto depois que os comandos obrigatórios forem concluídos e o registro da execução contiver seus resultados. Se o repositório não usa rascunhos, aplique um rótulo como agent-created por meio de um controlador confiável, não por meio de texto composto pelo agente.

A atribuição de revisores deve seguir ownership e risco

O primeiro revisor deve vir das regras de ownership do repositório, não de um palpite do agente sobre quem parece saber mais. A documentação do CODEOWNERS do GitHub descreve um mapeamento entre arquivos e responsáveis que pode solicitar revisão para os caminhos alterados. O GitLab oferece mecanismos comparáveis de aprovação e code owners. Esses arquivos são úteis para encaminhar a revisão, mas não tornam a revisão obrigatória automaticamente, a menos que a proteção da branch ou as regras de merge exijam isso.

Essa distinção importa. Um repositório pode mostrar um code owner solicitado e ainda permitir o merge sem a aprovação dessa pessoa, dependendo das configurações. Trate encaminhamento e aplicação da regra como controles separados. Verifique ambos com um pull request de teste deliberadamente não autorizado antes de confiar na política.

Use a lista de arquivos alterados depois do commit final, não os caminhos que o agente planejou modificar. Um patch gerado pode alcançar uma biblioteca compartilhada, um diretório de implantação ou uma pasta de migrações no fim da execução. O cálculo dos revisores precisa considerar o que realmente mudou.

Adicione uma pessoa responsável quando a tarefa afetar áreas em que as regras de ownership sejam amplas demais ou inexistentes. Essa pessoa responde pela intenção da tarefa. Um code owner pode confirmar que a implementação se encaixa em um componente; a pessoa responsável pode confirmar que o comportamento solicitado é adequado ao produto. Não atribua uma dúzia de pessoas apenas porque o diff atravessou limites. Listas grandes de revisores produzem o resultado conhecido em que cada pessoa presume que outra cuidou da parte difícil.

Alguns caminhos devem obrigar um fluxo mais rigoroso. Exemplos incluem migrações de banco de dados, código de autorização, definições de build e release, manifestos de dependências, configurações de infraestrutura e artefatos gerados. A resposta correta nem sempre é «bloquear o agente». Muitas vezes é «exigir o responsável que entende a consequência». Uma migração pode passar nos testes unitários e ainda tornar o rollback impossível.

Atribua revisores pela API somente depois que o pull request existir e verifique a atribuição resultante. Se um grupo responsável não puder receber solicitações, o controlador deve marcar o pull request como bloqueado, em vez de substituir silenciosamente o grupo por um desenvolvedor aleatório. Um fallback silencioso transforma uma regra de ownership em decoração.

Os testes descrevem evidências, enquanto a aprovação decide a aceitação

O agente deve declarar exatamente o que executou, o que não executou e por quê. «Os testes passaram» é uma afirmação inútil sem comandos, código de saída e o SHA do commit testado. Armazene essa evidência também fora do texto do pull request, porque um agente pode editar o texto depois.

Use um pequeno relatório estruturado para cada execução:

{
  "run_id": "run_01J...",
  "repository": "acme/payments-api",
  "head_sha": "8c71...",
  "commands": [
    {"command": "npm test -- payment-retry", "exit_code": 0},
    {"command": "npm run lint", "exit_code": 0}
  ],
  "not_run": ["integration suite requires payment sandbox approval"]
}

O controlador deve rejeitar a transição para pronto quando a evidência indicar um SHA diferente da ponta da branch. Isso captura uma sequência sutil e frequente: o agente executa os testes, faz mais uma «pequena» correção e abre o pull request sem executar nada novamente.

As verificações de status obrigatórias devem continuar no lado do repositório. O agente não pode ter permissão para ignorar verificações, aprovar o próprio pull request, alterar a proteção da branch ou fazer merge. Uma verificação pode confirmar que um comando conhecido passou. Ela não confirma que uma nova regra de autorização está correta, que o requisito foi entendido ou que a tarefa deveria ter sido tentada naquele repositório.

Não deixe um resumo gerado substituir a revisão do diff. Bons resumos ajudam os revisores a se orientar, mas são afirmações feitas pelo autor. Os revisores precisam das mudanças reais nos arquivos, dos testes, do contexto da issue relevante e de quaisquer omissões intencionais.

Toda mudança criada precisa de uma trilha de auditoria que sobreviva a um incidente

Uma URL de pull request não é um registro de auditoria. Ela deixa de funcionar quando os repositórios mudam de lugar, as branches são excluídas, o acesso é alterado ou alguém edita a descrição. Mantenha um registro de eventos somente para anexação que permita ao investigador responder quem iniciou uma execução, qual processo fez cada chamada, qual repositório mudou e o que o sistema retornou.

Registre no mínimo:

• um ID da execução e a referência original da tarefa ou do ticket
• a identidade do bot responsável e a identidade do processo de agente autenticado
• repositório, branch-base, SHA-base, branch de origem e cada SHA de commit criado
• tipo de requisição da API, identificador imutável do pull request, horários e status do resultado
• solicitações de revisão, aprovações, resultados das verificações, eventos de fechamento, merge ou rejeição

Não coloque credenciais em texto puro, arquivos-fonte completos ou prompts arbitrários de tarefas no registro de auditoria por padrão. Investigadores precisam de fatos confiáveis sobre as ações, não de outra cópia descontrolada de material sensível. Se guardar o conteúdo do patch, registre um digest do conteúdo e aplique suas regras normais de retenção e acesso.

Vale preservar a diferença entre um registro de atividade e um registro de decisão. Um registro de atividade diz que uma chamada da API criou o pull request 418. Um registro de decisão diz quem aprovou aquela sessão do agente, quem alterou sua autorização e quem a revogou. Durante um incidente, ambos importam. É preciso saber o que aconteceu e por que o ator tinha autoridade naquele momento.

O Sallyport pode manter sessões de agentes e chamadas HTTP ou SSH individuais em diários projetados a partir de seu registro de auditoria criptografado e encadeado por hashes, e sp audit verify verifica a cadeia offline sobre o texto cifrado. Isso se encaixa em uma configuração na qual o agente solicita uma ação, mas nunca recebe a credencial do repositório.

O encadeamento de hashes torna alterações posteriores detectáveis; ele não torna completo um registro de eventos fraco. Registre as identidades do repositório e dos commits no limite da ação. Um registro perfeitamente verificado de «requisição HTTP enviada» não dirá se a requisição criou o pull request errado.

Mantenha as credenciais fora do agente e separe a criação do merge

O agente nunca deve manter um token amplo do repositório no prompt, no ambiente, em um arquivo do workspace ou na saída de uma ferramenta. Depois que o token entra nesse contexto, ele pode vazar por logs, histórico do shell, mensagens de erro, transcrições copiadas ou uma instrução que convença o agente a imprimi-lo. A remoção posterior não coloca o segredo de volta sob controle de forma confiável.

Use um gateway de ações ou um controlador restrito que aceite uma solicitação específica: criar uma branch neste repositório, enviar estes commits para este prefixo permitido, criar um pull request em rascunho contra esta branch-base aprovada ou solicitar estes revisores. O gateway injeta as credenciais e retorna o resultado. Ele deve rejeitar chamadas que não se encaixem no escopo declarado.

Os direitos de criação e de merge são privilégios diferentes. Um serviço que pode criar um pull request pode ser autorizado a propor milhares de mudanças ruins. Um serviço que pode fazer merge pode colocar uma única mudança ruim em produção. Não combine os dois para tornar uma demonstração mais fluida. Mantenha a ação de merge nas regras de proteção da branch e com uma pessoa responsável, mesmo quando o agente tiver gerado um patch perfeito.

A autorização por execução também é melhor do que um processo de agente permanentemente confiável. Ferramentas de agentes podem iniciar subprocessos, ser reutilizadas em tarefas inesperadas e permanecer ativas depois da tarefa que justificou o acesso. Dê ao processo uma sessão limitada, registre a aprovação e torne a revogação imediata.

Um exercício de falha revela lacunas que o texto da política esconde

Faça um exercício controlado de falha antes de depender da criação automatizada de pull requests. Use um repositório de teste ou uma política de branch descartável e dê ao agente uma tarefa que tente atravessar cada limite. O objetivo é verificar o comportamento de negação e registro, não admirar uma demonstração de caminho feliz.

Comece com um repositório permitido e outro proibido. Confirme que o controlador consegue criar o pull request em rascunho esperado no primeiro e rejeita o segundo antes que qualquer branch apareça. Depois tente enviar alterações para main, fazer force push para uma branch agent/ e abrir um pull request contra uma branch de release não aprovada. Inspecione os eventos do repositório, não apenas as mensagens do controlador.

Em seguida, simule um timeout depois que a requisição de criação chegar à API do repositório. Reinicie a execução e confirme que ela encontra o pull request original em vez de abrir outro. Altere a branch depois de registrar os resultados dos testes e verifique se a transição para pronto para na divergência de SHA.

Por fim, revogue a sessão do agente durante uma execução e tente outra chamada da API. A chamada deve falhar, a negação deve aparecer no registro de decisões e nenhuma credencial deve ficar visível na saída do agente. Se algum desses testes depender de uma pessoa perceber uma mensagem de chat, o controle ainda não existe.

A primeira ação prática é inventariar o token que o agente usa hoje. Liste todos os repositórios que ele pode acessar, todas as branches que pode atualizar e se pode fazer merge ou alterar configurações. A maioria das equipes descobre que o token é mais amplo do que a tarefa. Reduza esse escopo antes de pedir ao agente mais um pull request.