Falar com o Control Center a partir de uma PR do GitHub

Este guia mostra-lhe como trabalhar com o Control Center sem sair do GitHub: pedir uma revisão com IA a partir da página da PR, fazer uma pergunta ao bot num comentário e manter a conversa a decorrer nas respetivas threads de revisão.

O bot é a GitHub App do seu próprio servidor — a mesma que já permite que as pessoas iniciem sessão e que executa trabalho em segundo plano. Não se regista nada de novo, e nada tem de ser acessível a partir da internet: o servidor descobre o que foi dito no GitHub por sondagem, pelo que um portátil atrás de NAT comporta-se exatamente como uma implementação pública.

Pré-requisitos

O servidor tem a respetiva GitHub App registada e instalada, com Pull requests: read and write (para comentários, threads e reações) e Issues: read (para a pesquisa de comentários). Ambas já constam da lista de permissões desse guia
O repositório está ligado a um espaço de trabalho no Control Center
Sem URL de webhook, sem túnel, sem callback — não há nada para configurar do lado da rede

Descobrir o nome do seu bot

O login do bot é <appslug>[bot], em que appslug é o nome que deu à aplicação quando a registou.

Vá a Definições → Servidor → Início de sessão único e desloque-se até ao cartão Aplicações do fornecedor
Abra o bloco GitHub e clique em Testar
Copie o Login do bot quando for preenchido. Se ainda mostrar a dica de campo vazio, o login é sempre <appslug>[bot] — escreva-o, ou então a forma curta @appslug

O GitHub não oferece contas de aplicação no seu preenchimento automático de @, pelo que o login tem de ser escrito — é por isso que o cartão de definições o torna copiável com um clique. O sufixo [bot] é opcional: tanto @myapp como @myapp[bot] endereçam o bot.

Pedir uma revisão a partir do GitHub

Duas formas, ambas iniciando o mesmo pipeline pr_review predefinido que o botão Ask AI inicia:

Adicione a etiqueta ai-review à PR. É a coisa mais próxima que o GitHub oferece de atribuir o bot como revisor — as contas de aplicação não podem ocupar o lugar nativo de revisor solicitado. Não há comentário a que reagir, pelo que nada é publicado no GitHub; a revisão começa no Control Center
Comente @myapp review (ou apenas @myapp) na conversa da PR. O bot reage com 👀 e depois responde quando a revisão tiver começado (ou que uma já está a correr)

Os revisores trabalham no espaço de revisão da PR; leia e publique as constatações como em Usar revisão com IA. Voltar a publicar no GitHub continua a ser uma decisão que toma no Control Center — iniciar uma revisão a partir do GitHub não publica nada no GitHub por si só.

A etiqueta dispara uma vez por PR: adicioná-la é o pedido, e não é rearmada quando é removida e adicionada de novo. Para executar uma revisão outra vez — depois de um push, por exemplo — mencione o bot.

Fazer uma pergunta

Comente na conversa da PR:

@myapp why does the flaky test in runner_test.dart fail on CI but not locally?

O que acontece, por ordem:

O bot reage com 👀 para que saiba que o comentário foi visto
A pergunta é publicada no espaço de revisão da PR em seu nome — a mesma atribuição que se a tivesse escrito no Control Center
Um agente responde no espaço, e a resposta é publicada de volta na PR como um comentário que o menciona com @

Uma pergunta numa PR que ainda não tem revisão acorda o agente CEO do espaço de trabalho; depois de uma revisão ter sido executada, responde o agente que falou por último, pelo que as mensagens de seguimento chegam a quem tem o contexto.

Continuar uma conversa numa thread de revisão

Responda dentro de uma thread de revisão inline da qual o bot faça parte — um comentário de diff que tenha deixado, ou uma resposta que tenha publicado nessa thread. Não é necessária nenhuma menção; a thread é o endereçamento:

> @myapp the retry loop looks O(n²) to me

what would the complexity be with the bounded queue instead?

Os vários turnos funcionam da mesma forma: cada resposta é outra pergunta na mesma conversa, com o espaço de revisão como contexto, e a resposta volta na thread.

Um seguimento na cronologia da conversa da PR é um novo comentário de nível superior, pelo que continua a precisar de uma menção com @.

Com quem o bot fala

Um comentário do GitHub chega com pouco mais do que um login, pelo que o bot resolve o autor antes de fazer seja o que for:

A sua conta do GitHub tem de estar ligada à sua identidade no Control Center — inicie sessão com o GitHub, ou cole um token, em Definições → Espaço de trabalho → Perfil e identidade → Hospedagem de código
Tem de ser membro com um papel de escrita (member, admin ou owner) no espaço de trabalho que liga o repositório

Qualquer outra pessoa recebe uma única resposta educada a explicar o que falta — um login desconhecido (não ligado, ou ligado mas não membro aqui) e um papel só de leitura são os dois casos — e as suas palavras nunca entram no espaço de trabalho. A etiqueta ai-review não é condicionada desta forma: não tem autor, pelo que inicia a revisão no espaço de trabalho que já liga o repositório.

O que esperar

Aspeto	Comportamento
Reconhecimento	👀 num comentário dentro de cerca de um minuto — o intervalo de varredura. A etiqueta `ai-review` não tem comentário a que reagir
Respostas	Publicadas como o bot (a aplicação), no canal onde a pergunta foi feita
Atribuição no espaço	A pergunta é sua; o agente corre em seu nome, de acordo com as definições de autonomia do espaço
Revisões	As constatações ficam no espaço de revisão; publicar no GitHub é manual

A latência de cerca de um minuto é o preço a pagar por não precisar de qualquer acesso de rede de entrada. Nada na varredura é urgente, e nada se perde enquanto o servidor estiver offline — um comentário que chega durante uma paragem é apanhado na varredura seguinte.

Resolução de problemas

Não acontece nada num comentário que menciona o bot.

A aplicação está instalada na conta que é proprietária do repositório, e o repositório está ligado a um espaço de trabalho? Um repositório não ligado é ignorado antes de algo ser registado, pelo que ligá-lo mais tarde ainda faz a entrega
A sua conta do GitHub está ligada, e é membro com um papel de escrita? Verifique na PR a resposta de recusa do bot — indica qual dos casos é
Continua sem acontecer nada? O registo do servidor indica a varredura e a PR quando algo falha; procure pr_conversation: (o componente de sondagem) e github_pr_conversation: (a ponte)

A etiqueta não inicia uma revisão.

Dispara uma vez por PR. Se já correu uma revisão, ou se a etiqueta foi adicionada antes de o servidor ter visto a PR (a primeira varredura registra o trabalho acumulado em silêncio em vez de o desencadear de uma só vez), mencione antes o bot — @myapp review inicia sempre uma, a menos que já esteja uma revisão em curso.

A resposta do bot nunca chegou ao GitHub.

A resposta em si nunca se perde — está no espaço de revisão da PR no Control Center. Uma falha de publicação (GitHub em baixo, permissões alteradas) é registada e a resposta não é repetida; volte a perguntar na thread se for importante.

Guias relacionados

Criar a GitHub App: o registo de onde nasce o bot
Usar revisão com IA: ler as constatações que uma revisão iniciada por menção produz
Configurar a integração com o GitHub: ligar a sua própria conta do GitHub, que é por onde o bot o resolve
Usar espaços: a sala onde tudo isto acaba