Skip to main content
A integração com o GitHub conecta sua conta do GitHub ao Orkestral para que sua equipe de agentes possa clonar repositórios, abrir pull requests, listar e ler PRs, e publicar code reviews com comentários inline. Você conecta uma única vez com um login de dispositivo seguro. O Orkestral armazena o token de acesso criptografado na sua máquina e nunca o grava em texto puro no disco.
O GitHub é uma integração local-first. Seu token fica em ~/.orkestral, criptografado pelo keychain do seu sistema operacional. Nenhum serviço de nuvem do Orkestral o acessa.

​
O que ela habilita

Repositórios

Liste repositórios que você possui, dos quais é colaborador ou que acessa por meio de uma organização, e clone-os como sources.

Pull requests

Liste pull requests abertos e recentes de um repositório, e crie novos pull requests a partir de uma branch.

Code review

Leia o diff de um pull request e publique um review com um resumo e comentários inline em linhas específicas.

Auth segura

Login via Device Flow sem client secret. O token é criptografado em repouso e removido de logs e mensagens de erro.

​
Requisitos

  • Uma conta do GitHub com acesso aos repositórios em que você quer trabalhar.
  • Um keychain do sistema operacional disponível para o safeStorage do Electron. No macOS, no Windows e na maioria dos desktops Linux ele está presente por padrão. Se estiver ausente, a conexão falha com um erro de criptografia.
  • git instalado e no seu PATH. O Orkestral executa git clone ao clonar um repositório.
  • Acesso de rede a github.com e api.github.com.
O OAuth App padrão solicita estes escopos:

​
Como conectar

O Orkestral usa o GitHub OAuth Device Flow. Você autoriza o Orkestral no github.com inserindo um código curto, então nenhuma senha ou secret jamais passa pelo app.
1

Inicie a conexão

Abra a integração com o GitHub nas configurações e escolha conectar. O Orkestral solicita um código de dispositivo e mostra um user code mais um link de verificação.
2

Autorize no GitHub

O Orkestral abre seu navegador na página de verificação. Insira o user code e então aprove os escopos solicitados para sua conta.
3

Aguarde a confirmação

O Orkestral consulta o GitHub em segundo plano. Quando você aprova, ele busca seu perfil, criptografa o token e armazena a conta. O painel passa a mostrar seu login, nome de exibição e avatar.
O código de dispositivo expira após uma janela fixa (o GitHub retorna o tempo limite quando o fluxo começa). Se ele expirar antes de você aprovar, inicie a conexão novamente para obter um código novo.

​
Clonando um repositório

Quando você clona um repositório como source, o Orkestral executa git clone com o token armazenado injetado apenas para esse único comando:
  • O token é passado por um http.extraHeader em memória (Authorization: Basic com x-access-token), de modo que ele nunca é gravado no .git/config do repositório clonado.
  • GIT_TERMINAL_PROMPT=0 é definido, então o git nunca trava em um prompt de senha interativo.
  • O progresso do clone é transmitido de volta para a UI.
  • Quaisquer credenciais são removidas da saída de erro antes que ela seja exibida para você.
​
string
Branch opcional para fazer checkout. Quando omitida, o git clona a branch padrão do repositório.
​
number
Profundidade de clone opcional. Quando definida como um número positivo, o Orkestral executa um clone raso (--depth) por velocidade. Você pode buscar o histórico completo depois, se precisar. Quando omitida, o clone é completo.

​
Pull requests e reviews

Uma vez conectado, os agentes e o ferramental de review podem usar estas capacidades contra qualquer repositório que você possa acessar:

​
Comentários de review e eventos

Um review publicado carrega um body de resumo de nível superior e zero ou mais comentários inline. Cada comentário inline aponta para um caminho de arquivo, uma linha e um lado do diff.
​
'LEFT' | 'RIGHT'
padrão:"RIGHT"
Em qual lado do diff o comentário se fixa. RIGHT é a nova versão do arquivo; LEFT é a versão antiga.
​
'COMMENT' | 'APPROVE' | 'REQUEST_CHANGES'
padrão:"COMMENT"
O veredito de review que o GitHub registra. COMMENT deixa feedback sem veredito, APPROVE aprova o PR e REQUEST_CHANGES o bloqueia.
​
boolean
padrão:"false"
Ao criar um pull request, abre-o como draft em vez de um PR pronto para review.

​
Capacidades e limites

  • A listagem de repositórios retorna no máximo 500 repositórios (5 páginas de 100). Se você tiver mais, os que receberam push mais recentemente vêm primeiro.
  • A listagem de pull requests retorna no máximo 1000 PRs (10 páginas de 100), com a atividade mais recente primeiro.
  • O clone é raso apenas quando você passa uma profundidade; caso contrário, ele puxa o histórico completo.
  • O token é criptografado com o keychain do sistema operacional. Se o keychain estiver indisponível, tanto a conexão quanto qualquer ação que use o token falham com um erro de criptografia claro.
  • O Orkestral conversa com a API REST do GitHub fixada na versão 2022-11-28.
Desconectar uma conta exclui o token armazenado dela. Clonar, listar, criar PRs e publicar reviews param de funcionar até você reconectar.

​
Configuração

​
string
Variável de ambiente que sobrescreve o client ID do OAuth App empacotado. Defina-a quando quiser rodar o Device Flow contra o seu próprio GitHub OAuth App (útil para desenvolvimento). Seu app precisa ter Enable Device Flow ativado.
Para revisar ou revogar o acesso do Orkestral pelo GitHub, abra a página de configurações do aplicativo OAuth do app conectado. O Orkestral pode abrir essa página para você; ela aponta para github.com/settings/connections/applications/<client id>.

​
Solução de problemas

Isso acontece com um client ID personalizado cujo OAuth App não permite o Device Flow. Vá em github.com/settings/applications, abra o app, marque Enable Device Flow e salve. O client ID padrão do Orkestral já tem isso habilitado.
O GitHub rejeitou o client ID (incorrect_client_credentials ou invalid_client). Verifique ORKESTRAL_GITHUB_CLIENT_ID. O OAuth App precisa existir e o ID precisa corresponder exatamente. Remova a variável para voltar ao app empacotado.
O código de dispositivo expirou. Inicie a conexão novamente para obter um user code novo e então aprove-o prontamente no GitHub.
Você recusou a autorização no GitHub ou aprovou uma conta diferente. Reinicie a conexão e aprove com a conta correta.
Seu sistema operacional não expôs um keychain utilizável, então o Orkestral não consegue criptografar ou descriptografar o token. Isso é comum em configurações Linux mínimas sem um serviço de secrets. Instale ou desbloqueie um keychain (por exemplo o GNOME Keyring) e então reconecte.
Confirme que o git está instalado e no seu PATH, que você ainda tem acesso ao repositório e que seu token não foi revogado. A saída de erro é higienizada para ocultar credenciais, então o final da mensagem do git indica a causa real (por exemplo uma branch ausente ou um erro de permissão). Se o token foi revogado, reconecte a conta.
Se as chamadas de pull request ou review começarem a falhar com erros de autorização depois de funcionarem antes, seu token provavelmente foi revogado no GitHub. Desconecte e reconecte a conta para gerar um novo.

​
Relacionados

Adapters

Os providers que dão energia aos seus agentes, incluindo o Forge local.

Sources

Adicione repositórios e pastas para sua equipe trabalhar.