Quando usar Reusable Workflow ou Composite Action no GitHub Actions?

Neste artigo, vamos aprofundar as diferenças entre os conceitos de reusable workflow (fluxo de trabalho reutilizável) e Composite Action (ação composta) no GitHub Action. 

Ambos os conceitos permitem reaproveitar a execução de um conjunto de operações, evitando assim duplicação de comandos ou de setup de ambiente sendo realizados em diversos workflows dentro de um conjunto de repo ou de uma Org.

Vamos começar pelo que cada um desses conceitos representa, em seguida, compararemos eles para saber em quais situações pode fazer mais sentido usar um ou outro com nossos workflows do GitHub Actions.

O que é um Reusable Workflow?

O conceito de reusable workflow foi introduzido em Novembro 2021 e vem ganhando popularidade desde então. 

Os benefícios dos fluxos de trabalho reutilizáveis são bastante simples:

• Segue o princípio DRY (Don’t Repeat Yourself);
• Evita a duplicação de workflows;
• Facilita a manutenção de workflows;
• Nos permite criar novos workflows mais rapidamente, aproveitando o trabalho de outras pessoas;
• Promove as melhores práticas usando workflows bem projetados e já testados.

De acordo com uma observação do Radar de Tecnologia da Thoughtworks:

“Os workflows reutilizáveis no GitHub Actions trazem modularidade ao design do pipeline, permitindo a reutilização parametrizada mesmo entre repositórios (desde que o repositório de fluxo de trabalho seja público ou interno). Eles suportam o uso explícito de valores confidenciais como segredos e podem retornar valores para o job inicial.

Com algumas linhas de YAML, o GitHub Actions agora oferece o tipo de flexibilidade que você vê com CircleCI Orbs ou Azure Pipeline Templates, mas sem ter que deixar o GitHub como plataforma.”

O que é uma Composite Action?

Uma Composite Action (ação composta) é um dos três tipos diferentes de ações personalizadas que podem ser criadas no GitHub (composta, JavaScript e Docker). 

A principal diferença é que o arquivo de metadata (action.yml) de uma ação composta possui um campo runs com uma lista de etapas (steps) a serem executadas em oposição a um programa a ser executado.

runs:
      using: "composite"
      steps:
	[ … ]

Composite Actions não podem usar segredos direta. Os benefícios de usar uma Composite Action são:

• Segue o princípio DRY (Don’t Repeat Yourself);
• Evita a duplicação de etapas (steps);
• Facilita a manutenção de etapas (steps) separando elas em ações (por responsabilidade);
• Nos permite criar novos workflows mais rapidamente, aproveitando o trabalho de outras pessoas;
• A natureza descritiva de um arquivo action.yml melhora a legibilidade de um workflow do GitHub ao avaliar entradas e saídas necessárias.

Diferenças entre Action e Reusable workflow

Antigamente a diferença era muito clara, pois uma Composite Action permitia apenas usar scripts bash nelas. Mas agora que temos a possibilidade de explorar outras actions como passos nas Composites Actions assim que usar condições através da palavra reservada if nas etapas (também lançado em novembro 2021), a diferença é mais sutil. 

Mesmo assim, existem 5 diferenças que merecem ser destacadas, são elas:

1. Segredos

A primeira diferença está relacionada a segredos. 

mente usando a terminologia ${{ secrets.SECRET_NAME }}, os segredos precisam ser enviados via inputs, o que implica que serão tratados como textos (e não ofuscados na execução da action caso expostos na implementação).

Reusable workflows, por outro lado, podem consumir segredos, herdando eles do workflow principal (o workflow chamando o reusable workflow), ou sendo encaminhados através de parâmetros do workflow, conforme imagem abaixo:

on:
  workflow_call:
    inputs:
      config-path:
        required: true
        type: string
    secrets:
      envPAT:
        required: true

Fonte: Github Doc 

Obs.: É bom lembrar que devemos sempre considerar que o código pode executar entradas não confiáveis de possíveis invasores. Certos contextos devem ser tratados como entrada não confiável, pois uma pessoa invasora pode inserir seu próprio conteúdo malicioso. Para obter mais informações, consulte “Compreendendo o risco de injeções de script (inglês)“.

2. Armazenamento

A segunda diferença é o armazenamento dos arquivos.

