Como Criar e Usar uma Ação Composta no GitHub Actions

Como Criar e Usar uma Ação Composta no GitHub Actions

As ações compostas do GitHub Actions são uma forma poderosa de organizar e reutilizar etapas de automação dentro dos seus fluxos de trabalho. Ao agrupar várias tarefas em uma única ação, você pode simplificar o gerenciamento de workflows e reduzir a duplicação de código.

Neste artigo, você aprenderá como criar uma ação composta usando um exemplo prático de ação que imprime uma saudação personalizada, gera um número aleatório e executa um script.

O que são ações compostas?

Uma ação composta é composta por múltiplos passos encapsulados em um único arquivo de metadados (action.yml) e pode ser reutilizada em diferentes fluxos de trabalho. Essa estrutura facilita a manutenção, a distribuição e o reaproveitamento de lógica comum entre diferentes projetos.

Exemplo prático: Criando uma ação “Hello World”

Vamos construir uma ação que:

• Recebe um nome de entrada e exibe uma mensagem de saudação.
• Gera um número aleatório como saída.
• Executa um script final chamado goodbye.sh.

1. Criando o repositório

Crie um novo repositório no GitHub com um nome como hello-world-composite-action. Em seguida, clone o repositório em sua máquina local:

git clone https://github.com/SEU_USUARIO/hello-world-composite-action.git
cd hello-world-composite-action

2. Criando o script goodbye.sh

No diretório raiz do projeto, crie um script que apenas imprima “Goodbye”:

echo "echo Goodbye" > goodbye.sh
chmod +x goodbye.sh

Adicione esse arquivo ao repositório:

git add goodbye.sh
git commit -m "Add goodbye script"
git push

3. Criando o arquivo action.yml

Agora, crie o arquivo que define a lógica da ação composta:

name: "Hello World"
description: "Greet someone"
inputs:
  who-to-greet:
    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:
    - name: Set Greeting
      run: echo "Hello $INPUT_WHO_TO_GREET."
      shell: bash
      env:
        INPUT_WHO_TO_GREET: ${{ inputs.who-to-greet }}

    - name: Random Number Generator
      id: random-number-generator
      run: echo "random-number=$(echo $RANDOM)" >> $GITHUB_OUTPUT
      shell: bash

    - name: Set GitHub Path
      run: echo "$GITHUB_ACTION_PATH" >> $GITHUB_PATH
      shell: bash
      env:
        GITHUB_ACTION_PATH: ${{ github.action_path }}

    - name: Run goodbye.sh
      run: goodbye.sh
      shell: bash

Adicione, faça o commit e o push desse arquivo:

git add action.yml
git commit -m "Add action"
git push

4. Criando uma tag

Para usar a versão da ação no workflow, é recomendável criar uma tag:

git tag -a v1 -m "First release"
git push --follow-tags

Testando sua ação em um workflow

Para verificar se a ação funciona corretamente, adicione um workflow em outro repositório em .github/workflows/main.yml:

on: [push]

jobs:
  hello_world_job:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - id: foo
        uses: SEU_USUARIO/hello-world-composite-action@v1
        with:
          who-to-greet: "Mona the Octocat"
      - run: echo random-number "$RANDOM_NUMBER"
        shell: bash
        env:
          RANDOM_NUMBER: ${{ steps.foo.outputs.random-number }}

Quando esse workflow rodar, ele deve imprimir a saudação personalizada, “Goodbye”, e um número aleatório.

Organizando a ação dentro do mesmo repositório

Você também pode manter sua ação composta dentro do próprio repositório onde será usada. Para isso:

• Crie a pasta .github/actions/hello-world-composite-action
• Mova os arquivos goodbye.sh e action.yml para essa pasta.

No workflow, a referência à ação será diferente:

uses: ./.github/actions/hello-world-composite-action

Outros exemplos úteis

Veja abaixo alguns repositórios que disponibilizam ações compostas avançadas:

• microsoft/action-python
• microsoft/gpt-review
• tailscale/github-action

Conclusão

As ações compostas são uma excelente maneira de estruturar e organizar fluxos de trabalho no GitHub Actions. Elas trazem praticidade para desenvolvedores que desejam automatizar tarefas sem repetir código, garantindo mais produtividade e manutenção mais simples.

E agora queremos saber de você: Já pensou em criar uma ação composta própria para agilizar seus workflows no GitHub? Compartilhe nos comentários!