Configurar a integração com o GitHub

Este guia aborda as partes da configuração específicas do GitHub. O GitHub é um dos três hosts de código suportados — consulte Ligar um host de código para ligar o GitLab ou o Bitbucket e para saber como um espaço de trabalho combina as várias forges.

Pré-requisitos

Uma conta do GitHub com acesso aos repos nos quais quer trabalhar
Uma GitHub App registada para o seu servidor (consulte Criar a GitHub App) para que possa iniciar sessão, ou um token de acesso pessoal com repo e read:org para colar

Iniciar sessão com o GitHub

Um fluxo de dispositivo: o GitHub mostra-lhe um código curto, você aprova-o em github.com e o servidor recebe a credencial — sem URL de callback, sem porta, nada a expor. Disponível sempre que o servidor tenha um id de cliente, que uma compilação oficial já inclui.

Vá a Definições → Espaço de trabalho → Perfil e identidade → Hospedagem de código (ou ao primeiro passo do onboarding)
Na linha GitHub, clique em Entrar com o GitHub
Uma caixa de diálogo mostra um código de oito caracteres e abre github.com/login/device no seu navegador. O código já está na sua área de transferência
Cole-o, aprove a aplicação e volte. A linha passa sozinha para «Ligado como your-username»

Pode fechar a caixa de diálogo enquanto termina no navegador — o servidor continua a sondar até o código expirar (cerca de 15 minutos), pelo que o início de sessão é concluído na mesma.

Ou colar um token

A alternativa quando o servidor não tem app, quando a app não está instalada numa conta de que precisa, ou quando simplesmente prefere usar um PAT.

Vá a Definições → Espaço de trabalho → Perfil e identidade → Hospedagem de código
Na linha GitHub, clique em Adicionar token
Cole um token com repo e read:org (clássico) e guarde. Um token granular precisa de Contents e Pull requests do repositório (leitura e escrita), mais Checks e Actions (leitura).

O token é testado à medida que é guardado, pelo que a linha consegue indicar a conta a que pertence. Clique em Desligar para o remover.

Ponto de verificação: a linha GitHub apresenta «Ligado como your-username». Um sufixo indica a origem quando a credencial que responde não é a sua — «pela aplicação deste servidor» ou «do ambiente».

O que a integração lhe oferece

Funcionalidade	Como
Lista e detalhe de PRs	A API REST do GitHub, a partir do servidor, com a identidade da app ou com a sua própria credencial
Execuções de verificação	A API GitHub Checks
Publicação de revisões	Um passo sujeito a uma ação do utilizador que publica a sua revisão na PR
Registo de repos	Um checkout é aceite se o seu remoto `origin` apontar para github.com — ou para gitlab.com / bitbucket.org
Acesso dos agentes ao GitHub	O intermediário de credenciais injeta um token só de leitura como `GH_TOKEN` / `GITHUB_TOKEN`; os pushes passam pelo Control Center
Sinais de notificação	Uma sondagem do lado do servidor à sua caixa de entrada de notificações do GitHub levanta «mencionado numa pull request» e «revisão solicitada»
Perfis de utilizador	Cartões de perfil ao passar o rato e filtragem de PRs por autor

Alguns caminhos usam a API GraphQL em vez da REST quando é mais barato — a atividade de branches para o seletor de composição de PRs e o estado de revisão em direto que determina se uma notificação de revisão solicitada ainda está pendente.

Estar atento a indisponibilidades do GitHub

A barra de título mostra uma pastilha de estado quando um fornecedor está degradado, abrangendo o GitHub, o Claude, a OpenAI e o Kimi. Está oculta enquanto tudo estiver saudável — a presença assinala problemas, não a sua ausência.

Clique na pastilha para abrir um painel flutuante com o estado de cada fornecedor e um botão de atualização. Os estados são atualizados automaticamente a cada dois minutos.

Saber como os agentes atuam no GitHub

Um agente que trabalha numa worktree do GitHub recebe sempre um token do GitHub só de leitura. Um push passa pelo Control Center, que pergunta à regra Fazer push para um remoto e depois o reencaminha com um token de escrita que o agente nunca detém. Consulte Configurar políticas de sandbox
Os commits criados por um agente são assinados como o agente — o nome apresentado mais (agent), num endereço sintético indexado pelo id do agente — nunca como uma pessoa. A pessoa que o pediu é creditada com um trailer Co-Authored-By
Com uma GitHub App configurada, o intermediário emite, por lançamento, tokens de instalação granulares, limitados ao repo e com cerca de uma hora de duração, em vez de entregar um token amplo. A instalação é resolvida a partir do proprietário do repo da execução, pelo que uma app instalada em várias contas fica corretamente limitada àquela que a execução tocar. Sem app, os agentes recebem o token do ambiente, que não pode ser restringido a só leitura: a regra de push vincula então o git push, mas não código que use o token diretamente
O token é sempre o do intermediário, nunca o do próprio membro que faz o pedido. O token do servidor é retido a uma execução que atua por um membro que não seja o proprietário e não tenha ligado o GitHub

Resolução de problemas

A lista de PRs está vazia e diz que o GitHub não está ligado

Não tem nenhuma credencial do GitHub neste servidor. Inicie sessão ou cole um token em Hospedagem de código. Os repos de outras forges não são afetados — só os do GitHub é que não contribuem em nada.

A linha oferece «Adicionar token» mas não «Entrar com o GitHub»

O servidor não tem id de cliente — o que é o estado normal para uma compilação a partir do código-fonte, já que as credenciais só são integradas em compilações oficiais. Consulte Criar a GitHub App: demora cerca de dois minutos e só o proprietário do servidor tem de o fazer, uma vez.

A caixa de diálogo de início de sessão diz que o fornecedor não devolveu nenhum código de dispositivo

A GitHub App existe, mas a caixa de verificação Device flow está desmarcada. Ative-a nas definições da app (General → Device flow) e tente de novo.

A linha diz «pela aplicação deste servidor» quando eu esperava a minha própria conta

Não iniciou sessão; o que está a ver é a identidade de app do servidor a responder. Clique em Entrar com o GitHub nessa linha.

Um PAT granular não mostra botão de merge nem o estado das verificações

O token precisa de Contents e Pull requests (leitura e escrita), mais Checks e Actions (leitura). Depois de o alterar, cole-o novamente em Hospedagem de código.

Adicionar um repo é rejeitado

O registo exige as três coisas: que o caminho esteja dentro de uma árvore de trabalho git, que tenha um remoto origin e que esse remoto aponte para uma forge suportada (github.com, gitlab.com ou bitbucket.org). Consulte Adicionar repos a um espaço de trabalho.

Tudo deixa de funcionar durante um tempo após uso intenso

Esse é o disjuntor de limite de pedidos. O GitHub assinala o seu limite principal com um 403 que transporta x-ratelimit-remaining: 0 e um momento de reposição; ao ver um, o cliente faz falhar localmente os pedidos seguintes sem qualquer chamada de rede até a janela terminar, para que uma tempestade de novas tentativas não possa agravar o limite. As falhas transitórias são repetidas até três vezes com recuo exponencial, respeitando retry-after.