# 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.

Source: https://latchkey.dev/pt/documentation/install-the-github-app

## Summary

- Instale a partir do passo **Connect GitHub** do card Get started em uma **organização** do GitHub; quem instala se torna o owner do workspace.
- Instalações em contas pessoais são rejeitadas e removidas automaticamente.
- O app lê execuções de workflow e YAML, recebe webhooks, abre PRs apenas por ação sua e gerencia seu grupo de runners.

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](https://github.com/apps/latchkey-analytics-ci-cd-monitor). 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.

> **Quem se torna o owner do workspace**
> A pessoa que instala o app é vinculada como o owner do workspace no Latchkey. Há exatamente um owner por workspace, e a propriedade pode ser transferida depois com Transferir Propriedade, então instale com a conta que deve ser dona da cobrança e do gerenciamento do time. Veja [Time e funções](/documentation/team-and-roles).

## 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](https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch) 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.

1. **Crie uma organização gratuita** Acesse [github.com/account/organizations/new](https://github.com/account/organizations/new) e crie uma organização. O plano **Free** é tudo o que o Latchkey precisa; dê a ela o nome do seu time, projeto ou usuário. O guia oficial do GitHub é [Creating a new organization from scratch](https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch).
2. **Mova seu repositório para a organização** No repositório no GitHub, abra **Settings → General → Danger Zone → Transfer ownership** e transfira-o para sua nova organização. A transferência mantém seu histórico de commits, issues, pull requests e stars, e o GitHub redireciona a URL antiga para que clones e links existentes continuem funcionando. Veja [Transferring a repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/transferring-a-repository). Se preferir começar do zero, crie um novo repositório diretamente dentro da organização.
3. **Reconecte o Latchkey** De volta ao Latchkey, clique em **Connect GitHub** no card Get started novamente e escolha sua **organização** desta vez. A instalação é vinculada ao seu workspace e a configuração continua para a seleção de repositórios.

## 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](/documentation/security-and-permissions); 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

### Quem se torna o owner do workspace?

A pessoa que instala o GitHub App é vinculada como o owner do workspace. Há exatamente um owner por workspace; o owner pode depois passar o workspace para outro membro com Transferir Propriedade. Detalhes em [Time e funções](/documentation/team-and-roles).

### Posso instalar o Latchkey em mais de uma organização?

Sim. Cada instalação recebe seu próprio workspace, com seu próprio plano, time, repositórios e dados. O seletor de workspace na barra lateral do dashboard alterna entre os workspaces aos quais você pertence, e o Latchkey lembra seu último workspace usado entre logins.

### Preciso ser o owner da organização do GitHub para instalar?

Você precisa de permissões de owner ou admin na organização. Se você não tiver nenhuma delas, peça a um owner da organização para instalar o app ou conceder a você direitos de admin.

### Instalar o app muda algo nos meus repositórios?

Não. Não há agentes para instalar e nenhuma alteração nos seus workflows até que você decida fazê-las. O Latchkey só escreve por meio de pull requests que você pode revisar: uma otimização que você aplica, ou uma proposta de correção autorreparável. Veja [Segurança e permissões do GitHub](/documentation/security-and-permissions).

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt