Instalar o GitHub App

Como funciona a instalação do GitHub App do Latchkey, por que ela exige uma conta de organização, quais permissões usa e como corrigir uma instalação que falhou.

O Latchkey se conecta ao GitHub por meio de um GitHub App. Instalá-lo é a etapa única de configuração da qual todo o resto depende: webhooks, analytics, recomendações de IA e runners gerenciados fluem todos pelo app. Isso também faz dele a primeira coisa a verificar quando algo parece desconectado: se o app estiver ausente ou instalado na organização errada, todos os recursos derivados apresentam sintomas de uma vez.

Instalando durante o onboarding#

O caminho normal é o passo 1 do onboarding ("Conectar o GitHub"). Clique em Autorizar o Latchkey e o GitHub abre a página de instalação do app do Latchkey. Escolha a organização que você quer monitorar e confirme. Quando o GitHub trouxer você de volta ao Latchkey, a instalação é vinculada ao seu workspace e o onboarding continua para a seleção de repositórios.

Contas de organização são obrigatórias#

O Latchkey suporta apenas contas de organização do GitHub. Se o app for instalado em uma conta pessoal (de usuário), o Latchkey a rejeita: a instalação é automaticamente desinstalada do GitHub e o onboarding mostra um erro de "conta pessoal não suportada" para que você possa tentar novamente com uma organização. Se você só tem uma conta pessoal, crie uma organização do GitHub primeiro (é gratuito) e transfira ou crie seus repositórios lá.

O que o app pode acessar#

Em termos simples, o app do Latchkey:

• Lê metadados de execução de workflow e de job (nomes, tempos, status, labels de runner). Este é o material bruto para os dashboards de custo, desempenho e confiabilidade.
• Lê seus arquivos YAML de workflow em .github/workflows/, para que a IA possa analisá-los e propor alterações concretas no exato arquivo que um PR de otimização editaria.
• Recebe webhooks para eventos de workflow, para que o dashboard permaneça atualizado em tempo real. É também por isso que não há nada para fazer polling ou atualizar.
• Abre pull requests em seu nome apenas quando você pede: ao aplicar uma recomendação de otimização, ou uma proposta de correção autorreparável. Esses PRs são sempre para sua revisão; nada é mesclado automaticamente, e pull requests de forks nunca são tocados.
• Gerencia seu próprio grupo de runners na sua organização para que jobs runs-on: latchkey-* possam ser roteados para runners gerenciados. Isso é infraestrutura de CI da organização, não conteúdo de repositório.

O que ele não faz: o Latchkey não lê o código-fonte da sua aplicação além dos arquivos de workflow, e nunca lê seus secrets ou os valores das suas variáveis de ambiente. Se o seu time de segurança quiser o panorama completo, incluindo isolamento de runner e exclusão de dados, aponte-os para Segurança e permissões do GitHub; ela foi escrita para responder diretamente a uma revisão de segurança.

Se a instalação der errado#

• Instalado na conta errada: se foi uma conta pessoal, o Latchkey já removeu a instalação; basta tentar novamente com a organização. Se foi a organização errada, desinstale o app dessa organização no GitHub (Settings, GitHub Apps) e instale-o na correta. Para confirmar onde o app está atualmente, verifique a página Settings, GitHub Apps de cada organização: o Latchkey aparece na lista onde quer que esteja instalado.
• Fechou a aba no meio da instalação: faça login novamente e o Latchkey retoma o onboarding de onde você parou; nada precisa ser desfeito primeiro.
• Sem permissão para instalar: instalar um GitHub App em uma organização requer permissões de owner ou admin. Peça a um owner da organização para instalar o app ou conceder a você direitos de admin, e então tente novamente pelo onboarding.

Perguntas comuns#