GitHub App

Camada funcional

O GitHub tem um caminho próprio, separado do catálogo geral de integrações: a organização instala um aplicativo do GitHub, escolhe os repositórios que ele alcança e vincula as pessoas. A partir daí o agente pode clonar, ler, criar branch e abrir pull request — agindo como uma identidade definida.

Por que não passa pelo caminho comum

O GitHub tem um modelo de permissão próprio: instalação por organização ou conta, seleção de repositórios, e duas credenciais separadas — a do aplicativo e a de cada pessoa. Isso não cabe no fluxo genérico de conexão usado pelos demais serviços do catálogo, e por isso existe um caminho dedicado.

Autorizar a própria conta e instalar o app são coisas diferentes (23/08/2026)

No GitHub são duas operações distintas, e até 22/08/2026 estavam fundidas num botão só, apontando sempre para a instaladora:

• Instalar o app numa conta depende de permissão de administração NAQUELA conta, e a própria conta pode restringir quem instala. É o que faz o app enxergar repositórios — precisa acontecer uma vez, por organização ou conta pessoal. Quem não tem essa permissão só consegue pedir a instalação a quem administra.
• Autorizar a própria conta não exige nenhuma permissão especial. É o que dá ao agente a permissão de clonar e escrever, e alcança a interseção entre "onde o aplicativo está instalado" e "o que essa pessoa acessa".

Quem não era administrador da organização acabava pedindo a instalação em vez de instalar: o GitHub registrava o pedido e devolvia a pessoa sem autorização nenhuma, e ela ficava travada para sempre num passo que nunca teve permissão de completar — sem nunca chegar ao passo que podia (autorizar). Esse desfecho agora vira uma mensagem própria ("Solicitação enviada aos administradores...") em vez de erro genérico.

O botão "Conectar GitHub" — e o aviso de credencial que aparece na conversa quando falta essa conexão — agora leva direto para a autorização da própria conta. "Instalar em outra conta ou organização" continua disponível como link secundário, para quem precisa trazer uma conta nova ao aplicativo.

Veredito de acesso antes de clonar (23/08/2026)

Antes desta mudança, a única forma de "sem acesso" que a plataforma sabia nomear era "conta não conectada". Qualquer outro motivo — a pessoa não é colaboradora do repositório, o app nunca foi instalado na conta dona dele, ou ela só tem leitura — seguia adiante e quebrava mais tarde: na hora de clonar, como uma falha genérica de comando, ou pior, na hora de publicar as mudanças, depois de o agente já ter feito o trabalho.

Agora a plataforma confere, antes de clonar, o que a conta que assina a conversa pode fazer naquele repositório, e chega a um de quatro vereditos:

O veredito vale por repositório, e o que acontece depois depende do papel de cada um: sem acesso ao principal, o turno de um agente comum é interrompido; sem acesso a um repositório extra, só aquele repositório fica de fora, e o agente é avisado disso.

Os dois vereditos fatais interrompem o turno com uma mensagem nomeando a conta e o repositório, em vez de uma falha genérica na hora de clonar. Para um agente App (Build & Deploy) nenhum dos dois é fatal: a própria provisão do App pode ter acabado de criar o repositório, e um repositório privado recém-criado numa organização legitimamente aparece como inexistente para quem está conversando — ela ainda não é colaboradora dele. Tratar isso como fatal quebraria a provisão normal de um App.

Quando o veredito é de somente leitura, o turno não quebra: o agente é avisado, ANTES de trabalhar, que não pode publicar mudanças naquele repositório e por quê — para ele reportar a saída real ("peça acesso de escrita a um administrador") em vez de uma falha técnica depois do trabalho perdido.

Uma falha da própria conferência — rede indisponível, GitHub fora do ar, excesso de chamadas — nunca derruba o turno: sem veredito, a preparação segue como antes desta mudança. E excesso de chamadas não é tratado como falta de acesso: a conferência separa os dois casos antes de dar o veredito, para não acusar a pessoa de não ter acesso a um repositório que ela acessa.

Escolher o repositório: teto de 200 e busca pelo nome completo (23/08/2026)

A lista de repositórios que a tela oferece traz até 200 — medido em produção, uma conta com 566 repositórios alcançáveis só enxergava os 200 mais recentes, e o filtro por texto roda sobre o que já foi carregado, então um repositório fora do teto ficava invisível mesmo digitando o nome exato. Agora a tela avisa quando a lista veio cortada e convida a digitar o nome completo, no formato dono barra repositório; esse caminho sempre funciona porque busca aquele repositório direto, em vez de depender da lista já carregada.

Como as credenciais são protegidas

As credenciais usadas para agir no GitHub ficam cifradas em repouso e são renovadas automaticamente quando preciso. O agente nunca vê o valor direto — só o efeito de agir com ele.

O retorno da instalação é assinado e verificado, para que ele não possa ser falsificado por um terceiro.

Quando falta credencial no meio de um turno, a conversa mostra uma frase pronta explicando o que falta, em vez do erro técnico cru — que era o que aparecia antes, na faixa de erro da conversa.

Quem age no GitHub: os três modos

Ao ligar essa capacidade, a configuração do agente decide quem assina cada ação feita no GitHub:

• Quem está conversando com o agente no momento.
• O dono do agente.
• Uma pessoa fixa, escolhida na própria configuração.

Essa escolha importa para auditoria: no GitHub, cada commit aparece com um autor, e decidir qual é uma decisão de governança, não de conveniência. Por isso, uma vez definidos, o modo escolhido e a pessoa fixa (quando houver) não podem ser trocados por uma atualização comum de configuração — só na criação do agente, ou por um caminho controlado.

Configuração coesa

Com essa capacidade ligada, pelo menos um repositório passa a ser obrigatório, e o modo de pessoa fixa exige que essa pessoa seja informada. Não há caminho que contorne isso: nem pela tela, nem pela conversa, nem pela API — a configuração incompleta é recusada em vez de salva pela metade.

Atualizado em 25/08/2026: até 24/08/2026 um agente comum trabalhava com um repositório só, e era por isso que a configuração pedia o repositório e a branch. Agora ele trabalha com uma lista de até dez, um deles marcado como principal. A conferência de acesso descrita acima passa a valer para cada repositório da lista, e não uma vez só: um repositório extra sem acesso tira aquele repositório do turno, enquanto o principal sem acesso derruba o trabalho. O modelo completo está na página sobre repositórios de um agente.

Quem depende disso

• Apps (Build & Deploy): o repositório do sistema publicado — continua um só por construção, não passa pela lista.
• Skills: importação a partir de repositório.
• Agentes com repositório de trabalho: clone preparado no início da execução, com a credencial já pronta, sem passar pelo agente — hoje uma lista de até 10, não mais um só. Ver a página sobre os repositórios de um agente.