Criar a GitHub App

Este guia mostra como dar ao seu servidor uma identidade própria no GitHub. Demora cerca de dois minutos, só o proprietário do servidor o faz e só tem de acontecer uma vez por servidor.

Para ligar a sua própria conta posteriormente, consulte Configurar a integração com o GitHub.

Porque é que o seu servidor precisa de uma app própria

Um único registo dá origem a duas tarefas diferentes, e é a app que torna ambas honestas:

Tarefa	O que lhe responde	Porque é que importa
Uma pessoa inicia sessão	O ID de cliente da app, através do fluxo de dispositivo	Fica com uma credencial que é sua, no servidor, em todos os dispositivos — sem tokens para colar ou renovar
O servidor atua	O id da app + a chave privada → token de instalação	Os webhooks, a sondagem de PRs e a sincronização de tickets deixam de depender de o token de uma pessoa continuar válido

Repare no que não está nessa tabela: um segredo de cliente. O fluxo de dispositivo do GitHub autentica-se apenas com o ID de cliente — tanto no pedido do código de dispositivo como na sondagem do token — pelo que não há segredo nenhum a guardar para iniciar sessão.

Sem uma app própria, a primeira tarefa continua a funcionar através do ID de cliente incluído na build; a segunda recorre às credenciais do proprietário do servidor, pelo que o trabalho em segundo plano fica dependente de quem fez o onboarding primeiro.

Pré-requisitos

É o proprietário do servidor — as operações providerApps.* estão reservadas a ele, e o cartão é invisível para todos os outros
Uma conta do GitHub, ou uma organização onde possa criar apps
Nada acessível publicamente: o início de sessão é um fluxo de dispositivo, pelo que o servidor não precisa de portas de entrada, túnel, URL de callback nem domínio

Registar a app

Vá a github.com/settings/apps/new (para uma organização: Settings → Developer settings → GitHub Apps → New GitHub App)
GitHub App name — qualquer coisa; Control Center (yourname) serve. Aparece nos commits e nos comentários que o servidor faz
Homepage URL — qualquer coisa, por exemplo https://github.com/your-name
Callback URL — deixe-a vazia. O fluxo de dispositivo não tem nenhuma
Assinale Enable Device Flow. Esta é a única definição sem a qual o início de sessão não funciona
Desmarque Webhook → Active, a menos que esteja a configurar webhooks em separado
Em Repository permissions, conceda pelo menos:
- Contents: Read and write
- Metadata: Read-only (obrigatória)
- Pull requests: Read and write
- Issues: Read and write, se usar o GitHub Issues para tickets, e para a pesquisa de comentários de conversas de PR do bot (consulte Falar com o Control Center a partir de uma PR do GitHub)
- Checks: Read-only, para o estado da CI na página da PR
Em Where can this GitHub App be installed?, escolha a opção que se adequar — “Only on this account” é a certa para um servidor pessoal
Clique em Create GitHub App

Recolher os três valores

Na página da app, imediatamente após a criação:

Valor	Onde
App ID	O separador General, perto do topo
Client ID	O separador General, em “Client secrets”
Private key	Generate a private key — descarrega um `.pem`

O ficheiro da chave privada é descarregado uma única vez e o GitHub nunca o volta a mostrar. Guarde-o até o ter colado; pode sempre gerar outro.

Um segredo de cliente é opcional e serve exatamente para uma coisa: se mantiver “Expire user authorization tokens” ATIVADA, é ele que renova o token de alguém discretamente, em vez de lhe pedir que inicie sessão de novo a cada oito horas. O início de sessão em si nunca o utiliza.

A configuração mais simples é desligar essa expiração, e então não é preciso nenhum segredo. Se a mantiver ligada, gere um segredo e cole-o em Definições → Servidor → Início de sessão único (o cartão Aplicações do fornecedor) — não existe nenhuma variável de ambiente para ele, nem vem incorporado em nenhuma build, pelo que fica no seu servidor.

Instalar a app na sua conta

