# Integração com o GitHub Ligue os repositórios do GitHub aos seus projetos no KrakenDock. Branches, commits e pull requests que citam a chave de um card aparecem dentro do card. Você também pode importar as issues de um repositório como cards e manter essas issues sincronizadas com o board. O guia é para quem administra a conta ou o projeto (conectar e vincular) e para quem desenvolve (citar o card no código e acompanhar o trabalho pelo card). > Versão em Markdown puro deste guia: [https://app.krakendock.com/docs/github.md?lang=pt-BR](https://app.krakendock.com/docs/github.md?lang=pt-BR). Use-a para colar num assistente de IA ou na documentação interna do seu time. ## Visão geral | Peça | O que faz | Onde | | -------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------- | | Conexão | instala o GitHub App do KrakenDock numa conta ou organização do GitHub | Configurações → **Integrações** (pessoal ou da organização) | | Repositórios do projeto | escolhe quais repositórios da conexão alimentam o projeto | Configurações do projeto → **Repositórios** | | Painel **Desenvolvimento** | mostra no card as branches, commits e pull requests que citam a chave dele | dentro do card | | Importação de issues | cria um card para cada issue do repositório, de uma vez | Configurações do projeto → **Repositórios** | | Sincronização de issues | mantém um card por issue, com alterações e comentários vindos do GitHub | Configurações do projeto → **Repositórios** | O caminho de dados é sempre do GitHub para o KrakenDock. Nada do que você muda no KrakenDock é escrito no GitHub, com uma exceção: o botão **Criar branch** do card cria a branch no repositório. ## Como começar 1. Abra [Configurações → Integrações](https://app.krakendock.com/settings/integrations) e clique em **Conectar GitHub**. Para um projeto de organização, use as configurações da organização (veja [Conta pessoal ou organização](#conta-pessoal-ou-organizacao)). 2. No GitHub, escolha a conta onde o app será instalado e os repositórios que ele pode ler. Aceite as permissões e autorize o app. 3. O GitHub devolve você ao KrakenDock, e a conta aparece na lista com o tipo **Usuário** ou **Organização**. 4. No projeto, abra **Configurações** → **Repositórios**, clique em **Vincular repositório**, escolha o repositório e clique em **Vincular**. 5. Faça um commit com a chave de um card na mensagem, por exemplo `APP-42 corrige o login`, e envie (push). O commit aparece no painel **Desenvolvimento** do card `APP-42` em segundos. Depois, se quiser trazer as issues: [importe](#importar-issues) as que já existem e [ligue a sincronização](#sincronizar-issues) para as próximas. ## Conectar uma conta do GitHub Uma conexão é uma instalação do GitHub App do KrakenDock numa conta do GitHub (de usuário ou de organização). Uma conta do KrakenDock pode ter várias conexões: use **Conectar outra conta** para acrescentar mais uma. Durante a instalação, o GitHub pede que você autorize o app. O KrakenDock usa essa autorização só para confirmar que você administra a conta do GitHub onde o app foi instalado e descarta o acesso logo em seguida. Ele não guarda nenhum token seu. Depois disso, o KrakenDock lê o GitHub como o próprio app, só nos repositórios que você liberou na instalação. ### Conta pessoal ou organização Cada projeto só enxerga as conexões da conta dona dele: | Projeto | Onde conectar | Quem pode conectar | | -------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | Pessoal (seu) | [Configurações → Integrações](https://app.krakendock.com/settings/integrations) | você | | De uma organização do KrakenDock | **Configurações da organização** → **Integrações** (`/SUA-ORGANIZACAO/settings/integrations`) | quem tem a permissão **Gerenciar integrações** (Owner, por padrão) | No GitHub, você precisa ser o dono da conta de usuário ou admin da organização onde instala o app. Ter acesso a alguns repositórios não basta. - Se você não é dono da organização no GitHub, o GitHub cria um pedido de instalação. O KrakenDock mostra "Instalação solicitada": quando um dono aprovar no GitHub, conecte de novo. - Uma instalação do GitHub fica ligada a uma única conta do KrakenDock. Se ela já está conectada em outra conta (por exemplo, na sua conta pessoal em vez da organização), a conexão é recusada. Desconecte de lá antes. ### Repositórios liberados para o app Para dar acesso a mais repositórios, ou tirar, mude a instalação no próprio GitHub (nas configurações do app instalado, em _Configure_). Clicar em **Conectar outra conta** e escolher a mesma conta do GitHub também leva você até lá. - Um repositório novo na instalação fica disponível para vincular, sem passo extra. - Um repositório removido da instalação, excluído ou transferido para outra conta é retirado do KrakenDock, com os vínculos dele nos cards. - Um repositório renomeado, ou que mudou de visibilidade, é atualizado sozinho. ### Desconectar e desinstalar - **Desconectar** remove a conexão no KrakenDock: os repositórios dela deixam de estar vinculados aos projetos, e as branches, commits e pull requests somem dos cards. Os cards criados a partir de issues continuam no board. - Desconectar não desinstala o app do GitHub. Para revogar o acesso, desinstale o app pelo GitHub. Ao receber a desinstalação, o KrakenDock apaga a conexão. - Se o GitHub suspender a instalação, a conexão aparece como **Suspensa**. Enquanto isso, não dá para vincular repositórios, importar issues nem criar branches por ela. ## Vincular repositórios a um projeto Em **Configurações** → **Repositórios** do projeto (grupo **Integrações**), clique em **Vincular repositório**. A lista mostra os repositórios de todas as conexões da conta dona do projeto, com busca. Os que já estão no projeto aparecem como **Vinculado**. - Um projeto pode ter vários repositórios, e o mesmo repositório pode estar em vários projetos. - Só as chaves dos projetos vinculados a um repositório são reconhecidas nele. Se `APP` e `API` usam o mesmo repositório, vincule-o aos dois. ### Importação inicial Ao vincular, o KrakenDock lê as branches atuais e os pull requests abertos que citam cards do projeto. Commits antigos e pull requests já fechados não entram: dali em diante, tudo chega pelos eventos do GitHub. | Status | Significado | | ---------------- | -------------------------------------------------------------------------------- | | **Na fila** | a leitura inicial ainda não começou | | **Importando** | lendo branches e pull requests | | **Sincronizado** | pronto; a data da última leitura aparece ao lado | | **Falhou** | o GitHub recusou a leitura (app desinstalado, sem acesso, limite de requisições) | O botão de sincronizar de novo (ícone de setas, ao lado do repositório) refaz a leitura inicial. Ele também reinicia uma leitura parada em **Na fila** ou **Importando** há mais de 10 minutos. Uma leitura que falhou não é repetida sozinha. ### Desvincular um repositório O ícone de lixeira, com a confirmação **Desvincular**, tira o repositório do projeto. As branches, commits e pull requests dele somem dos cards, e a sincronização de issues desse repositório para. Os cards já criados a partir de issues ficam. Quando nenhum projeto usa mais um repositório, o KrakenDock apaga os dados dele. ## Branches, commits e pull requests nos cards ### Como citar o card Escreva a chave do card (`CHAVE-N`) em um destes lugares: | Onde | O que é lido | Exemplo | | ------------ | ------------------------------------- | --------------------------- | | Commit | a mensagem | `APP-42 corrige o login` | | Branch | o nome | `feat/APP-42-login` | | Pull request | o título e o nome da branch de origem | `[APP-42] Login com e-mail` | - Maiúsculas e minúsculas não importam: `feat/app-42-login` vale. - A chave não pode estar colada a outras letras ou números. `XAPP-42` e `APP-42a` não contam. - Um commit, uma branch ou um pull request pode citar vários cards. - Números de cards que não existem são ignorados. Um card na lixeira não recebe vínculos novos. - A descrição e os comentários do pull request não são lidos. - Um pull request vinculado continua atualizado (aberto, mergeado, fechado) mesmo que o título deixe de citar o card. Um pull request que nunca citou um card não é guardado. - Tags são ignoradas. Apagar uma branch no GitHub tira a branch do card. - O KrakenDock lê os commits que vêm no evento de push do GitHub. Commits que o GitHub não manda no evento não são buscados depois. ### O painel Desenvolvimento O painel **Desenvolvimento** fica no card, para os membros do projeto. Ele aparece quando o projeto tem algum repositório vinculado ou quando o card já tem atividade. Cada linha de resumo abre uma janela com as abas **Branches**, **Commits** e **Pull requests**: - **Branches**: nome, repositório e última atualização, com link para o GitHub. - **Commits**: SHA curto (com link), primeira linha da mensagem, autor, repositório e data. A janela mostra os 50 mais recentes e o total. - **Pull requests**: número, título, branch de origem → destino, autor e o estado: **Aberto**, **Rascunho**, **Mergeado** ou **Fechado**. O card se atualiza sozinho nas telas abertas quando chega um vínculo novo. Os pull requests abertos e mergeados dos cards também entram no feed de atividade da página inicial do projeto, só para membros. Visitantes de um projeto público não veem o painel nem os pull requests no feed. ### Criar a branch pelo card O painel sugere um nome de branch a partir do card: `fix/APP-42-titulo-do-card` para bugs e `feat/APP-42-titulo-do-card` para os outros tipos. - **Copiar nome da branch** e **Copiar comando git** (`git checkout -b …`) copiam a sugestão. - **Criar branch** abre uma janela com **Repositório**, **Nome da branch** e **Branch base** (vazia, usa a branch padrão do repositório). A branch é criada no GitHub e já fica vinculada ao card. - Se já existe uma branch com esse nome, ela é vinculada ao card, sem erro. - O nome não pode ser o da branch base nem o da branch padrão. - O botão só aparece para quem pode editar cards, com algum repositório vinculado. ### O que não acontece sozinho Mergear um pull request ou citar `fecha APP-42` num commit não move nem finaliza o card. Mova o card no board quando o trabalho terminar. Só a [sincronização de issues](#sincronizar-issues) muda cards sozinha, e apenas os cards criados a partir de issues. ## Importar issues A importação cria, de uma vez, um card para cada issue de um repositório vinculado. Use-a para trazer o histórico de um projeto que já existe no GitHub. É preciso a permissão **Gerenciar projeto**. ### Como importar 1. Em **Configurações** → **Repositórios**, clique no ícone **Importar issues** ao lado do repositório. 2. Escolha o **Board de destino** e clique em **Continuar**. O board Helpdesk não pode receber issues. 3. Revise o resumo: quantas issues abertas e fechadas, para quais colunas vão e o que acontece com as milestones. Confirme. 4. Acompanhe o progresso. Pode fechar a janela: a importação continua no servidor. O resultado fica na seção **Importações**, na mesma página, com o relatório de cada uma. Também dá para importar ao criar um projeto: em **Novo projeto**, o campo opcional **Importar issues do GitHub** pede a **Conta do GitHub** e o **Repositório**. O KrakenDock vincula o repositório e importa as issues para o primeiro board, logo depois de criar o projeto. ### Como cada issue vira card Todas as issues do repositório entram, abertas e fechadas, das mais antigas para as mais novas. Não há filtro. Pull requests não viram cards. | Na issue | No card | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Título | título (até 255 caracteres) | | Corpo | descrição, com o link da issue no fim (até 20.000 caracteres; o excesso é cortado com um aviso) | | Estado aberta | primeira coluna do board | | Estado fechada | primeira coluna de concluídos do board (ou a última coluna, se nenhuma for de concluídos) | | Labels | labels do projeto com o mesmo nome; as que faltam são criadas. A label `bug` torna o card do tipo Bug, e os outros cards são Tarefa | | Milestone | num board Scrum, uma milestone aberta vira sprint planejada (ou entra na sprint aberta de mesmo nome); nos outros casos, vira a label `milestone: NOME` | | Responsável | o primeiro responsável da issue que for membro do projeto (veja abaixo) | | Comentários | comentários do card, com `**@login** comentou em AAAA-MM-DD:` no início, sem autor no KrakenDock | | Autor | quem iniciou a importação fica como relator do card | Para achar o responsável, o KrakenDock procura um membro do projeto com aquele login do GitHub ligado à conta (pelo [login com GitHub](#login-com-github)). Se nenhuma conta tem esse login ligado, vale um membro cujo nome de usuário no KrakenDock seja igual ao login. Sem membro correspondente, o card fica sem responsável, e o relatório lista os logins. Os cards mostram o ícone do GitHub no board e o link "Ver issue #… no GitHub" no card. As menções `@usuario` do texto importado são registradas sem notificar ninguém. ### Duplicatas e reimportação - Cada card guarda o repositório e o número da issue. Importar de novo só traz as issues que ainda não estão no projeto, e as já importadas são puladas, mesmo que você tenha mudado o card. - A importação e a sincronização usam a mesma referência: uma issue importada não ganha um segundo card quando a sincronização é ligada, e vice-versa. - Desvincular e vincular de novo o mesmo repositório também não duplica. ### Limites da importação - Até 5.000 issues por importação (as mais antigas). O resumo avisa quando o repositório passa disso. - Até 500 comentários por issue (os mais recentes). Num repositório com muitas issues muito comentadas, pode vir menos, porque cada lote de 100 issues traz no máximo 5.000 comentários. O relatório avisa quando cortou. - Uma importação por vez em cada projeto. - Quando o GitHub limita as requisições, a importação pausa e retoma sozinha no horário indicado. - A importação não envia notificações nem webhooks por card. No fim, sai um único webhook `import.completed`. ## Sincronizar issues Com a sincronização ligada, os eventos do GitHub mantêm um card para cada issue do repositório, num board que você escolhe. A sincronização vai só do GitHub para o KrakenDock. ### Ligar a sincronização 1. Em **Configurações** → **Repositórios**, na linha do repositório, escolha o **Board de destino**. 2. Marque **Criar cards para issues do GitHub**. Quem pode ligar segue a regra de quem pode vincular repositórios (veja [Permissões](#permissoes)). Os outros gestores do projeto só veem em qual board a sincronização está ligada. A sincronização não busca as issues antigas: uma issue sem card ganha o card no próximo evento dela (uma edição, um comentário, um label). Para trazer todas de uma vez, [importe](#importar-issues) antes ou depois de ligar. Desligar não apaga os cards já criados. Excluir o board de destino desliga a sincronização. ### O que cada evento faz Cada evento muda só aquilo de que trata. O que você mudou no card dentro do KrakenDock fica, a menos que o GitHub mande uma mudança naquele mesmo campo. | Na issue | No card | | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Aberta (ou qualquer evento de uma issue sem card) | cria o card, como na [importação](#como-cada-issue-vira-card); uma issue fechada já nasce finalizada na coluna de concluídos | | Título ou corpo editado | atualiza o título ou a descrição | | Fechada | finaliza o card e o leva para a coluna de concluídos, se ele ainda não está numa | | Reaberta | desfaz a finalização e volta o card para a primeira coluna, se ele está numa coluna de concluídos | | Label adicionada ou removida | adiciona ou remove só aquela label | | Responsável adicionado ou removido | define o responsável do card (ele tem um só) ou o tira, se for a mesma pessoa; vale para membros do projeto com o GitHub ligado à conta | | Milestone adicionada ou removida | ajusta a sprint ou a label `milestone: NOME` | | Excluída | arquiva o card | - Na sincronização, relator, responsável e autor de comentário são achados pelo id da conta do GitHub ligada pelo [login com GitHub](#login-com-github), nunca pelo nome de usuário. Sem relator correspondente, o card mostra "GitHub" como relator. - O card pode mudar de board dentro do projeto: ele continua sincronizado onde estiver. - Cards arquivados ou na lixeira não mudam nem são recriados. Depois que um card some da lixeira de vez, o próximo evento da issue cria um card novo. - Um evento atrasado, mais antigo que o último aplicado, é ignorado. - As mudanças aparecem no histórico do card como "via GitHub", atualizam as telas abertas e disparam os webhooks do projeto. Ninguém é notificado. ### Comentários - Os comentários da issue são espelhados no card a partir do momento em que a sincronização está ligada. Comentários anteriores não são buscados. - Editar ou excluir o comentário no GitHub edita ou exclui o espelho. - O comentário espelhado leva o selo "via GitHub" e o link "ver no GitHub". Se a pessoa não tem conta no KrakenDock com o GitHub ligado, aparece o login dela do GitHub. - No KrakenDock, o comentário espelhado é só leitura. Para tirá-lo do card, é preciso a permissão **Excluir cards**, e ele não volta mesmo se for editado no GitHub. - Comentários de pull requests não são espelhados. ### O que não sincroniza - Nada vai do KrakenDock para o GitHub: comentar, mover ou finalizar o card não muda a issue. - Pull requests não viram cards (eles aparecem no painel [Desenvolvimento](#o-painel-desenvolvimento)). - Uma issue transferida para outro repositório não cria card. ## Login com GitHub Nas telas de entrada e de cadastro, **Continuar com GitHub** entra no KrakenDock com a sua conta do GitHub. - Se já existe uma conta no KrakenDock com o mesmo e-mail, verificado no GitHub, o GitHub fica ligado a ela. Senão, uma conta nova é criada. - O login com GitHub é independente da integração: ele não conecta repositórios. - Ligar o GitHub à sua conta faz o KrakenDock reconhecer você nas issues e nos commits: você pode virar responsável e autor de comentários nos cards sincronizados, e seus commits e pull requests mergeados contam como contribuições suas. ## Permissões ### No KrakenDock | Ação | Quem pode | | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | Conectar ou desconectar o GitHub | conta pessoal: você. Organização: **Gerenciar integrações** (Owner, por padrão) | | Vincular repositórios e ligar a sincronização de issues | **Gerenciar projeto** e ser dono da conexão: o dono do projeto pessoal ou, num projeto de organização, quem tem **Gerenciar integrações** | | Desvincular, sincronizar de novo e importar issues | **Gerenciar projeto** | | Ver o painel **Desenvolvimento** | membros do projeto (**Ver projeto**) | | Criar branch pelo card | **Editar cards** | | Excluir um comentário espelhado do GitHub | **Excluir cards** | A integração com o GitHub está disponível em todos os planos. ### No GitHub App Ao instalar, o GitHub mostra as permissões que o app pede: | Permissão | Para quê | | ------------------------------ | ------------------------------------------------------- | | Contents: leitura e escrita | ler as branches e criar a branch pelo card | | Pull requests: leitura | ler os pull requests | | Issues: leitura | importar e sincronizar issues, comentários e milestones | | Metadata: leitura | obrigatória em todo GitHub App | | Members (organização): leitura | confirmar que quem conecta uma organização é admin dela | O app recebe os eventos de push, pull request, repositório, issues e comentários de issue. Quando o app passa a pedir uma permissão nova (como Issues), o GitHub avisa o dono da instalação. Até ele aceitar nas configurações do app instalado, a parte que depende dela não funciona. Sem Issues, por exemplo, a importação falha com "O app do GitHub não pode ler as issues", e o resto da integração continua normal. ## Solução de problemas | Sintoma | Causa provável | | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | "A integração com o GitHub não está configurada neste servidor" | o servidor do KrakenDock não tem o GitHub App configurado; fale com o administrador | | O repositório não aparece em **Vincular repositório** | o app não tem acesso a ele na instalação, a conexão está numa conta diferente da dona do projeto ou está **Suspensa** | | O botão **Vincular repositório** não aparece | falta **Gerenciar projeto**, ou você não é dono da conexão (projeto pessoal de outra pessoa ou sem **Gerenciar integrações** na organização) | | A conexão é recusada ao voltar do GitHub | você não é dono da conta nem admin da organização no GitHub, ou a instalação já está conectada em outra conta do KrakenDock | | "Instalação solicitada" | você não é dono da organização no GitHub; um dono precisa aprovar, e depois você conecta de novo | | O commit não aparece no card | a chave está colada a outro texto, o repositório não está vinculado ao projeto do card, ou o commit foi enviado antes do vínculo | | O status do repositório ficou em **Falhou** | o GitHub recusou a leitura; confira o acesso do app e use o botão de sincronizar de novo | | A importação diz que o app não pode ler as issues | a instalação ainda não aceitou a permissão Issues; o dono aceita nas configurações do app no GitHub | | O card sincronizado ficou sem responsável | o responsável no GitHub não é membro do projeto ou não ligou o GitHub à conta do KrakenDock | | Uma issue antiga não virou card | a sincronização só cria o card no próximo evento da issue; importe as issues para trazer todas | | O pull request foi mergeado e o card não andou | é o esperado: só a sincronização de issues move cards | ## Perguntas frequentes ### O KrakenDock consegue ler meu código? O app lê branches, commits e pull requests dos repositórios que você liberou, e escreve só para criar uma branch quando você pede pelo card. Do código, o KrakenDock guarda só o que cita cards: nome da branch, mensagem e autor do commit, título e estado do pull request. Ele nunca lê o conteúdo dos arquivos. ### Posso usar o mesmo repositório em mais de um projeto? Sim. Vincule o repositório a cada projeto. Cada projeto reconhece as próprias chaves, e um commit pode citar cards de projetos diferentes. ### Comentar no card responde na issue? Não. A sincronização vai só do GitHub para o KrakenDock. Responda na própria issue, e o comentário volta para o card. ### Repositórios privados funcionam? Sim, desde que estejam liberados na instalação do app. Eles aparecem com o selo **Privado**. Só membros do projeto veem o painel **Desenvolvimento**, mesmo num projeto público. ## Veja também - [Primeiros passos](https://app.krakendock.com/docs/getting-started) - [Boards, cards e sprints](https://app.krakendock.com/docs/boards) - [Webhooks](https://app.krakendock.com/docs/webhooks), para avisar outros sistemas quando um card muda ou uma importação termina - [Projetos open source e contribuição externa](https://app.krakendock.com/docs/open-source) Ainda com dúvidas? Fale com a gente em [https://app.krakendock.com/help](https://app.krakendock.com/help).