Conectar um host de código

O Control Center funciona com três hosts de código, chamados de forges em todo o app: GitHub, GitLab e Bitbucket Cloud. Nenhum deles é o padrão. Conecte um e tudo funciona; conecte vários e um único espaço de trabalho pode reunir repos de todos eles ao mesmo tempo.

O forge é uma propriedade de cada repo, lida do remote origin dele quando você o registra. Você nunca escolhe um, e não existe uma configuração por espaço de trabalho para errar.

Conectar um forge

Abra Configurações → Espaço de trabalho → Perfil e identidade (/settings/workspace/profile).
Encontre o cartão Hospedagem de código. Todos os forges compatíveis aparecem listados, conectados ou não.
Pressione Entrar com … se a linha oferecer essa opção, ou Adicionar token e cole um.

Entrar aparece para um forge para o qual seu servidor tem um app registrado — hoje, o GitHub, por meio de um fluxo de dispositivo (veja Criar o GitHub App). Todo o resto é um token colado, o que é a opção honesta em vez de um botão que não tem como concluir.

De qualquer forma, a credencial é sua e fica no servidor, indexada pelo seu id de usuário: nenhum token é armazenado na máquina em que você o digitou, todos os dispositivos em que você entra usam a mesma credencial, e nenhum outro membro consegue lê-la. Ela entra em vigor na próxima solicitação — não há nada para reiniciar, e desconectar faz com que ela deixe de ser enviada imediatamente.

Cada linha informa de onde veio a sua credencial, porque é essa a diferença entre “meu token não está funcionando” e “um token diferente está respondendo”:

Subtítulo	Significado
`Conectado como octocat`	A sua própria credencial está sendo usada
`Conectado como octocat · pela app deste servidor`	A identidade do app do servidor está respondendo — você não entrou
`Conectado como octocat · do ambiente`	Uma variável de ambiente do servidor está respondendo, não a sua credencial
`Não conectado`	Você não tem credencial para este forge

Qual token cada forge quer

Forge	Token	Onde criá-lo
GitHub	Clássico: `repo` e `read:org`. Granular: Contents + Pull requests (read/write), Checks + Actions (read)	github.com → Configurações → Configurações do desenvolvedor → Tokens
GitLab	Um token de acesso pessoal com `api`	gitlab.com → Configurações do usuário → Tokens de acesso
Bitbucket	Um token de API da Atlassian, mais o e-mail da sua conta	id.atlassian.com → Segurança → Tokens de API

O Bitbucket autentica com o e-mail da sua conta como nome de usuário e o token como senha. Defina BITBUCKET_EMAIL no ambiente do servidor para que ele saiba com qual e-mail parear o token.

Ou use o ambiente

Para uma instalação headless ou de CI, o servidor lê estas variáveis:

GitHub — GITHUB_TOKEN, depois GH_TOKEN
GitLab — GITLAB_TOKEN, depois CI_JOB_TOKEN
Bitbucket — BITBUCKET_API_TOKEN, depois BITBUCKET_TOKEN (com BITBUCKET_EMAIL)

Essas são a credencial do servidor, não a sua, e a distinção é determinante: uma solicitação feita em seu nome usa a sua credencial e nada mais, então o ambiente nunca substitui você silenciosamente. Trabalho sem ninguém por trás — webhooks, consulta periódica de PRs, sincronização de tickets — resolve primeiro a identidade do app do servidor, depois a credencial do proprietário do servidor e, por fim, o ambiente. A ordem é fixa para que “eu entrei e nada mudou” nunca seja um resultado possível.

Você é uma pessoa diferente em cada forge

A mesma pessoa é octocat no GitHub e algo completamente diferente no GitLab. O Control Center resolve sua identidade por forge e usa a correta para cada repo, e é isso que faz “precisa da minha revisão”, “criado por mim” e “você aprovou isto” ficarem corretos em um espaço de trabalho misto.

Se a identidade de um forge não foi resolvida, os repos dele não contribuem com nada para a caixa de entrada, em vez de corresponder a tudo. A caixa de entrada diz isso em vez de afirmar que você está em dia com tudo.

Uma caixa de entrada, todos os forges

A caixa de entrada e a fila de PRs se ramificam por todos os forges representados no espaço de trabalho e mesclam os resultados em um único fluxo — uma pull request do GitHub e uma do Bitbucket ficam lado a lado, ordenadas por horário em vez de agrupadas por fornecedor.

As falhas são isoladas. Um forge que está fora do ar, com limite de taxa atingido ou desconectado não contribui com nada e deixa os outros intactos; ele nunca esvazia a caixa de entrada inteira. Os repos dele continuam mostrando o último estado conhecido até que ele se recupere.

O que cada forge consegue fazer

Todos os forges dão suporte ao ciclo principal: listar e abrir pull requests, ler diffs, comentar em linha e no nível superior, revisar, fazer merge e fechar. Além disso, eles realmente diferem, e o Control Center oculta o que um forge não consegue fazer em vez de mostrar um controle que falha silenciosamente.

Capacidade	GitHub	GitLab	Bitbucket
Revisões em lote (pendentes)	✓	✓	—
Solicitar alterações	✓	✓	✓
Estado “visto” por arquivo sincronizado	✓	—	—
Reações com emoji	✓	✓	—
Revisores de equipe / grupo	✓	✓	—
Revisores sugeridos	✓	—	✓
Resultados de CI em uma PR	✓	✓	✓
Detalhar as etapas/logs de um job de CI	✓	✓	—
Pull requests empilhadas	✓	—	—
Modelos de descrição de PR	✓	✓	—
Consulta periódica de notificações	✓	—	—
Perfis de usuário avançados	✓	✓	—
Ref de head da PR no servidor	✓	✓	—

Quando uma capacidade está ausente, o recurso degrada de forma honesta:

O estado “visto” ainda funciona, mas apenas no dispositivo em que você o definiu.
As revisões em lote no Bitbucket publicam comentário por comentário, então os revisores os veem chegar individualmente em vez de todos de uma vez.
A ausência de ref de head da PR no Bitbucket significa que fazer checkout de uma pull request busca seu branch de origem pelo nome, o que falha quando esse branch é excluído.

Vocabulário

O GitLab chama uma pull request de merge request. O Control Center diz “pull request” em todo o seu próprio modelo e usa o substantivo de cada forge quando está falando sobre aquele forge.

Solução de problemas

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

Você não tem credencial para esse forge. Entre ou cole um token em Configurações → Espaço de trabalho → Perfil e identidade → Hospedagem de código. Os repos dos outros forges não são afetados.

Conectei um forge, mas os repos dele ainda não mostram nada

Verifique o subtítulo da linha. Se ele diz “pela app deste servidor” ou “do ambiente”, uma credencial diferente da que você esperava está respondendo — a sua própria credencial prevalece para tudo que você pedir, então, se ele diz outra coisa, a sua não foi salva.

Um repo não registra

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 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. Um forge que sinaliza seu limite primário faz o cliente falhar as próximas solicitações localmente, sem nenhuma chamada de rede, até que a janela passe — assim uma tempestade de tentativas não pode aprofundar o limite. Falhas transitórias são repetidas com backoff exponencial.