GitHub para projetos de software: vincule repositórios e branches
A integração com o GitHub mostra branches, pull requests e commits nas issues a que pertencem e permite começar uma branch a partir de uma issue. Um proprietário ou administrador conecta o GitHub uma vez para todo o espaço de trabalho. Depois, você vincula repositórios a projetos de software individuais.
Visão rápida
| O que é | Visão da atividade do GitHub no nível da issue, mais criação de branches |
| Onde encontrar | Configurações do projeto, Integrações; a seção Desenvolvimento em uma issue |
| Quem conecta o GitHub | Somente o proprietário ou administrador do espaço de trabalho |
| Quem vincula repositórios | Pessoas com permissão nas configurações do projeto |
| Funciona em | Somente projetos de software |
Para as configurações gerais, veja configurações do projeto de software.
Como conectar o GitHub
Só um proprietário ou administrador do espaço de trabalho pode fazer isso. Os demais veem o botão desativado com “Somente proprietários e administradores da equipe podem conectar o GitHub.”
- Abra a engrenagem das configurações do projeto e depois Integrações. Você também pode ir em Configurações e depois Integrações.
- Clique em Conectar GitHub.
- Instale o app no GitHub e escolha a conta.
- Você volta ao Worklenz com “GitHub conectado com sucesso.”
Se uma organização precisar aprovar a instalação, você vê “A instalação foi solicitada. Um proprietário da organização precisa aprová-la.”
O cartão da conexão mostra a conta, uma etiqueta Conectado, quantos repositórios estão disponíveis e os botões Atualizar repositórios, Sincronizar status e Desconectar. Um espaço de trabalho pode conectar uma conta do GitHub, e uma conta do GitHub só pode pertencer a um espaço de trabalho.
Como vincular um repositório a um projeto
- Abra o projeto de software e clique na engrenagem e depois em Integrações.
- No bloco do GitHub, escolha um repositório em Selecionar um repositório para vincular.
- Clique em Vincular. Você vê “Repositório vinculado.”
A linha vinculada mostra o nome do repositório, uma etiqueta Privado, se for o caso, e uma Branch base editável.
Como as issues se conectam à atividade do GitHub?
Inclua a chave da issue, como KEY-104, no nome de uma branch, em uma mensagem de commit ou no título de um pull request. As chaves não diferenciam maiúsculas de minúsculas, e só vale a chave do seu próprio projeto. Palavras de fechamento como fixes, closes ou resolves em uma mensagem de commit fecham a issue; “Fixes KEY-1 and KEY-2” fecha as duas.
O que o painel Desenvolvimento mostra?
Abra uma issue e encontre Desenvolvimento. Ele lista:
- Pull requests com número, título, branch, autor e um status como Aberto, Rascunho, Aprovado, Alterações solicitadas, Mesclado ou Fechado.
- Branches, com a etiqueta Excluída se foram removidas do GitHub.
- Commits, cinco no começo, depois Mostrar todos e Mostrar menos.
Se nada estiver vinculado, ele diz “Nenhuma atividade do GitHub ainda” e lembra você de incluir a chave da issue. Se nenhum repositório estiver vinculado, ele leva você para Configurações do projeto > Integrações.
Como criar uma branch a partir de uma issue
Você precisa de um repositório vinculado e do direito de criar tarefas. Convidados não podem.
- Abra a issue e vá para Desenvolvimento.
- Clique em Criar branch.
- Escolha o Repositório, um prefixo de Tipo (feature/, bugfix/, hotfix/ ou chore/), um Nome da branch e a Branch base. O nome começa com a chave da issue mais o título.
- Crie. Você vê “Branch criada.” com um comando para copiar e executar localmente.
Os nomes de branch usam letras, números, pontos, hifens, sublinhados ou barras.
Se falhar, você pode ver “Já existe uma branch com este nome”, “A branch base não foi encontrada neste repositório” ou uma mensagem de que o app do GitHub precisa de acesso de escrita ao conteúdo. Peça a um administrador para conceder.
Como remover um vínculo de uma issue
Use o ícone de lixeira ao lado de uma branch, pull request ou commit e depois Remover. Isso apenas o oculta na tarefa. Nada muda no GitHub.
Como desvincular um repositório
Em Integrações, use o ícone de excluir na linha vinculada e confirme Desvincular. Os vínculos existentes nas issues permanecem, mas a atividade nova deixa de ser acompanhada. Para desconectar o GitHub de todo o espaço de trabalho, um proprietário ou administrador clica em Desconectar. Os vínculos existentes e o histórico são mantidos e voltam a valer se você reconectar.
Automação de status e importação de issues
Cada repositório vinculado tem uma Automação de status: escolha um status para Branch criada, Pull request aberto e Pull request mesclado, ou deixe Não alterar o status. As issues nunca andam para trás nem saem de um status de concluído.
Um bloco de Importação de issues permite trazer issues do GitHub com Importar issues: filtre por Abertas, Fechadas ou Todas, filtre por etiqueta, escolha o Backlog ou uma sprint e importe de 1 a 50 por vez. Pull requests são ignorados, e issues já importadas mostram “Importada como {key}”.
Boas práticas
- Coloque a chave da issue em todo nome de branch, mensagem de commit e título de pull request, porque é assim que o Worklenz liga a atividade do GitHub a uma issue.
- Use palavras de fechamento como fixes ou closes só quando o commit realmente conclui a issue, porque elas fecham todas as chaves de issue listadas na mensagem.
- Peça a um proprietário ou administrador do espaço de trabalho que conecte o GitHub uma vez, porque só eles podem e um espaço de trabalho pode conectar uma conta do GitHub.
- Defina a Automação de status para branch criada, pull request aberto e pull request mesclado, porque o Worklenz nunca move uma issue para trás nem a tira de um status de concluído.
- Desvincule o repositório quando parar de usá-lo, porque remover um vínculo de uma issue apenas o oculta na tarefa e não muda nada no GitHub.