Guia de Dicas para GitHub Actions - Estrutura padrão e uma lista das ações mais úteis

Um pouco sobre as ações comuns do GitHub e sua estrutura.

Conteúdo da página

GitHub Actions é uma plataforma de automação e CI/CD dentro do GitHub, usada para construir, testar e implantar seu código com base em eventos como pushes, pull requests ou em um agendamento.

Além do GitHub padrão, você pode usar GitHub Actions em um servidor Gitea auto-hospedado.

github actions flow

Este resumo abrange a estrutura das GitHub Actions, uma breve descrição e as ações mais comuns usadas em fluxos de trabalho de código aberto e comerciais. As ações abrangem ferramentas oficiais, da comunidade e de terceiros, apoiando automação desde builds e testes até implantação, gestão de liberações, QA e notificações.

Estrutura de Configuração Básica

Workflows de GitHub Actions são definidos em arquivos YAML localizados na pasta .github/workflows dentro do repositório.

name: Nome do Workflow
on:
  push:
    branches: [ main ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Configurar Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Executar testes
        run: npm test
  • O bloco on especifica eventos de gatilho.
  • Cada job é executado em seu próprio runner.
  • steps podem executar comandos de shell ou chamar ações reutilizáveis.

Componentes Principais do Workflow

Componente Descrição
Workflow Processo automatizado (YAML) acionado por um evento
Evento Atividade que aciona o workflow (push, pull_request, etc.)
Job Série de passos executados em um runner, pode ser executado sequencialmente ou em paralelo
Passo Cada comando ou ação em um job
Runner VM ou container onde os jobs são executados
Ação Extensão/reutilizável encapsulando uma tarefa

Eventos de Gatilho

  • push
  • pull_request
  • schedule (usando sintaxe cron)
  • workflow_dispatch (gatilho manual, permite parâmetros de entrada)
  • release, issue, etc.

Exemplo:

on:
  push:
    branches: [ main ]
  workflow_dispatch:
    inputs:
      environment:
        description: 'Ambiente de implantação'
        required: true
        default: 'produção'
        type: string

Ações Úteis Integradas

Ação Propósito Parâmetros Comuns
actions/checkout Verificar código do repositório ref, token, submodules, persist-credentials
actions/setup-node Configurar ambiente Node.js node-version, cache, architecture, check-latest
actions/setup-python Configurar Python python-version, architecture
actions/cache Cachear dependências path, key, restore-keys
docker/build-push-action Construir e empurrar imagens Docker context, file, platforms, tags, push, build-args
actions/upload-artifact Carregar artefatos de build name, path, if-no-files-found
actions/download-artifact Baixar artefatos name, path
github/email-actions Enviar notificações por e-mail to, subject, content, attachments
peter-evans/create-pull-request Criar PRs via workflow branch, title, body, labels, base
actions/github-script Executar JavaScript arbitrário no workflow script, github-token

Parâmetros de Ação

Parâmetros Gerais para Qualquer Chamada de Ação:

- name: Alguma Ação ou Passo
  uses: owner/repo@ref
  with:
    param1: value
    param2: value
  env:
    ENV_VAR: value
  if: ${{ condition }}
  run: command_to_run
  shell: bash|pwsh|python|sh
  continue-on-error: true|false
  • with: argumentos passados para a ação (veja a documentação da ação para todas as opções)
  • env: variáveis de ambiente para o passo
  • if: execução condicional
  • run: comandos de shell (se não estiver usando uma ação)
  • shell: shell usado para executar o passo
  • continue-on-error: continuar mesmo se o passo falhar

Definindo Entradas de Ação Personalizadas

Em sua metadados de ação (action.yml):

inputs:
  example-input:
    description: 'Um exemplo de entrada'
    required: false
    default: 'valor-padrão'

Quando usado em um workflow:

- uses: my/action@v1
  with:
    example-input: 'valor-personalizado'

Acessado como variável de ambiente INPUT_EXAMPLE_INPUT quando a ação é executada.

Exemplo: Workflow com Parâmetros Manuais

name: Deploy
on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Ambiente de implantação'
        required: true
        default: 'produção'
        type: string
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout do código
        uses: actions/checkout@v4
      - name: Implantar no ambiente
        run: echo "Implantando no ${{ github.event.inputs.environment }}"

Mercado de Ações

  • Milhares de ações reutilizáveis estão disponíveis no GitHub Marketplace.
  • Categorias incluem: implantações em nuvem, ferramentas de notificação, frameworks de teste, análise de código e muito mais.
  • Explore: actions/checkout, actions/setup-node, docker/build-push-action, actions/cache, actions/upload-artifact, e muitas outras.

Dicas Rápidas

  • Coloque os arquivos de workflow em .github/workflows.
  • Use workflow_dispatch com inputs para execuções manuais e parametrizadas.
  • Use a ação cache para acelerar a instalação de dependências.
  • Use a matriz de jobs para testar várias versões de OS/runtime.
  • Use segredos para dados sensíveis, referenciados como ${{ secrets.SECRET_NAME }}.

Este cheatsheet abrange os fundamentos do uso, configuração e extensão de GitHub Actions para automação, CI/CD e muito mais. Para mais detalhes e atualizações, sempre consulte a documentação oficial do GitHub e os repositórios das ações.

Ações de GitHub Comuns

Aqui está uma lista prática de ações de GitHub frequentemente usadas que ajudam a automatizar CI/CD, testes, construção, implantação e tarefas de fluxo de trabalho:

Ações Oficiais Principais

Ação Propósito Parâmetros Chave
actions/checkout Verifica o código do repositório ref, submodules
actions/setup-node Configura o ambiente Node.js node-version, cache
actions/setup-python Configura o ambiente Python python-version
actions/setup-java Configura o JDK Java distribution, java-version
actions/cache Cacha dependências e saídas de build path, key, restore-keys
actions/upload-artifact Carrega artefatos de build name, path
actions/download-artifact Baixa artefatos de workflow name, path
actions/github-script Executa JavaScript usando o contexto e API do GitHub script
actions/create-release Cria uma liberação do GitHub tag_name, release_name
actions/upload-release-asset Carrega ativos para uma liberação upload_url, asset_path
actions/labeler Aplica automaticamente rótulos a issues/PRs repo-token, configuration-path

Ações Comunitárias e de Terceiros Populares

Ação Propósito
docker/build-push-action Constrói e empurra imagens Docker
actions/setup-go Configura o ambiente Go
super-linter/super-linter Lint automático universal do código
trufflesecurity/trufflehog Escaneia segredos e credenciais
peaceiris/actions-gh-pages Implantar sites estáticos no GitHub Pages
JamesIves/github-pages-deploy-action Implantar projetos no GitHub Pages
peter-evans/create-pull-request Cria pull requests automaticamente
softprops/action-gh-release Cria e carrega liberações do GitHub
ad-m/github-push-action Empurra alterações de volta para o repositório GitHub
actions/setup-dotnet Configura o SDK .NET
azure/login Autentica no Azure
google-github-actions/auth Autentica no Google Cloud

Ações de Teste, QA e Relatório

Ação Propósito
actions/setup-ruby Configura o ambiente Ruby
codecov/codecov-action Carrega relatórios de cobertura de código para Codecov
coverallsapp/github-action Carrega resultados de cobertura para Coveralls
dorny/test-reporter Anexa resultados de testes aos checks do GitHub
stefanzweifel/git-auto-commit-action Auto-commite e empurra alterações de arquivos

Ações de Implantação e Notificação

Ação Propósito
appleboy/scp-action Carrega arquivos usando SCP
SamKirkland/FTP-Deploy-Action Implantar arquivos através de FTP/FTPS
cypress-io/github-action Executar testes end-to-end do Cypress
slackapi/slack-github-action Enviar mensagens para o Slack
dawidd6/action-send-mail Enviar e-mails durante as execuções do workflow

Utilitários e Gestão de Fluxo de Trabalho

Ação Propósito
peter-evans/repository-dispatch Dispara workflows de repositórios externos
fregante/setup-git-user Define credenciais de usuário Git para commits
andymckay/labeler Rótula issues e PRs com base em caminhos
actions/configure-pages Configura a publicação no GitHub Pages
EndBug/add-and-commit Adiciona e commite arquivos dentro de um workflow
dangoslen/changelog-enforcer Verifica se um changelog foi atualizado para PRs

Como Encontrar Mais

Há muitas ações do GitHub que permitem a automação de fluxo de trabalho, como testes automatizados, implantação em produção, notificações e integrações com outros serviços. O GitHub Marketplace lista milhares de ações em categorias como testes, segurança, implantação, notificações, qualidade do código e integrações. Listas curadas, como “Awesome Actions”, também são ótimas para inspiração e descoberta.