Criar o GitHub App

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

Talvez você não precise disso

Uma compilação oficial já inclui um id de cliente do GitHub, então Entrar com GitHub funciona de imediato sem nada registrado — um fluxo de dispositivo se autentica só com o id de cliente, por isso é seguro distribuí-lo. Registre seu próprio app quando quiser que o SERVIDOR aja por si próprio (webhooks, polling de PR e sincronização de tickets rodando em uma instalação do app, e não na credencial de uma pessoa), ou quando você estiver compilando a partir do código-fonte.

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

Por que seu servidor precisa de um app próprio

Um único registro atende a dois trabalhos diferentes, e o app é o que torna ambos honestos:

Trabalho	O que responde	Por que importa
Uma pessoa entra	O id de cliente do app, pelo fluxo de dispositivo	Você tem uma credencial que é sua, no servidor, em todos os dispositivos — sem token para colar ou rotacionar
O servidor age	O id do app + a chave privada → token de instalação	Webhooks, polling de PR e sincronização de tickets deixam de depender de o token de uma pessoa ainda ser válido

Note o que não está nessa tabela: um segredo de cliente. O fluxo de dispositivo do GitHub se autentica apenas com o id de cliente — tanto a solicitação do código de dispositivo quanto o polling do token —, então não há nenhum segredo a guardar para entrar.

Sem um app próprio, o primeiro caso continua funcionando pelo id de cliente que a compilação inclui; o segundo recorre à credencial do proprietário do servidor, então o trabalho em segundo plano fica dependendo de quem fez a configuração inicial primeiro.

Não existe um botão “instalar o GitHub App do Control Center”

Um GitHub App distribuído significaria um mesmo segredo de cliente e uma mesma instalação compartilhados entre os servidores de todo mundo, de modo que o acesso aos repositórios de cada espaço de trabalho passaria por credenciais que ninguém nesse espaço de trabalho controla. Por isso cada servidor tem o próprio app — este guia mostra como isso custa pouco.

Pré-requisitos

• Você é o proprietário do servidor — as operações providerApps.* são permitidas apenas a ele, e o cartão fica invisível para todos os outros
• Uma conta do GitHub, ou uma organização em que você possa criar apps
• Nada precisa ser acessível publicamente: a entrada é um fluxo de dispositivo, então o servidor não precisa de porta de entrada, túnel, URL de callback nem domínio

Registrar o app

1. Acesse github.com/settings/apps/new (para uma organização: Settings → Developer settings → GitHub Apps → New GitHub App)
2. GitHub App name — qualquer coisa; Control Center (yourname) serve. Ele aparece nos commits e comentários que o servidor faz
3. Homepage URL — qualquer coisa, por exemplo https://github.com/your-name
4. Callback URL — deixe em branco. O fluxo de dispositivo não usa nenhuma
5. Marque Enable Device Flow. É a única configuração sem a qual a entrada não funciona
6. Desmarque Webhook → Active, a menos que você vá configurar webhooks à parte
7. Em Repository permissions, conceda ao menos:
   • Contents: Read and write
   • Metadata: Read-only (obrigatório)
   • Pull requests: Read and write
   • Issues: Read and write, se você usa o GitHub Issues para tickets, e para a busca de comentários do bot nas conversas de PR (consulte Falar com o Control Center a partir de uma PR do GitHub)
   • Checks: Read-only, para o estado de CI na página da PR
8. Em Where can this GitHub App be installed?, escolha o que fizer mais sentido — “Only on this account” é o certo para um servidor pessoal
9. Clique em Create GitHub App

Coletar os três valores

Na página do app, logo após a criação:

Valor	Onde
App ID	A aba General, perto do topo
Client ID	A aba General, em “Client secrets”
Private key	Generate a private key — um .pem é baixado

O arquivo da chave privada é baixado uma única vez e o GitHub nunca mais o mostra. Guarde-o até ter colado; você sempre pode gerar outro.

