Github Actions em projetos inner-source: ganhe agilidade nos code-reviews

Trabalhando há mais de dois anos em projetos inner-source, aprendemos algumas lições ao conviver com contribuições de desenvolvedores com diversos níveis de experiência.

Há desenvolvedores que já têm prática em contribuir e que dá até gosto de avaliar o pull request. Há aqueles que mal sabem o que é o CONTRIBUTING.md de um projeto, e há aqueles que sabem tudo isso, mas preferem não seguir as diretrizes/convenções do projeto em que estão contribuindo. Provavelmente isso seja algo comum em projetos inner-source, onde desenvolvedores que nunca contribuíram com projetos open-source (com todas as suas guidelines e boas práticas) são levados a contribuir com projetos compartilhados internamente em suas empresas.

É aí que entram as GitHub Actions, que podem ser uma ferramenta poderosa para ganhar agilidade nos code-reviews em projetos inner-source. Ao configurar as Actions de forma adequada, é possível automatizar a revisão de código, realizar análises estáticas automáticas, fornecer feedback automático aos desenvolvedores e realizar o build e testes automatizados a cada pull request. Isso facilita o processo de revisão, melhora a qualidade do código e agiliza a integração contínua durante a revisão. Com as Actions, é possível padronizar e automatizar parte do processo de revisão, permitindo que os desenvolvedores se concentrem em aspectos mais críticos do code-review.

No “episódio” de hoje, vamos falar um pouco sobre um pré-validador que ajuda a manter o padrão dos pull requests de seu repositório.

Esse workflow será executado a cada vez que for criado um pull request ou este sofrer atualizações e realiza as seguintes ações:

1. adiciona automaticamente assign para o autor do pull request
2. verifica se o título do pull request está de acordo com as regras do Conventional Commits
3. adiciona labels para ajudar na sinalização de problemas

Workflows vs Actions

No parágrafo anterior falei sobre criar um workflow, mas espera… não estávamos falando de actions?

No contexto do GitHub Actions, "workflow" e "actions" são conceitos diferentes, mas estão relacionados. Vamos entender cada um deles:

1. Workflow (Fluxo de Trabalho):

   • Um workflow é uma automação personalizada que você define para o seu projeto no GitHub. Ele consiste em um conjunto de ações que são executadas de forma automática em resposta a eventos específicos no repositório.
   • Os eventos podem incluir push de código, criação de pull requests, criação ou fechamento de issues, entre outros.
   • Um workflow é definido em um arquivo YAML no diretório .github/workflows do seu repositório.

   Aprenda mais sobre na documentação oficial do Github Actions:
   Acionando um fluxo de trabalho - GitHub Docs

2. Actions (Ações):

   • As ações são unidades reutilizáveis de automação que podem ser combinadas em workflows. Elas são os componentes individuais que executam tarefas específicas.
   • Uma ação pode ser criada por você ou por terceiros (disponíveis no Github Marketplace), e pode ser compartilhada e utilizada em diferentes projetos e workflows.
   • As ações podem ser usadas para realizar diversas tarefas, como compilar código, executar testes, fazer o deploy de uma aplicação, entre outras coisas.

Definindo a condição para executar o workflow

Nosso workflow será executado a cada vez que for criado um pull request ou este sofrer atualizações.

name: "Pull Request Validator"

on:
  pull_request:
    types: [ opened, edited, labeled, unlabeled, synchronize ]

Assign automático ao autor do pull request

A primeira ação a ser definida pode parecer bobagem, mas no dia a dia de uma equipe é muito importante: definir quem é o responsável pelo pull request!

Vamos criar uma action dentro da seção jobs chamada auto-assign :

jobs:
  auto-assign:
    name: Assign PR to creator
    runs-on: ubuntu-latest

    steps:
      - name: Assign PR to creator
        uses: thomaseizinger/assign-pr-creator-action@v1.0.0
        if: github.event_name == 'pull_request' && github.event.action == 'opened'
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}

Análise do título do pull request

Projetos inner-source precisam seguir um padrão de commit para evitar que o histórico de commits fique bagunçado e confuso. Imagine procurar por uma mudança específica na sua branch main e no histórico constam vários commits em português e muitos outros em inglês… Como procurar por uma determinada correção, sendo que cada dev usou um padrão? E em qual língua? Bom, é importante definir um padrão de escrita e principalmente definir o idioma utilizado!

Hoje em dia utiliza-se muito o padrão do Conventional Commits que é uma convenção simples, fácil de usar e que se dá muito bem com a especificação de versionamento semântico SemVer. Em resumo, novas features têm o prefixo feat, correções são fix, alterações em arquivos do projeto são chore.

Na action abaixo, vamos definir uma análise no título do pull request e validar se está de acordo com as regras do Conventional Commits. Caso não esteja, será adicionado um comentário com exemplos de uso.

  lint-pr:
    name: Lint pull request title
    runs-on: ubuntu-latest

    steps:
      - name: Lint pull request title
        uses: jef/conventional-commits-pr-action@v1
        with:
          comment: true
          token: ${{ secrets.GITHUB_TOKEN }}

Adicione labels automaticamente

Usar labels em um pull request é muito útil, pois podemos sinalizar algum problema ou facilitar na triagem de pull requests que demandam mais atenção, por exemplo.

Vamos supor que nas regras de contribuição desse repositório, é obrigatório atualizar o arquivo de changelog a cada alteração. Para isso vamos utilizar a action labeler.

  add-label:
    name: Add labels
    runs-on: ubuntu-latest
    steps:
      - name: Github Actions Checkout
        uses: actions/checkout@v3

      - name: Labeler
        uses: actions/labeler@v4.0.3
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}
          configuration-path: .github/labeler.yml
          sync-labels: true

As labels e as regras de aplicação ficam no arquivo .github/labeler.yml que precisará ser criado.

missing-changelog-update:
  - any: [ '*' ]
    all: [ '!CHANGELOG.md' ]

Dessa forma, quando esquecerem de atualizar o arquivo CHANGELOG.md, será automaticamente adicionada a label missing-changelog-update!

💡 Caso tenha problemas de permissão ao rodar o workflow, pode ser que precise ajustar as permissões de acesso ao GITHUB_TOKEN no seu repositório.

Conclusão

Neste artigo, exploramos como as GitHub Actions podem ser uma ferramenta poderosa para agilizar os code-reviews em projetos inner-source. Discutimos a importância de automatizar processos repetitivos, como a atribuição automática de pull requests, a verificação de títulos de pull requests conforme as regras do Conventional Commits e a adição automática de labels.

Ao implementar essas práticas, você pode melhorar significativamente a eficiência e a qualidade das revisões de código em seu projeto, permitindo que os desenvolvedores se concentrem em aspectos mais críticos e criativos do desenvolvimento.

Próximos Passos

1. Implemente o Workflow: Comece configurando o workflow de validação de pull requests em seu repositório.
2. Explore Mais Actions: Visite o GitHub Marketplace para descobrir outras ações que podem ser úteis para o seu fluxo de trabalho.
3. Personalize Conforme Necessário: Ajuste as ações e workflows conforme as necessidades específicas do seu projeto.

Recursos Adicionais

• Documentação Oficial do GitHub Actions
• Conventional Commits
• SemVer

Implementar essas práticas pode parecer um desafio no início, mas os benefícios a longo prazo em termos de qualidade e eficiência do código valem o esforço.

Boa sorte e bons code-reviews!