Composite Actions requer seu próprio repositório, que deve ser público, e um arquivo de metadados (action.yaml). Se você quiser executar o script de um arquivo, também precisará do arquivo de script no mesmo repositório.

Reusable workflows, por outro lado, podem ser armazenados em seu repositório como arquivos de outros workflows no formato YAML, na pasta .github/workflows. Também é possível criar um repositório centralizado para armazenar vários fluxos de trabalho reutilizáveis.

3. Jobs

A terceira diferença está relacionada ao uso de jobs.

Composite Actions permitem executar uma sequência de etapas (steps), mas não é possível executar múltiplos jobs através de uma Composite Action. Inclusive, uma Composite Action nem especifica a palavra job no arquivo action.yaml.

name: 'Hello World'
description: 'Greet someone'
inputs:
  who-to-greet:  # id of input
    description: 'Who to greet'
    required: true
    default: 'World'

outputs:
  random-number:
    description: "Random number"
    value: ${{ steps.random-number-generator.outputs.random-number }}
runs:
  using: "composite"
  steps:
    - run: echo Hello ${{ inputs.who-to-greet }}.
      shell: bash
    - id: random-number-generator
      run: echo "random-number=$(echo $RANDOM)" >> $GITHUB_OUTPUT
      shell: bash
    - run: echo "${{ github.action_path }}" >> $GITHUB_PATH
      shell: bash
    - run: goodbye.sh
      shell: bash

Fonte: Github Doc

Reusable workflows, por outro lado, definem jobs dentro deles, ou seja, você pode ter quantos trabalhos quiser em um único reusable workflow.

name: Reusable workflow example


on:
  workflow_call:
    inputs:
      config-path:
        required: true
        type: string
    secrets:
      token:
        required: true
 
jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/labeler@v4
      with:
        repo-token: ${{ secrets.token }}
        configuration-path: ${{ inputs.config-path }}

Fonte: Github Doc

Uma consequência disso é que se você precisa especificar onde o job será executado, ou seja, se seu job precisar ser executado em um runner ou máquina específica (ex: self-hosted runner), você precisará usar reusable workflow.

4. Encadeamento

A quarta diferença é o encadeamento.

Composite Actions podem ser encadeadas em até 10 camadas. Isso significa que você pode criar uma Composite Action que tenha outra Composite Action como uma de suas etapas (step), e assim por diante até o 10º nível.

Reusable workflows, por outro lado, não podem chamar outro reusable workflow, quer dizer, você não pode encadeá-los.

5. Logs

A quinta diferença está relacionada aos logs.

A execução de uma Composite Action retorna um único log de uma única etapa, mesmo que contenha várias etapas contidas nela.

Já com Reusable workflows, temos logs muito ricos do que está acontecendo, e cada tarefa e etapa é registrada de forma independente em tempo real.

Ganhe tempo usando fluxo de trabalho reutilizáveis e ações compostas

Por hoje é isso, galera! Esperamos que este artigo tenha esclarecido a diferença entre reusable workflows e composite actions no GitHub Actions.

Resumindo: ambas as abordagens permitem economizar muito tempo na hora de criar novos workflows, aproveitando operações já implementadas e testadas em outros momentos.

Composites Actions são geralmente mais isoladas e genéricas, enquanto os reusable workflows são mais ricos em recursos e atraem cenários um pouco mais específicos (com uso de segredos, self-hosted runner, entre outros…).

Quem quiser consultar alguns exemplos com GitHub Actions, compartilhamos aqui alguns exemplos em repositórios pessoais para ambas as abordagens:

Composite Actions:

• assert-command-line-output
• clone-github-repo-action
• create-other-repo-branch-action
• git-commit-push 

Reusable workflows:

• Exemplo 1 → workflow principal
• Exemplo 2 + Exemplo 3 + Exemplo 4 → workflow principal
• Exemplo 5 → workflow principal

Lembrando que a documentação do Github Actions em português é muito boa e vale a leitura.

Aproveite para continuar acompanhando os artigos e podcasts da Zup aqui pela Central de Conteúdos!

Referências

• A Deep Dive into GitHub Actions’ Reusable Workflows – Medium
• Radar de Tecnologia – Thoughtworks
• Create a Composite Action – Github