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. Use-a para colar num assistente de IA ou na documentação interna do seu time.
| 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.
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 as que já existem e ligue a sincronização para as próximas.
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.
Cada projeto só enxerga as conexões da conta dona dele:
| Projeto | Onde conectar | Quem pode conectar |
|---|---|---|
| Pessoal (seu) | Configurações → Integrações | 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.
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á.
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.
APP e API usam o mesmo repositório, vincule-o aos dois.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.
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.
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 |
feat/app-42-login vale.XAPP-42 e APP-42a não contam.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:
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.
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.
git checkout -b …) copiam a sugestão.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 muda cards sozinha, e apenas os cards criados a partir de 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.
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.
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). 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.
import.completed.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.
Quem pode ligar segue a regra de quem pode vincular repositórios (veja Permissões). 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 antes ou depois de ligar.
Desligar não apaga os cards já criados. Excluir o board de destino desliga a sincronização.
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; 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 |
Nas telas de entrada e de cadastro, Continuar com GitHub entra no KrakenDock com a sua conta do GitHub.
| 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.
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.
| 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 |
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.
Sim. Vincule o repositório a cada projeto. Cada projeto reconhece as próprias chaves, e um commit pode citar cards de projetos diferentes.
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.
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.
Ainda com dúvidas? Fale com a gente em https://app.krakendock.com/help.