Pular para o conteúdo

Do ticket ao pull request revisável

Code Automation · Agentes de código e automação de PR

Você escreve o ticket com o critério de aceite; a IA sugere um plano que uma pessoa aprova, escreve o diff, e o executor isolado aplica a mudança e roda os testes do seu repositório. O resultado é uma proposta com hash, revisada por outra pessoa, entregue como patch ou como pull request em rascunho.

O problema

O que este produto resolve

Boa parte do trabalho de manutenção é previsível: atualizar dependência, ajustar configuração, corrigir o mesmo tipo de falha, incluir o teste que faltava.

Assistentes de código ajudam quem está no editor, mas não pegam um ticket e devolvem uma mudança testada, com evidência, pronta para outra pessoa revisar.

E quando um agente escreve código sem trava, ninguém sabe dizer que arquivos ele podia tocar, onde o código rodou e quem aprovou o quê.

atualizado em

Quem usa e para quê

Perfis típicos, sem nomes de clientes. Cada uso leva o status da funcionalidade que o atende.

  • Time de manutenção de um sistema legadoTransformar atualizações de dependência e ajustes repetitivos em mudanças testadas e prontas para revisar.Ticket to PR
  • Liderança técnicaLiberar o time de tarefas previsíveis sem abrir mão de aprovar o plano e revisar cada proposta.Ticket to PR
  • Time de QALevar um teste novo ao repositório por um ticket, com patch testado e revisão de outra pessoa.Ticket to PR

Funcionalidades

O que o produto faz

Contratação pela conta, em autoatendimento.

  • Ticket to PR

    Ticket manual → plano sugerido pela IA e aprovado por uma pessoa → diff validado (só arquivos do plano, sem workflows nem segredos) → aplicação e testes do repositório no executor isolado → proposta com hash revisada por outra pessoa → patch para git apply. PR em rascunho só com a credencial de escrita do workspace e a criação de PR ligada; nada é mesclado. O ticket nasce na tela, pela API da sessão ou de outros produtos (teste aceito, flag a remover, drift de IaC); GitHub Issues e Jira não viram ticket.

  • Code context and verification

    Índice de código por repositório enviado pelo CI, com busca para pessoas e agentes; verificação de cada execução com checks e evidências (logs, capturas, traces); aprovação automática opcional de mudança de risco baixo, que o workspace precisa ligar, nunca em branch de produção sem regra explícita; aceitar não cria PR nem mescla.

  • Code experts and event-driven flows

    Dois experts de engenharia instaláveis: Revisor de código (diff contra os padrões do time e a documentação do repositório) e Verificador de mudança (promessa do PR contra diff e testes). Fluxos que rodam por evento do workspace (PR, achado, alerta, incidente, decisão de política) e que podem ser exportados e importados como documento JSON aiuby.flow/v1 para versionar no Git.

Como funciona

Do começo ao registro

  1. Ticket

    Título, descrição, critério de aceite, repositório, branch base, imagem de execução e comando de teste.

  2. Plano aprovado

    A IA lê a lista de arquivos, o README e o manifesto e sugere um plano com até 12 arquivos. Uma pessoa aprova, com justificativa e o hash do que viu.

  3. Diff validado

    A IA escreve o diff e a plataforma confere antes de rodar: só arquivos do plano, sem workflows, sem segredo, aplicando limpo na base.

  4. Executor isolado

    Clone raso, git apply e os testes do repositório, rodando sem nenhum token. O diff final é capturado antes dos testes.

  5. Proposta revisada

    Passou: nasce uma proposta com hash, evidência e fatos de segurança do diff. Quem pediu o patch não decide.

  6. Verificação

    Cada execução ganha um veredito com os checks do executor e os do seu CI, com links para a evidência.

  7. Entrega

    Patch para git apply ou pull request em rascunho, numa branch nova sobre o commit testado. O merge é do seu time.

Funcionalidades

Funcionalidade por funcionalidade

O que cada uma faz, como funciona, um exemplo tirado da documentação e o que ela não faz. O selo de cada bloco vem do catálogo.

Ticket to PR

Um pedido escrito vira mudança testada, pronta para revisão.

O Ticket to PR conduz uma tarefa de código do pedido até a entrega em seis etapas com dono definido: ticket, plano, patch, execução, proposta e entrega. A IA sugere o plano e escreve o diff; a plataforma valida cada saída antes de qualquer execução; o executor isolado aplica o patch e roda os testes do próprio repositório; e duas pessoas diferentes decidem, uma sobre o plano e outra sobre a proposta final.

O que sai no fim é um patch para git apply, com hash conferível, ou um pull request em rascunho numa branch nova criada sobre o commit testado. O merge fica sempre com o seu time.

