# GitHub Issues
URL: /integracoes/github
Conecte o projeto ao GitHub, crie issues a partir de reports e vincule issues existentes.
Com a integração, qualquer membro do projeto cria uma issue a partir de um report, ou vincula uma issue que já existe. As evidências continuam no Mira: a issue leva o texto e um link de volta ao report, e quem abrir o link precisa entrar no Mira e ter acesso ao projeto.
A integração não acompanha o status da issue nem sincroniza edições posteriores.
## Usar no dia a dia [#usar-no-dia-a-dia]
**Quem faz:** qualquer membro do projeto, depois que um admin conectou o GitHub.
### Criar uma issue [#criar-uma-issue]
### Abrir o report [#abrir-o-report]
Abra o report e revise a triagem.
### Escolher o repositório [#escolher-o-repositório]
No card **Integrações**, escolha criar issue e selecione o repositório. Confira as issues já vinculadas e os envios em andamento, para não criar duas.
### Revisar o texto [#revisar-o-texto]
Revise título e descrição, incluindo contexto e passos. Remova dados sensíveis antes de confirmar. O Mira inclui o link de volta ao report.
### Confirmar [#confirmar]
Confirme e acompanhe a solicitação até aparecer o vínculo. Fechar ou recarregar a tela não cancela um envio confirmado.
A GitHub App aparece como autora da ação no GitHub, e o histórico do Mira registra quem pediu o envio. Arquivos e dumps técnicos não são copiados. Editar o report depois não altera a issue.
Card Integrações de um report com a ação de criar issue no GitHub. Nome planejado: `github-create-issue.png`. Depende de GitHub simulado no pipeline.
### Vincular uma issue existente [#vincular-uma-issue-existente]
1. Copie a URL da issue, como `https://github.com/empresa/repositorio/issues/123`.
2. No report, abra a ação de vincular e cole a URL.
3. Confira repositório, número e título e confirme.
O repositório precisa estar liberado para o projeto. Issues abertas e fechadas valem. Pull requests não. O Mira não escreve na issue existente. Para corrigir uma escolha errada, remova o vínculo no Mira e vincule a correta. A issue no GitHub não é alterada.
### Se algo falhar [#se-algo-falhar]
| Situação | O que fazer |
| --- | --- |
| Pendente ou enviando | Acompanhe a solicitação existente, sem criar outra |
| Aguardando limite do GitHub | Aguarde o prazo informado, porque repetir cliques não antecipa |
| Falha de validação | Corrija o campo indicado e retome |
| Conexão inválida ou sem permissão | Peça ao admin para conferir a instalação e os repositórios |
| Issue não encontrada | Confira a URL e seu acesso. A mensagem não prova que ela foi excluída |
| Resultado incerto na criação | Confira o GitHub antes de criar outra: a issue pode existir sem confirmação no Mira |
Em resultado incerto, use a recuperação da solicitação para informar a URL encontrada. Se a conferência não encontrar a issue, só um admin ou o Mantenedor do projeto libera nova tentativa, confirmando o risco de duplicar.
O botão **Ajuda** da seção do report cobre criar, vincular, estados e recuperação.
## Conectar o GitHub [#conectar-o-github]
**Quem faz:** admin do Mira, junto com uma pessoa autorizada no GitHub. O painel **GitHub Issues**, em **Configurações do projeto → Integrações**, mostra os passos com links.
### Criar a GitHub App [#criar-a-github-app]
No painel, escolha **Conta pessoal** ou **Organização**, informe o nome da organização se for o caso e clique em **Criar a App no GitHub**. O link abre o registro já preenchido: Issues em leitura e escrita, Metadata em leitura, App privada e webhook desativado. Clique em **Create GitHub App**.
Para ter links de código e commits suspeitos nos [erros](/erros/detalhe#código-no-github), acrescente também a permissão **Contents** em leitura. Sem ela, o resto funciona.
### Copiar o App ID [#copiar-o-app-id]
Na página da App, copie o número do **App ID**. Não use o Client ID.
### Gerar a chave privada [#gerar-a-chave-privada]
Em **Private keys**, clique em **Generate a private key**. O GitHub baixa um arquivo `.pem`.
### Instalar a App [#instalar-a-app]
Em **Install App**, instale na conta ou organização e escolha **Only select repositories** com os repositórios necessários. A organização pode exigir aprovação de um owner.
### Achar o Installation ID [#achar-o-installation-id]
Abra a instalação com **Configure**. O Installation ID é o número no fim da URL, como `.../settings/installations/12345678`.
### Conectar no Mira [#conectar-no-mira]
No último passo do painel, informe o App ID, o Installation ID e o conteúdo inteiro do `.pem`, da linha `BEGIN` até a linha `END`. Clique em **Validar e conectar** e confira a conta exibida. Depois, selecione os repositórios que podem receber issues deste projeto e clique em **Salvar repositórios**.
Liberar um repositório autoriza todos os membros do projeto a enviar texto pela App, mesmo sem permissão pessoal de escrita no GitHub. Adicionar um repositório na instalação não o libera no projeto: é preciso marcá-lo e salvar.
A chave privada fica criptografada e nunca é mostrada de novo. Não cole chaves em chat, report ou issue.
### Mensagens ao conectar [#mensagens-ao-conectar]
| Mensagem | O que fazer |
| --- | --- |
| O GitHub recusou a chave | Confira se o App ID é da mesma App e cole o `.pem` inteiro |
| Instalação não encontrada | Confira o Installation ID e se a App continua instalada |
| Instalação de outra App, suspensa ou sem permissões | Ajuste as permissões da App e aceite a atualização na página da instalação |
| O GitHub limitou as chamadas | Tente de novo em alguns minutos |
| Sem acesso a repositório com Issues ativo | Adicione os repositórios na instalação e clique em **Consultar de novo** |
### Trocar a chave [#trocar-a-chave]
1. Na página da App no GitHub, gere uma nova chave.
2. No painel do Mira, clique em **Atualizar credenciais**, cole a chave nova e clique em **Validar e conectar**.
3. Só depois de validar, apague a chave antiga no GitHub.
**Desconectar**, no menu de ações do painel, interrompe novos envios. Não revoga a instalação no GitHub nem remove texto já exportado.
## Próximos passos [#próximos-passos]
- [Jira](/integracoes/jira)
- [Código no GitHub, nos erros](/erros/detalhe#código-no-github)