Um segredo de cliente é opcional e serve para exatamente uma coisa: se você deixar “Expire user authorization tokens” ATIVADO, é ele que renova o token de alguém silenciosamente, em vez de pedir que a pessoa entre de novo a cada oito horas. A entrada em si nunca o usa.

A configuração mais simples é desativar essa expiração, e então nenhum segredo é necessário em lugar algum. Se você mantê-la ativada, gere um segredo e cole em Configurações → Servidor → Início de sessão único (no cartão Apps do fornecedor) — não existe variável de ambiente para ele, e nenhuma vem embutida na compilação, então ele fica no seu servidor.

Instalar na sua conta

Um app registrado, mas não instalado, consegue autenticar pessoas e não consegue ler nada.

1. Na página do app, abra Install App
2. Instale-o na sua conta ou organização
3. Escolha All repositories ou selecione os repositórios que este servidor deve enxergar

Colar no Control Center

1. Acesse Configurações → Servidor → Início de sessão único e role até o cartão Apps do fornecedor
2. No bloco GitHub, preencha cada campo:
   • Id da app — o App ID numérico
   • Chave privada — cole o .pem inteiro, incluindo as linhas BEGIN e END
   • Id de cliente — o da mesma página
   • Segredo de cliente — só se você tiver gerado um (para renovar o token)
3. Clique em Testar

A chave é analisada no momento em que é salva, então uma colagem truncada ou em formato errado é rejeitada ali mesmo, em vez de falhar em uma solicitação em segundo plano horas depois. Testar vai além e pergunta ao GitHub em quais contas o app está instalado — “salvo” e “funciona” são afirmações diferentes, e só a segunda significa que algo vai rodar.

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

Configurar com variáveis de ambiente

Para uma instalação headless ou automatizada por script, o servidor preenche cada campo a partir do ambiente na primeira vez em que não há um valor armazenado:

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

Não há flags de linha de comando para isso — um segredo na linha de comando pode ser lido por qualquer processo do host via ps. O ambiente é o único lugar para configurá-los, e ele prevalece sobre o que a compilação inclui. O .env.template é a lista completa.

Para desenvolvimento local, o .env na raiz do repositório carrega os mesmos valores, e o desktop os repassa ao servidor que ele inicia. Coloque a chave em uma única linha ali: um valor de .env é uma linha, e \n entre aspas duplas é decodificado como uma quebra de 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 broker de tokens do sandbox já lê, então um host que já configurou tokens de agente de granularidade fina ganha a via de entrada de graça. O preenchimento acontece uma vez por campo — depois disso o valor armazenado prevalece, então uma edição feita nas configurações não é desfeita na próxima reinicialização.

Faça o mesmo para o Linear

O Linear não tem fluxo de dispositivo, então a entrada nele é uma ida e volta pelo navegador e sim precisa de uma URL de callback — o cartão Apps do fornecedor mostra exatamente qual registrar.

1. Crie um aplicativo OAuth em linear.app/settings/api/applications/new
2. Defina a Callback URL como a URL que o cartão mostra, ao pé da letra
3. Cole o Client ID e o Client secret no bloco do Linear
4. Opcionalmente, adicione uma API key do espaço de trabalho — é a credencial que o servidor usa para sincronizar tickets quando nenhuma pessoa pediu

Solução de problemas

O diálogo de entrada diz que o provedor não retornou nenhum código de dispositivo

Enable Device Flow está desativado no app. Ative-o em General e tente de novo.

O teste diz que as credenciais funcionam, mas o app não está instalado em lugar nenhum

Registro e instalação são etapas separadas. Abra Install App na página do app e instale-o.

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

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

Um membro entrou, mas não vê nenhum repositório

O app não está instalado na conta proprietária deles, ou a instalação dele seleciona outros repositórios. A entrada do próprio membro só concede o que o app tem permissão de enxergar.

Guias relacionados

• Configurar a integração com o GitHub
• Falar com o Control Center a partir de uma PR do GitHub
• Conectar um host de código
• Gerenciar chaves de API
• Configurar a integração com o Slack