Como funciona

  • Ticket com título, descrição, critério de aceite, repositório do workspace, branch base, imagem de execução (node22, python312 ou go126), comando de preparação opcional e comando de teste. Além da tela e da API, outros produtos abrem tickets com o pedido pronto: o .spec.ts de um teste aceito no Test Automation, a remoção de uma flag velha no Feature Management e a correção de um drift de IaC detectado pelo Software Delivery.
  • Plano em JSON com até 12 arquivos (modificar, adicionar ou excluir), passos, testes e riscos. Cada caminho é conferido contra a árvore do repositório, o plano grava um sha256 e espera a aprovação de uma pessoa, com justificativa e o hash que ela viu.
  • Diff validado antes de rodar: até 24 KB e 20 arquivos, só arquivos do plano, sem .github/workflows, .env, chaves, credenciais ou .git, sem segredo nas linhas novas, sem binário, renomeação, link simbólico ou mudança de modo, e aplicando limpo na base lida do GitHub.
  • Execução no executor isolado: clone raso, git apply, captura do diff final antes dos comandos do repositório e testes rodando sem nenhum token. O retorno volta assinado, com segredo derivado só daquela execução.
  • Proposta com hash, evidência e histórico no catálogo de agentes, acompanhada de fatos de segurança extraídos do diff (segredo, TLS desligado, eval, shell, SQL concatenado, hash fraco, CORS aberto). Quem pediu o patch não decide a proposta.
  • Laço limitado por ticket: 3 iterações por padrão (teto de 5), orçamento de IA por ticket, uma iteração por vez e um patch por plano. Um plano novo recebe o motivo da falha anterior.
Pela API As rotas de sessão seguem a ordem do fluxo: ticket, plano, decisão do plano, patch, diff, decisão da proposta e PR em rascunho. A rota da API v1 só lê o estado do laço.
POST /api/platform/code-automation/tickets
POST /api/platform/code-automation/tickets/<id>/plan
POST /api/platform/code-automation/plans/<id>/decision      {decision, reason, sha256}
POST /api/platform/code-automation/tickets/<id>/patch
GET  /api/platform/code-automation/runs/<id>/patch          (diff, cabeçalho x-aiuby-sha256)
POST /api/platform/agent-catalog/proposals/<id>/decision
POST /api/platform/code-automation/runs/<id>/pull-request

GET  /api/v1/code-automation/tickets                        (chave com engineering:read)

O que não faz

  • Não recebe tickets do GitHub Issues nem do Jira: a entrada é a tela, a API da sessão ou outro produto da AIUBY.
  • Não mescla, não força push e não reaproveita branch. O PR em rascunho depende da criação de PR ligada e da credencial de escrita do workspace; sem elas, a entrega é o patch.
  • Não faz busca semântica no código: o plano lê a árvore, o README e o manifesto, e o modelo recebe arquivos inteiros, dentro de tetos de tamanho. Repositórios grandes podem pedir tickets menores.
  • O teste é o comando declarado do repositório, sem relatório JUnit nem cobertura; os fatos de segurança vêm de regras fixas sobre o diff, não dos scanners do executor; e o PR grava arquivos com modo 100644, então um script executável alterado perde o bit de execução.

Code context and verification

Agentes que conhecem o código e mudanças com prova.

O contexto de código dá ao Code Automation o que um revisor espera: um índice do repositório para achar onde mexer, a prova de que a mudança funciona e uma regra clara para o que pode seguir sem a segunda pessoa.

A aprovação automática é opcional: nasce desligada, o workspace decide se liga e define o alcance. Mesmo ligada, ela só vale para risco baixo calculado por regra fixa, nunca toca branch de produção sem uma regra explícita do cliente e só registra o aceite da proposta. O pull request continua sendo pedido por uma pessoa, e o merge é do seu time.

Como funciona

  • Índice por repositório: o CI envia os arquivos de um commit e a plataforma guarda caminho, linguagem, símbolos (funções, classes, tipos, recursos de Terraform) e o conteúdo, com busca de texto para pessoas e agentes.
  • Verificação com evidência: cada execução ganha um veredito com os checks do executor (código de saída e duração de cada step, segurança do diff) e, quando o seu CI envia, os checks dele com links para log, captura de tela, trace e ambiente de revisão.
  • Aprovação automática opcional: com a política ligada, uma proposta de risco baixo, dentro do limite de arquivos e linhas, nos caminhos e branches liberados e com verificação aprovada, é aceita sem a segunda pessoa.
  • Branch de produção (main, master, production, release) fica fora da aprovação automática, salvo regra explícita marcada pelo cliente.
  • Aceite automático fica no histórico da proposta e na auditoria, em nome de system:auto-approval e com o motivo; o PR em rascunho continua sendo pedido por uma pessoa.

