Configurar a integração com o GitHub

Este guia cobre as partes da configuração específicas do GitHub. O GitHub é um dos três hosts de código compatíveis — veja Conectar um host de código para conectar o GitLab ou o Bitbucket, e para saber como um espaço de trabalho combina os três.

Pré-requisitos

Uma conta do GitHub com acesso aos repos em que você quer trabalhar
Ou um GitHub App registrado para o seu servidor (veja Criar o GitHub App) para você poder entrar, ou um token de acesso pessoal com repo e read:org para colar

Entrar com o GitHub

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

Abra Configurações → Espaço de trabalho → Perfil e identidade → Hospedagem de código (ou a primeira etapa da configuração inicial)
Na linha GitHub, clique em Entrar com 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 o app e volte. A linha muda sozinha para “Conectado como seu-nome-de-usuário”

A caixa de diálogo pode ser fechada enquanto você termina no navegador — o servidor continua consultando até o código expirar (cerca de 15 minutos), então o login ainda se conclui.

Ou cole um token

A alternativa quando o servidor não tem app, quando o app não está instalado em uma conta de que você precisa ou quando você simplesmente prefere usar um PAT.

Abra Configuraçõ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 salve. Um token granular precisa, no repositório, de Contents e Pull requests (leitura e escrita), além de Checks e Actions (leitura).

O token é testado no momento em que é salvo, então a linha consegue nomear a conta à qual ele pertence. Clique em Desconectar para removê-lo.

Ponto de verificação: a linha GitHub mostra “Conectado como seu-nome-de-usuário”. Um sufixo nomeia a origem quando a credencial que responde não é a sua — “pela app deste servidor” ou “do ambiente”.

O que a integração oferece

Recurso	Como
Lista e detalhe de PRs	A API REST do GitHub, a partir do servidor, com a identidade do app ou com a sua própria credencial
Execuções de verificação	A API Checks do GitHub
Publicação de revisões	Uma etapa que exige ação do usuário e publica a sua revisão na PR
Registro de repos	Um checkout é aceito se o remote `origin` dele apontar para github.com — ou para gitlab.com / bitbucket.org
Acesso dos agentes ao GitHub	O broker de credenciais injeta um token somente leitura como `GH_TOKEN` / `GITHUB_TOKEN`; os pushes passam pelo Control Center
Avisos de notificação	Uma consulta periódica, no servidor, à sua caixa de notificações do GitHub gera “Mencionado em um pull request” e “Revisão solicitada”
Perfis de usuário	Cartões de perfil ao passar o cursor e filtragem de PR por autor

Alguns caminhos usam a API GraphQL em vez da REST quando ela é mais econômica — a atividade de branches do seletor de composição de PR e o estado de revisão ao vivo que decide se uma notificação de revisão solicitada ainda está pendente.

Fique atento a quedas do GitHub

A barra de título mostra um chip de status quando um provedor está degradado, abrangendo GitHub, Claude, OpenAI e Kimi. Ele fica oculto enquanto tudo está saudável — a presença indica problema, não a ausência dele.

Clique no chip para abrir um flyout com o estado de cada provedor e um botão de atualização. Os status se atualizam sozinhos a cada dois minutos.

Saiba como os agentes agem no GitHub

Um agente que trabalha em uma worktree do GitHub sempre recebe um token do GitHub somente leitura. Um push passa pelo Control Center, que pergunta à regra Fazer push para um remoto e depois o encaminha com um token de escrita que o agente nunca tem. Veja Configurar políticas de sandbox
Os commits que um agente faz são atribuídos como o agente — o nome de exibição mais (agent), em um endereço sintético indexado pelo id do agente — nunca como um humano. Quem pediu é creditado com um trailer Co-Authored-By
Com um GitHub App configurado, o broker emite tokens de instalação granulares, com escopo de repo e cerca de uma hora de validade, a cada lançamento, em vez de entregar um token amplo. A instalação é resolvida a partir do proprietário do repo da execução, então um app instalado em várias contas se limita corretamente àquela que a execução tocar. Sem um app, os agentes recebem o token do ambiente, que não pode ser restrito a somente leitura: a regra de push então vincula o git push, mas não um código que use o token diretamente
O token é sempre o do broker, nunca o próprio do membro solicitante. O token do servidor é retido de uma execução que age por um membro que não é o proprietário e não conectou o GitHub

Solução de problemas

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

Você não tem credencial do GitHub neste servidor. Entre ou cole um token em Hospedagem de código. Os repos dos outros forges não são afetados — só os do GitHub não contribuem com nada.

A linha oferece “Adicionar token” mas não “Entrar com GitHub”

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

O GitHub App existe, mas a caixa Device flow dele está desmarcada. Ative-a nas configurações do app (General → Device flow) e tente de novo.

A linha diz “pela app deste servidor” quando eu esperava a minha própria conta

Você não entrou; o que você está vendo é a identidade do app do servidor respondendo. Clique em Entrar com GitHub nessa linha.

Um PAT granular não mostra botão de merge nem status de verificação

O token precisa de Contents e Pull requests (leitura e escrita), além de Checks e Actions (leitura). Depois de alterá-lo, cole-o de novo em Hospedagem de código.

Adicionar um repo é rejeitado

O registro exige as três condições: o caminho está dentro de uma árvore de trabalho do git, ele tem um remote origin e esse remote aponta para um forge compatível (github.com, gitlab.com ou bitbucket.org). Veja Adicionar repos a um espaço de trabalho.

Tudo para de funcionar por um tempo depois de uso intenso

Esse é o disjuntor de limite de taxa. O GitHub sinaliza o limite primário com um 403 que traz x-ratelimit-remaining: 0 e um horário de redefinição; ao ver um, o cliente faz as próximas solicitações falharem localmente, sem chamada de rede, até a janela passar, para que uma tempestade de tentativas não aprofunde o limite. Falhas transitórias são repetidas até três vezes com backoff exponencial, respeitando retry-after.