Ligar um host de código

O Control Center funciona com três hosts de código, designados forges em toda a aplicação: GitHub, GitLab e Bitbucket Cloud. Nenhuma delas é a predefinida. Ligue uma e tudo funciona; ligue várias e um único espaço de trabalho pode conter repos de todas elas ao mesmo tempo.

A forge é uma propriedade de cada repo, lida a partir do seu remoto origin quando o regista. Nunca escolhe uma, e não há qualquer definição por espaço de trabalho que possa estar errada.

Ligar uma forge

Abra Definições → Espaço de trabalho → Perfil e identidade (/settings/workspace/profile).
Encontre o cartão Hospedagem de código. Todas as forges suportadas são listadas, estejam ligadas ou não.
Prima Entrar com … se a linha o oferecer, ou Adicionar token e cole um.

Entrar aparece para uma forge para a qual o seu servidor tenha uma app registada — hoje, o GitHub, através de um fluxo de dispositivo (consulte Criar a GitHub App). Tudo o resto é um token colado, que é a opção honesta em vez de um botão que não consegue concluir.

De qualquer forma, a credencial é sua e reside no servidor, indexada pelo id do seu utilizador: nenhum token é guardado na máquina onde o escreveu, todos os dispositivos em que inicia sessão usam o mesmo, e nenhum outro membro o consegue ler. Produz efeito no pedido seguinte — não há nada para reiniciar, e desligar faz com que deixe de ser enviada de imediato.

Cada linha indica de onde veio a sua credencial, porque é essa a diferença entre “o meu token não está a funcionar” e “está a responder outro token”:

Subtítulo	Significado
`Ligado como octocat`	Está a ser usada a sua própria credencial
`Ligado como octocat · pela aplicação deste servidor`	Está a responder a identidade de app do servidor — não iniciou sessão
`Ligado como octocat · do ambiente`	Está a responder uma variável de ambiente do servidor, não a sua credencial
`Não ligado`	Não tem credencial para esta forge

Que token quer cada forge

Forge	Token	Onde o criar
GitHub	Clássico: `repo` e `read:org`. Granular: Contents + Pull requests (read/write), Checks + Actions (read)	github.com → Settings → Developer settings → Tokens
GitLab	Um token de acesso pessoal com `api`	gitlab.com → User settings → Access tokens
Bitbucket	Um token de API da Atlassian, mais o e-mail da sua conta	id.atlassian.com → Security → API tokens

O Bitbucket autentica com o e-mail da sua conta como nome de utilizador e o token como palavra-passe. Defina BITBUCKET_EMAIL no ambiente do servidor para que saiba com que e-mail associar o token.

Ou usar o ambiente

Para uma instalação headless ou de CI, o servidor lê estes:

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

Estas são a credencial do servidor, não a sua, e a distinção é essencial: um pedido feito em seu nome usa a sua credencial e mais nada, pelo que o ambiente nunca o substitui silenciosamente. O trabalho sem ninguém por trás — webhooks, sondagem de PRs, sincronização de tickets — resolve primeiro a identidade de app do servidor, depois a credencial do proprietário do servidor e, por fim, o ambiente. A ordem é fixa, para que “iniciei sessão e nada mudou” nunca seja um resultado possível.

É uma pessoa diferente em cada forge

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

Se a identidade numa forge não tiver sido resolvida, os seus repos não contribuem em nada para a caixa de entrada, em vez de corresponderem a tudo. A caixa de entrada di-lo, em vez de afirmar que está em dia.

Uma caixa de entrada, todas as forges

A caixa de entrada e a fila de PRs distribuem-se por todas as forges representadas no espaço de trabalho e fundem os resultados num único fluxo — uma pull request do GitHub e uma pull request do Bitbucket ficam lado a lado, ordenadas por tempo em vez de agrupadas por fornecedor.

As falhas ficam isoladas. Uma forge que esteja em baixo, com limite de pedidos ou não ligada não contribui em nada e deixa as restantes intactas; nunca esvazia a caixa de entrada inteira. Os seus próprios repos continuam a mostrar o último estado conhecido até que recupere.

O que cada forge consegue fazer

Todas as forges suportam o ciclo principal: listar e abrir pull requests, ler diffs, comentar em linha e ao nível superior, rever, fazer merge e fechar. Para além disso, diferem de forma genuína, e o Control Center oculta o que uma forge não consegue fazer em vez de mostrar um controlo que falha em silêncio.

Capacidade	GitHub	GitLab	Bitbucket
Revisões em lote (pendentes)	✓	✓	—
Pedir alterações	✓	✓	✓
Estado “visto” por ficheiro sincronizado	✓	—	—
Reações com emoji	✓	✓	—
Revisores de equipa / grupo	✓	✓	—
Revisores sugeridos	✓	—	✓
Resultados de CI numa PR	✓	✓	✓
Explorar os passos/registos de uma tarefa de CI	✓	✓	—
Pull requests empilhadas	✓	—	—
Modelos de descrição de PR	✓	✓	—
Sondagem de notificações	✓	—	—
Perfis de utilizador detalhados	✓	✓	—
Ref de cabeça de PR do lado do servidor	✓	✓	—

Quando falta uma capacidade, a funcionalidade degrada-se de forma honesta:

O estado “visto” continua a funcionar, mas apenas no dispositivo onde o definiu.
As revisões em lote no Bitbucket são publicadas comentário a comentário, pelo que os revisores os veem chegar individualmente em vez de todos de uma vez.
Sem ref de cabeça de PR no Bitbucket, fazer checkout de uma pull request obtém o respetivo branch de origem pelo nome, o que falha assim que esse branch é eliminado.

Vocabulário

O GitLab chama merge request a uma pull request. O Control Center diz “pull request” em todo o seu modelo, e usa o substantivo de cada forge quando está a falar dessa forge.

Resolução de problemas

A lista de PRs está vazia e diz que uma forge não está ligada

Não tem credencial para essa forge. Inicie sessão ou cole um token em Definições → Espaço de trabalho → Perfil e identidade → Hospedagem de código. Os repos das outras forges não são afetados.

Liguei uma forge mas os seus repos continuam a não mostrar nada

Verifique o subtítulo da linha. Se disser “pela aplicação deste servidor” ou “do ambiente”, está a responder uma credencial diferente da que esperava — a sua própria credencial ganha para tudo o que pedir, pelo que, se disser outra coisa, a sua não foi guardada.

Um repo não se regista

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 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. Uma forge que assinala o seu limite principal faz com que o cliente deixe de fazer mais pedidos localmente, 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 com recuo exponencial.