Exemplo de uso

O time liga a política só para a pasta docs/ na branch develop, com até três arquivos e cinquenta linhas. Uma correção de texto pedida num ticket passa nos testes do executor e é aceita sozinha, com o veredito e os logs anexados; uma mudança no código de pagamentos, de risco médio, continua esperando a revisão de outra pessoa.

O que não faz

  • Não mescla pull request e não cria PR sozinho: aceitar registra a decisão da proposta.
  • O índice não lê o GitHub por conta própria: quem envia os arquivos é o CI do cliente, até 64 KiB por arquivo.
  • A política nasce desligada e nunca vale para risco médio ou alto; o risco vem de uma regra fixa sobre o diff, sem modelo.
  • Não sobe o ambiente de revisão do PR nem tira capturas por conta própria: os links de evidência vêm do CI do cliente.

Code experts and event-driven flows

Revisão de apoio, verificação com evidência e automação por evento.

Dois experts de engenharia se instalam pelo catálogo de soluções, sobre a documentação dos repositórios que o Cortex indexa e os padrões que o time escreve. O Revisor de código recebe um diff colado e aponta cada problema com arquivo, linha, a regra e a fonte, como bloqueante ou sugestão. O Verificador de mudança recebe a promessa do PR, o diff e o resultado dos testes e dá um veredito por promessa: verificada, falhou ou insuficiente.

Os fluxos de agentes que automatizam a engenharia ganham dois recursos. Um fluxo publicado pode rodar por evento do workspace, como um PR aberto, um achado novo, um alerta, um incidente ou uma decisão de política, com o evento como entrada. E cada fluxo pode ser exportado como documento JSON aiuby.flow/v1, com chaves ordenadas e hash, para versionar no Git, e importado de volta como fluxo novo em rascunho.

Como funciona

  • Experts que só leem: buscam nas bases de conhecimento, citam a base e o título de cada regra usada e tratam diff, log e descrição colados como dado não confiável.
  • Segredo no texto colado é apontado pela linha, sem repetir o valor. Log cortado nunca vira "verificada".
  • Cada expert vem com base de exemplo, marcada como fictícia, e suíte de avaliação, e nasce em rascunho para o time ajustar.
  • Gatilho por tipo de evento: uma execução por evento, até 30 por hora por gatilho, em nome de quem criou o gatilho; evento de fluxo não dispara fluxo.
  • Documento importado não publica sozinho: a publicação confere o grafo e as referências do workspace de destino.

Exemplo de uso

A líder técnica instala o Revisor e escreve na base de padrões que SQL concatenado e catch vazio são bloqueantes. Antes de abrir o PR, quem desenvolve cola o diff e recebe os dois bloqueios com a regra citada. Um fluxo disparado a cada achado novo passa o achado ao agente de triagem do time, e o documento desse fluxo fica versionado no repositório da plataforma.

O que não faz

  • Os experts não comentam no PR, não aprovam e não leem o PR sozinhos: a pessoa cola o conteúdo.
  • O gatilho escolhe o tipo de evento, sem filtro pelo conteúdo, e é configurado pela API da plataforma.
  • O documento do fluxo é JSON: não há YAML, CLI nem sincronização automática com o repositório.

IA e limites

O que a IA faz aqui, e o que nunca faz sozinha

Faz

  • Sugere o plano: arquivos a modificar, adicionar ou excluir, passos, testes e riscos.
  • Escreve o diff unificado a partir do plano aprovado e do conteúdo dos arquivos.
  • Recebe o motivo da falha anterior quando um plano novo é aberto para o mesmo ticket.
  • Como Revisor de código e Verificador de mudança, aponta problemas e dá veredito com a regra e a fonte citadas, sobre o que a pessoa colou.

Não faz

  • Não roda nada sem plano aprovado por uma pessoa.
  • Não toca em arquivo fora do plano, em workflows de CI, em .env, chaves ou credenciais.
  • Não aprova a própria proposta, não mescla, não força push e não reaproveita branch.
  • Não recebe token nenhum durante a execução dos testes.

Governança e segurança

Regras que o código impõe

  • Quatro olhos: uma pessoa aprova o plano e outra decide a proposta; quem pediu o patch não decide. A exceção é a aprovação automática opcional de risco baixo, que o workspace liga e delimita por arquivos, linhas, caminhos e branches, nunca em branch de produção sem regra explícita, e que só registra o aceite: o PR continua pedido por uma pessoa.
  • Plano e proposta têm sha256: a decisão vale para o conteúdo que a pessoa viu.
  • O diff é validado antes de qualquer execução (tamanho, arquivos do plano, caminhos proibidos, segredo nas linhas novas); recusado, nada vai ao executor.
  • Os testes rodam no executor isolado, sem token e fora da infraestrutura da aplicação; o retorno é assinado com segredo derivado só daquela execução.
  • Laço limitado: 3 iterações por ticket por padrão (teto de 5), orçamento de IA por ticket e teto diário de execuções por workspace.
  • Kill switch da governança recusa plano, patch, despacho e PR, e cancela a execução em andamento.
  • A credencial de escrita é fine-grained, cifrada, nunca volta em resposta, log ou auditoria e nunca vai ao executor; a política code.pull_request.create é avaliada e gravada antes do PR.

