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 card Get started, Connect GitHub. Clique nele e o GitHub abre o fluxo de instalação a partir da listagem do app do Latchkey no GitHub. 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 a configuração 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 dashboard mostra um erro "You'll need a GitHub organization" 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á.

Crie uma organização e mova seu repositório#

Só tem uma conta pessoal? Você não precisa abandonar seu repositório existente. Crie uma organização gratuita, mova o repositório para ela e reconecte. Leva alguns minutos, e seu histórico, issues e stars vão junto.

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 card Get started retoma 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#