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.
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.
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.
Links Úteis
- https://docs.github.com/actions
- https://github.com/marketplace
- https://docs.github.com/en/actions/get-started/quickstart
- https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions
- GIT Cheatsheet
- Gitea - instalando e testando
- Backup e restauração do servidor Gitea
- Usando Gitea Actions para implantar um site Hugo no AWS S3
- Gitflow: Passos, Alternativas, Vantagens e Desvantagens
- DevOps com GitOps - Argo CD, Flux, Jenkins X, Weave GitOps e outros