Integrações

Com o que se conecta

Só integrações que existem no código. Cada uma leva o status da funcionalidade que a usa.

  • GitHubLeitura do repositório pela API, com o token só leitura do workspace quando é privado, e pull request em rascunho com a credencial de escrita.Ticket to PR
  • Imagens node22, python312 e go126Ambientes do executor isolado em que o patch é aplicado e os testes do repositório rodam.Ticket to PR
  • Gateway de modelosPlano e diff são pedidos ao modelo pelo Gateway: custo medido, orçamento, política e mascaramento de dado sensível.Ticket to PR
  • Políticas e kill switchA política code.pull_request.create e o kill switch da organização valem para plano, patch, despacho e PR.Governance & policies
  • API v1Leitura do estado do laço de cada ticket com uma chave de escopo engineering:read.API, CLI & keys
  • CI do clienteO CI envia o índice de código do commit e os próprios checks, com links para log, captura, trace e ambiente de revisão.Code context and verification
  • Catálogo de soluçõesRevisor de código e Verificador de mudança se instalam como experts sobre a documentação que o Cortex indexa.Code experts and event-driven flows

Perguntas frequentes

Respostas diretas

O que já dá para usar hoje?

Disponível: Ticket to PR, Code context and verification, Code experts and event-driven flows. Contratação pela conta, em autoatendimento.

Um agente pode fazer merge sozinho?

Disponível: Ticket to PR. Não. A entrega é um patch para git apply ou um pull request em rascunho numa branch nova. Nada é mesclado, nenhum push é forçado e nenhuma branch é reaproveitada; o merge é sempre de uma pessoa do seu time.

Onde o código é alterado e testado?

Disponível: Ticket to PR. Num executor isolado, fora da infraestrutura da aplicação. Ele faz um clone raso, aplica o patch, captura o diff final antes de rodar os comandos do repositório e roda os testes sem nenhum token. O que é revisado é o diff capturado, não o que os testes possam ter alterado depois.

Que arquivos a IA pode tocar?

Disponível: Ticket to PR. Só os arquivos do plano que uma pessoa aprovou, até 12 por plano. A plataforma recusa .github/workflows, .env, chaves, credenciais e .git, e também diff com segredo nas linhas novas, binário, renomeação, link simbólico ou mudança de modo.

O ticket vem do GitHub Issues ou do Jira?

Disponível: Ticket to PR, AI test authoring, Release monitor and flag cleanup. Não. O ticket é escrito na tela ou criado pela API da sessão, com título, descrição e critério de aceite. Outros produtos da AIUBY também abrem tickets com o pedido pronto: o Test Automation, para incluir o .spec.ts de um teste aceito; o Feature Management, para tirar do código uma flag que serve uma variante só; e o Software Delivery, para corrigir um drift de IaC.

Alguma mudança é aceita sem a segunda pessoa?

Disponível: Code context and verification. Só se o workspace ligar a aprovação automática, que é opcional. Com ela ligada, uma proposta de risco baixo, dentro do limite de arquivos e linhas, nos caminhos e branches liberados e com a verificação aprovada, é aceita sem a segunda pessoa, com o motivo na auditoria. Risco médio ou alto nunca entra, branch de produção só com regra explícita, e aceitar não cria PR nem mescla.

Preciso dar acesso de escrita ao meu repositório?

Disponível: Ticket to PR. Não para receber o patch: o download para git apply não depende de credencial de escrita. O pull request em rascunho exige a criação de PR ligada e uma credencial de escrita fine-grained do workspace, cifrada, diferente do token de leitura, que nunca vai ao executor.

Quanto custa?

Disponível: Ticket to PR. Não há preço definido para o produto. O consumo de IA de cada ticket é medido pelo Gateway e limitado por um orçamento por ticket. Quando houver preço, ele aparece na página de Preços.

Funciona junto com

  • AI EngineeringA mudança testada vira uma proposta no catálogo de agentes, com hash, evidência e histórico, e as chamadas ao modelo passam pelo Gateway, com orçamento e política do workspace.
  • Cost ManagementO gasto de IA de cada ticket é medido pelo Gateway e entra no mesmo consumo de IA que o workspace acompanha.

Code Automation

Contratação pela conta, em autoatendimento.