Integrando Jira e Git Hook para automatizar a validação de mensagens de commit
No artigo anterior, apresentamos o Git Hook e a sua capacidade de automatizar processos envolvendo o controle de versão. Além disso, passamos por vários hooks disponíveis e como cada um deles funciona.
Se você ainda não leu o artigo anterior, dá uma olhadinha rápida porquê vai ser importante para conseguirmos continuar: Git Hooks, o que são e como utilizá-los para descobrir commits duplicados?
Neste artigo, continuaremos a discussão e criaremos um hook de commit-message, onde além de analisarmos nossas mensagens de commit, estabeleceremos conexão com a API do Jira para potencializar nossas análises.
Definindo estrutura e regras para mensagem de commit
Antes de mais nada, é importante ressaltar que a padronização das regras de mensagem de commit são definidas pelo time de desenvolvimento. Dito isso, a estrutura utilizada no nosso exemplo tem como base as seguintes regras:
- Não é permitido realizar commits em branches específicas, como master, develop e release. Essas branches podem receber apenas ações de merge.
- Toda mensagem de commit deve iniciar com a chave da issue no jira a qual se refere o código que está sendo enviado para o git. Por exemplo:
JIRA-1234: Construindo Git Hook referente a verificação de mensagens de commit.
- Não é indicado que sejam realizados commits usando a chave de subtarefas.
Agora vamos alongar nossos dedos e começar a codar!
Conectando com a API do jira
Para que seja verificado se a chave utilizada na mensagem de commit se refere a uma tarefa ou subtarefa, é preciso que nos conectemos ao Jira. Para isso utilizaremos a API fornecida pela Atlassian.
O código abaixo, escrito em Python, apresenta o método utilizado para realizar a conexão bem como recuperar a issue referente a chave utilizada na mensagem de commit.
Para que seja feita a conexão com a API do Jira, é preciso que façamos o set das variáveis:
- server: URL do servidor que hospeda o nosso projeto no Jira, por exemplo: https://minhaempresa.atlassian.net/;
- api_token: token gerado pela Atlassian (é possível gerar o token através do site https://id.atlassian.com/manage-profile/security/api-tokens);
- user_email: e-mail utilizado para acessar o Jira.
Com a configuração desses dados, recuperamos a issue que estamos trabalhando através da execução do verbo get no caminho /issue da API.
O tempo para a realização da conexão e a recuperação dos dados da issue podem variar e acabar sendo um problema para o nosso hook, uma vez que depende tanto da estabilidade da internet quanto da disponibilidade do serviço oferecido pela Atlassian. Por essa razão, para evitarmos que o tempo de resposta seja um problema, na linha 27 configuramos um signal para enviar uma mensagem após 5 segundos (esse tempo pode ser configurado através da variável time_out). A linha 44 desativa o signal. Desse modo, caso a conexão com a API leve mais que 5 segundos, o signal enviará uma mensagem que disparará um callback pré-configurado que abortará a tentativa de conexão e dará ao usuário a opção de prosseguir sem que seja feita a análise utilizando os dados do Jira.
A configuração do signal é feita da seguinte forma:
Criando objetos a partir da API
Uma vez que obtivermos como resposta a issue do Jira, criaremos, a partir do JSON retornado, os objetos que utilizaremos na análise.
O código abaixo chama a função connect_and_get_issue definida anteriormente, e utiliza de seu retorno para construir os objetos em questão.
A construção dos objetos é baseada em campos específicos definidos no Enum JiraFieldsEnum. Como a documentação do Enum afirma, os campos definidos e os ids utilizados variam de projeto para projeto e possivelmente precisarão ser adaptados.
Com a construção dos objetos podemos começar nossas análises e validações a respeito da mensagem de commit :D
Validando commit
A execução da nossa validação deve ser feita de acordo com as regras de commit definidas pelo time, e no caso do nosso exemplo apresentadas anteriormente.
O método principal do nosso hook irá chamar o método valid_commit_message que será responsável por realizar a lógica de validação, como apresentada abaixo.
Após a execução das verificações das nossas regras de estrutura e mensagem de commit, direcionadas pela função valid_commit_message, retornaremos para o método principal o resultado da validação. Desse modo, o nosso método será capaz de definir o retorno que deverá ser dado ao Git Hook, conforme demonstrado abaixo.
Conforme apresentamos no artigo anterior, o hook de commit-message tem como entrada o path do arquivo onde se encontra a mensagem de commit, e caso receba 0 como retorno prossegue com a execução do commit, caso contrário aborta o processo. Por essa razão as linhas 11 e 13 realizam um sys.exit().
Mas Manollo, por quê usar um exit e não simplesmente um return?
Excelente pergunta!
A essa altura você já deve ter percebido que estamos trabalhando com a linguagem Python e não com shell script, como fizemos no artigo anterior, certo? Se pensarmos bem, a definição que demos aos Git Hooks no outro artigo foi de serem shell scripts executados através do disparo de algumas ações envolvendo comando de git.
Então não faz sentido criarmos esse hook utilizando as funções Python que criamos até agora, certo?
Mais ou menos!
Acontece que nós não criamos especificamente um hook, criamos uma aplicação em Python que nos permite verificar os commits. E essa aplicação Python pode (e será) chamada pelo nosso hook.
Por essa razão não utilizamos um return na função principal, para que ele no lugar de dar um retorno na execução da função saia do programa e apresente o retorno informado ao seu caller, o nosso hook commit-message.
Configurando Git Hook
Como acabamos de descobrir, o nosso código até o momento não se refere ao Git Hook, em si, mas a uma aplicação que será chamada pelo hook.
Mas como podemos fazer isso?
Bom, é bem simples. Executamos a chamada como fazemos em linha de comando. O código abaixo representa o nosso Git Hook.
Só isso?
Sim, só isso! O nosso código basicamente passa a execução para o código Python que criamos e direciona para ele o parâmetro com o path do arquivo contendo a mensagem de commit.
Desse modo, não é necessário que façamos implementações complicadas usando shell scripts.
Do it the way you want!
Instalando o novo Git Hook
A instalação do nosso novo hook não difere do que fizemos anteriormente, no primeiro artigo sobre Git Hooks. O que precisamos fazer é salvar o nosso shell script que faz a chamada para o código Python como commit-message (lembrando que o git só sabe qual hook chamar, pelo nome que o hook recebe).
Feito isso, basta enviar tanto o arquivo commit-message quanto o commit-verify.py (nosso código em Python) para dentro da pasta .git/hooks dentro do nosso projeto. E então dar permissão de execução para ambos arquivos.
Pronto! Agora já conseguiremos utilizar o nosso novo hook para validar nossas mensagens de commit de forma automatizada. E o resultado é esse aqui :D
That's it!
Qualquer dúvida ou sugestão, estou a disposição!
Nos vemos num próximo artigo…
