Como usar act para rodar GitHub Actions localmente antes de push

1. Introdução ao act: Por que testar workflows localmente?

O ciclo tradicional de desenvolvimento com GitHub Actions é doloroso: você faz um push, espera minutos para o workflow rodar na nuvem, descobre um erro bobo de sintaxe ou variável ausente, corrige e faz outro push. Esse loop de "push, esperar, corrigir, push de novo" pode consumir horas preciosas e poluir o histórico do repositório com commits de correção.

act resolve esse problema ao emular o runner do GitHub Actions diretamente na sua máquina. Ele interpreta os arquivos YAML da pasta .github/workflows/ e executa cada step dentro de containers Docker, replicando fielmente o ambiente de CI/CD da nuvem. Os benefícios são imediatos:

  • Economia de tempo: testes que levariam minutos no GitHub rodam em segundos localmente
  • Debugging rápido: logs detalhados e controle total sobre a execução
  • Validação offline: desenvolva workflows mesmo sem conexão com internet
  • Redução de commits desnecessários: apenas workflows validados vão para o repositório

2. Pré-requisitos e instalação do act

Antes de instalar o act, verifique os pré-requisitos:

  • Docker: instalado e em execução (verifique com docker --version)
  • Sistema operacional: Linux, macOS ou Windows 10/11 com WSL2

Instalação no Linux/macOS (via script curl)

curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

Instalação no Windows (via Chocolatey)

choco install act-cli

Verificando a instalação

act --version
act --help

Se tudo funcionar, você verá a versão instalada e a lista de comandos disponíveis.

3. Configurando o ambiente para execução local

Para que o act funcione corretamente, seu repositório precisa ter a estrutura padrão do GitHub Actions:

meu-repositorio/
├── .github/
│   └── workflows/
│       ├── ci.yml
│       ├── deploy.yml
│       └── test.yml
├── src/
├── .env
└── .secrets

Mapeamento de variáveis de ambiente

Crie um arquivo .env na raiz do projeto:

NODE_ENV=development
API_URL=http://localhost:3000
DEBUG=true

Execute o act com o arquivo de ambiente:

act --env-file .env

Gerenciamento de secrets

Para simular secrets sem expô-los no código, crie um arquivo .secrets (adicione ao .gitignore):

MY_SECRET_KEY=chave-local-de-teste
DB_PASSWORD=senha-local

Execute com:

act --secret-file .secrets

4. Executando workflows com act: comandos essenciais

Comando básico e listagem

# Executa todos os workflows
act

# Lista todos os jobs disponíveis
act -l

Executando eventos específicos

# Simula um push
act push

# Simula um pull_request
act pull_request

# Simula um schedule (cron)
act schedule

# Simula workflow_dispatch
act workflow_dispatch

Filtrando jobs e alterando imagem base

# Executa apenas o job "test" do workflow
act -j test

# Usa uma imagem específica para o runner
act -P ubuntu-latest=catthehacker/ubuntu:act-latest

5. Debugging e resolução de problemas comuns

Ativando logs detalhados

# Modo verbose
act --verbose

# Modo debug (ainda mais detalhado)
act --debug

Problemas frequentes e soluções

Problema: "Error: docker: command not found"
Solução: Verifique se o Docker está instalado e no PATH

which docker
sudo systemctl start docker  # Linux

Problema: "Job 'build' not found"
Solução: Liste os jobs disponíveis com act -l e use o nome exato

Problema: Variáveis de ambiente aparecendo como vazias
Solução: Certifique-se de que o arquivo .env está no diretório correto

Testando steps isoladamente

# Executa apenas um job específico
act --job build

# Executa um workflow específico (pelo nome do arquivo)
act -W .github/workflows/test.yml

6. Integração com CI/CD real e boas práticas

Sincronizando alterações locais

Após validar o workflow localmente, faça o push com confiança:

git add .
git commit -m "feat: adiciona workflow de CI validado localmente"
git push origin main

Workflows condicionais

Evite execução duplicada adicionando condições ao workflow:

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

Boas práticas

  • Versionamento do arquivo .actrc: crie um arquivo de configuração na raiz
# .actrc
--env-file .env
--secret-file .secrets
-P ubuntu-latest=catthehacker/ubuntu:act-latest
  • Cache de dependências: use actions/cache nos workflows para acelerar execuções
  • Teste em múltiplas imagens: valide o comportamento em diferentes versões do Ubuntu

7. Casos de uso avançados e extensões

Executando com serviços Docker Compose

Para workflows que dependem de banco de dados ou Redis:

act --bind

Isso permite que containers do Docker Compose se comuniquem com o runner.

Simulando eventos complexos

# Evento issue_comment
act issue_comment -e event.json

Onde event.json contém:

{
  "action": "created",
  "issue": {"number": 1},
  "comment": {"body": "/deploy"}
}

Integração com pré-commit

Adicione ao arquivo .pre-commit-config.yaml:

- repo: local
  hooks:
    - id: act-check
      name: Validate GitHub Actions
      entry: act --dry-run
      language: system
      files: \.github/workflows/.*\.yml$

8. Conclusão e próximos passos

O fluxo ideal de desenvolvimento com GitHub Actions agora é:

  1. Escreva o workflow YAML na pasta .github/workflows/
  2. Teste localmente com act push ou act pull_request
  3. Corrija erros instantaneamente com logs detalhados
  4. Faça push apenas quando o workflow estiver 100% funcional

Com act, você elimina o ciclo frustrante de tentativa e erro na nuvem, ganha produtividade e mantém o histórico do repositório limpo.

Para expandir seu conhecimento:
- Explore testes com matrizes de versões (Node 16, 18, 20)
- Configure ambientes multiplataforma (Linux, macOS, Windows)
- Estude a migração para self-hosted runners para cenários avançados

Referências