Uma app registada mas não instalada consegue autenticar pessoas e não consegue ler nada.

Na página da app, abra Install App
Instale-a na sua conta ou organização
Escolha All repositories, ou selecione os repositórios que este servidor deve ver

Colar os valores no Control Center

Vá a Definições → Servidor → Início de sessão único e desça até ao cartão Aplicações do fornecedor
No bloco GitHub, preencha cada campo:
- Id da aplicação — o App ID numérico
- Chave privada — cole o .pem completo, incluindo as linhas BEGIN e END
- Id de cliente — da mesma página
- Segredo de cliente — apenas se tiver gerado um (para renovação do token)
Clique em Testar

A chave é analisada no momento em que é guardada, pelo que uma colagem truncada ou com o formato errado é rejeitada de imediato, em vez de falhar num pedido em segundo plano horas mais tarde. Testar vai mais longe e pergunta ao GitHub em que contas a app está instalada — “guardado” e “funciona” são afirmações diferentes, e só a segunda significa que algo vai correr.

Ponto de verificação: o bloco do GitHub indica “O servidor pode agir por si próprio e as pessoas podem entrar.”, e a linha GitHub em Definições → Espaço de trabalho → Perfil e identidade → Hospedagem de código passa a oferecer Entrar com GitHub.

Configurar a app com variáveis de ambiente em alternativa

Para uma instalação headless ou por script, o servidor preenche cada campo a partir do ambiente na primeira vez que não tem nenhum valor guardado:

GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY="$(cat control-center.private-key.pem)"
GITHUB_CLIENT_ID=Iv1.0123456789abcdef

Não existem flags de linha de comandos para isto — um segredo na linha de comandos é legível por qualquer processo no host através de ps. O ambiente é o único sítio onde os configurar, e sobrepõe-se ao que a build incluir. O .env.template tem a lista completa.

Para desenvolvimento local, o .env na raiz do repo contém os mesmos valores e a aplicação para computador passa-os ao servidor que inicia. Coloque lá a chave numa única linha: um valor de .env é uma linha só, e \n entre aspas duplas é descodificado como uma nova linha.

GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEow…\n-----END RSA PRIVATE KEY-----"

GITHUB_APP_ID e GITHUB_APP_PRIVATE_KEY são os mesmos nomes que o mediador de tokens da sandbox já lê, pelo que um host que configurou tokens de agente de granularidade fina ganha a via de início de sessão de graça. O preenchimento acontece uma vez por campo — a partir daí, o valor guardado prevalece, pelo que editar em Definições não é revertido no reinício seguinte.

Faça o mesmo para o Linear

O Linear não tem fluxo de dispositivo, pelo que o seu início de sessão é uma ida e volta pelo navegador e precisa mesmo de uma URL de callback — o cartão Aplicações do fornecedor mostra-lhe exatamente qual deve registar.

Crie uma aplicação OAuth em linear.app/settings/api/applications/new
Defina a Callback URL com a URL que o cartão mostra, exatamente como está
Cole o Client ID e o Client secret no bloco do Linear
Opcionalmente, adicione uma API key do espaço de trabalho — é a credencial que o servidor usa para sincronizar tickets quando nenhuma pessoa o pediu

Resolução de problemas

A caixa de diálogo de início de sessão diz que o fornecedor não devolveu nenhum código de dispositivo

Enable Device Flow está desligada na app. Ligue-a em General e tente novamente.

O teste diz que as credenciais funcionam mas a app não está instalada em lado nenhum

O registo e a instalação são passos separados. Abra Install App na página da app e instale-a.

O teste diz que não foi possível ler a chave privada

Cole o ficheiro .pem completo, incluindo as linhas -----BEGIN e -----END. Uma chave ed25519 ou EC não pode ser usada — as GitHub Apps assinam com RSA.

Um membro iniciou sessão mas não vê repositórios

A app não está instalada na conta que é proprietária deles, ou a sua instalação seleciona repositórios diferentes. O início de sessão do próprio membro só concede o que a app tem permissão para ver.