Como Executar Suas Ações do GitHub Localmente com Act

A GitHub Actions revolucionou a forma como os desenvolvedores automatizam fluxos de trabalho dentro de seus repositórios. Desde pipelines de integração contínua e entrega contínua (CI/CD) até a automação de rotulagem de problemas e geração de notas de lançamento, Actions oferece uma maneira poderosa e integrada de gerenciar o ciclo de vida do desenvolvimento de software diretamente no GitHub.

No entanto, desenvolver e testar esses fluxos de trabalho pode parecer, às vezes, complicado. O ciclo tradicional envolve:

1. Fazer alterações em seus arquivos de fluxo de trabalho (normalmente localizados em .github/workflows/).
2. Comitar essas alterações.
3. Enviar para seu repositório do GitHub.
4. Aguardar os runners do GitHub pegarem o trabalho e executá-lo.
5. Analisar os logs no site do GitHub para ver se suas alterações funcionaram ou se introduziram erros.

Esse processo, especialmente a parte de espera e a mudança de contexto entre seu editor local e a IU do GitHub, pode desacelerar significativamente o desenvolvimento, especialmente ao iterar em fluxos de trabalho complexos ou depurar problemas difíceis. E se você pudesse testar suas Actions antes de enviá-las?

É exatamente aqui que entra o act. Como seu slogan sugere, "Pense globalmente, act localmente". O act é uma ferramenta de linha de comando de código aberto projetada para executar seus fluxos de trabalho do GitHub Actions localmente usando contêineres Docker. Ele simula o ambiente fornecido pelo GitHub Actions, permitindo que você teste e itere rapidamente em seus fluxos de trabalho sem a necessidade de comitar e enviar cada pequena mudança.

Por que executar o GitHub Actions localmente com act?

Os benefícios de incorporar o act ao seu fluxo de trabalho de desenvolvimento são substanciais:

1. Feedback Rápido: Esta é a principal vantagem. Em vez do ciclo de comitar-enviar-esperar-debugar, você pode executar seu fluxo de trabalho imediatamente após fazer uma alteração localmente. Obtenha feedback em segundos ou minutos, e não em minutos ou dezenas de minutos. Isso acelera drasticamente o processo de desenvolvimento e depuração dos seus arquivos .github/workflows/.
2. Executores de Tarefa Local: Muitos projetos usam ferramentas como make, npm scripts ou scripts de shell personalizados para definir tarefas comuns de desenvolvimento (compilação, teste, linting, etc.). O act permite consolidar essas tarefas. Você pode definir seus processos de compilação, teste e outros como jobs do GitHub Actions, e então usar o act para executar esses mesmos jobs localmente para fins de desenvolvimento. Isso reduz a duplicação e garante consistência entre seu ambiente de desenvolvimento local e seu pipeline de CI/CD. Você define as tarefas uma vez em seus arquivos de fluxo de trabalho, e elas são executadas de forma idêntica (ou muito semelhante) em todos os lugares.
3. Desenvolvimento Offline: Teste a sintaxe e a lógica básica do fluxo de trabalho mesmo sem uma conexão de internet constante (embora downloads iniciais de imagens e certas ações possam exigir conectividade).
4. Economia de Custos: Embora o GitHub forneça um plano gratuito generoso para repositórios públicos e preços razoáveis para privados, executar fluxos de trabalho complexos ou longos repetidamente durante o desenvolvimento pode consumir minutos dos runners. Testar localmente evita esse uso.
5. Poder de Depuração: Depurar Actions que falharam no GitHub geralmente envolve adicionar log adicional, enviar e esperar. Com o act, você pode inspecionar o ambiente local, montar volumes e potencialmente usar técnicas de depuração mais avançadas dentro dos contêineres Docker que ele cria.

Como o act funciona?

Entender o mecanismo por trás do act ajuda a utilizá-lo de forma eficaz e a solucionar problemas potenciais. Aqui está um resumo de seu funcionamento:

1. Parsing do Fluxo de Trabalho: Quando você executa o comando act no diretório raiz de seu repositório, ele escaneia o diretório .github/workflows/ em busca de seus arquivos YAML de fluxo de trabalho.
2. Simulação de Trigger de Evento: Por padrão, o act simula um evento push, mas você pode especificar outros eventos, como pull_request, workflow_dispatch, etc. Ele determina quais fluxos de trabalho e jobs devem ser executados com base no evento especificado e nos triggers on: definidos em seus arquivos de fluxo de trabalho.
3. Análise de Dependências: O act analisa as dependências entre jobs dentro de um fluxo de trabalho (usando a palavra-chave needs:) para determinar a ordem correta de execução.
4. Gerenciamento de Imagens Docker: Para cada job, o act identifica o ambiente runner especificado (por exemplo, runs-on: ubuntu-latest). Em seguida, mapeia isso para uma imagem Docker específica. O act usa a API Docker para:

• Puxar Imagens: Baixar as imagens dos runners necessárias e quaisquer imagens Docker usadas em ações de contêiner (uses: docker://...). Por padrão, ele baixa as imagens em cada execução, a menos que configurado de outra forma.
• Construir Imagens (se necessário): Se uma ação aponta para um Dockerfile local (uses: ./path/to/action), o act pode construir a imagem Docker localmente.

1. Execução de Contêiner: O act usa a API Docker para criar e executar contêineres para cada passo dentro de um job. Ele configura esses contêineres para imitar o ambiente do GitHub Actions o mais próximo possível:

• Variáveis de Ambiente: Variáveis de ambiente padrão do GitHub Actions (como GITHUB_SHA, GITHUB_REF, GITHUB_REPOSITORY, CI, etc.) são injetadas.
• Sistema de Arquivos: O código do repositório está montado no diretório de espaço de trabalho do contêiner (/github/workspace). Arquivos gerados pelos passos são mantidos dentro do contêiner para passos subsequentes.
• Rede: Os contêineres geralmente são executados em uma rede de ponte Docker, permitindo comunicação se necessário (embora as especificidades da rede possam diferir do ambiente do GitHub).

1. Transmissão de Logs: O act transmite os logs dos contêineres em execução diretamente para o seu terminal, fornecendo feedback em tempo real sobre o progresso da execução e quaisquer erros.

Basicamente, o act orchestra contêineres Docker locais para replicar o fluxo de execução e o ambiente de seus fluxos de trabalho do GitHub Actions.

Pré-requisitos: Instalação do Docker

A principal dependência do act é o Docker. O act aproveita o motor Docker para criar os ambientes isolados necessários para executar suas etapas de fluxo de trabalho. Antes de instalar o act, você deve ter uma instalação do Docker funcionando em seu sistema.

• Instalar o Docker: Siga as instruções oficiais para seu sistema operacional:
• macOS: Docker Desktop para Mac
• Windows: Docker Desktop para Windows (requer WSL 2 ou Hyper-V)
• Linux: Siga as instruções específicas para sua distribuição (por exemplo, Ubuntu, Fedora, Debian, etc.). Certifique-se de adicionar seu usuário ao grupo docker para executar comandos do Docker sem sudo.
• Verificar o Docker: Após a instalação, abra seu terminal e execute docker run hello-world. Este comando baixa uma pequena imagem de teste e a executa em um contêiner. Se ele for executado com sucesso, sua configuração do Docker está pronta.

Instalando o act

Uma vez que o Docker esteja em execução, você pode instalar o act. Existem várias maneiras de fazer isso, dependendo do seu sistema operacional e preferências.

1. Homebrew (macOS e Linux)

Se você usar o gerenciador de pacotes Homebrew, a instalação é simples:

brew install act

Isso instala a versão estável mais recente. Se você quiser a versão de desenvolvimento mais recente (que pode exigir um compilador), pode usar:

brew install act --HEAD

2. Extensão do GitHub CLI (macOS, Windows, Linux)

Se você já usa o GitHub CLI (gh), pode instalar o act como uma extensão:

gh extension install nektos/gh-act

Após a instalação, você invoca o act através do comando gh:

gh act          # Em vez de apenas 'act'
gh act -l
gh act pull_request

3. Chocolatey (Windows)

Para usuários do gerenciador de pacotes Chocolatey no Windows:

choco install act-cli

(Nota: Algumas fontes podem listar act em vez de act-cli. Verifique o nome do pacote mais recente no repositório oficial do Chocolatey se você encontrar problemas.)

4. Scoop (Windows)

Para usuários do gerenciador de pacotes Scoop no Windows:

scoop install act

5. WinGet (Windows)

Para usuários do Windows Package Manager (winget):

winget install nektos.act

6. Instalador de Script para Linux

Um script de conveniência está disponível para distribuições Linux sem acesso fácil através de gerenciadores de pacotes:

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

(Nota: Sempre tenha cautela ao canalizar scripts diretamente para sudo. Revise o conteúdo do script primeiro, se você tiver preocupações de segurança.)

7. Outros Métodos (Arch, COPR, MacPorts, Nix)

Instruções de instalação para outros gerenciadores de pacotes como pacman (Arch), COPR (Fedora), MacPorts e Nix estão disponíveis na documentação oficial do act:

Verificação:

Após a instalação, abra uma nova janela de terminal e execute:

act --version
# ou se estiver usando a extensão gh:
gh act --version

Isso deve imprimir a versão instalada do act, confirmando que a instalação foi bem-sucedida.

Configuração Inicial: Imagens de Runner

Na primeira vez que você executar o act dentro de um diretório de projeto, ele pode solicitar que você escolha um tamanho de imagem de runner padrão. O GitHub Actions oferece runners com recursos variados e software pré-instalado. O act tenta imitar isso usando diferentes imagens Docker base.

Você normalmente será apresentado a uma escolha como esta:

? Por favor, escolha a imagem padrão que você deseja usar com o act:

  - Micro: Imagem mínima com suporte a nodejs (~200MB) docker.io/node:16-buster-slim
  - Medium: Imagem Act com ferramentas básicas (~500MB) ghcr.io/catthehacker/ubuntu:act-latest
  - Large: Imagem do runner do GitHub Actions (~17GB) ghcr.io/catthehacker/ubuntu:full-latest

Imagem padrão? [Medium]:

• Micro: Baseado em imagens oficiais do Node.js slim (como node:16-buster-slim ou node:16-bullseye-slim). Muito pequeno e rápido de baixar, mas contém apenas Node.js e bibliotecas de sistema mínimas. Adequado se suas ações precisam apenas do Node.js ou instalam todas as suas dependências sozinhas.
• Medium: Fornecido pelo usuário catthehacker (por exemplo, catthehacker/ubuntu:act-latest, catthehacker/ubuntu:act-22.04). Essas imagens incluem mais ferramentas comuns encontradas nos runners do GitHub, mas ainda são relativamente leves (cerca de 500MB). Este é frequentemente o padrão recomendado, pois equilibra recursos e tamanho.
• Large: Também de catthehacker (por exemplo, catthehacker/ubuntu:full-latest, catthehacker/ubuntu:full-22.04). Essas são criadas a partir de dumps de sistema de arquivos dos runners hospedados no GitHub e contêm quase todos os softwares pré-instalados. Elas oferecem a mais alta compatibilidade, mas são muito grandes (geralmente >17GB), levando a longos tempos de download iniciais e uso significativo de espaço em disco.

Recomendação: Comece com a imagem Medium. Ela fornece um bom equilíbrio e funciona para muitos casos de uso comuns. Se você encontrar problemas devido à falta de software, você pode instalar o software dentro de seus passos de fluxo de trabalho ou mudar para usar a imagem Large para aquele runner específico (mais sobre isso depois).

O act salva sua escolha em um arquivo de configuração (~/.actrc). Você pode alterar o padrão mais tarde editando este arquivo ou reexecutando o act em um diretório onde precisa configurar.

Uso Principal do act: Executando Seus Fluxos de Trabalho

Uma vez instalado e configurado, usar o act é relativamente simples. Navegue até o diretório raiz do seu projeto (aquele contendo a pasta .github) em seu terminal.

1. Executar Evento Padrão (push)

O comando mais simples executa os fluxos de trabalho acionados pelo evento padrão push:

act
# ou
gh act

O act irá analisar seus fluxos de trabalho, identificar jobs acionados on: push, puxar as imagens Docker necessárias (se não já estiverem em cache) e executar os jobs.

2. Listar Fluxos de Trabalho e Jobs Disponíveis

Para ver quais fluxos de trabalho e jobs act reconhece e executaria para o evento padrão:

act -l
# ou
gh act -l

Isso gera uma lista como:

Stage  Job ID        Nome do Job   Nome do Fluxo    Arquivo do Fluxo  Eventos
0      build         Build         CI Pipeline     ci.yaml          push
1      test          Test          CI Pipeline     ci.yaml          push
1      lint          Lint          Qualidade do Código   codeql.yaml    push,pull_request

3. Executar um Job Específico

Se você quiser apenas testar um único job de um fluxo de trabalho, use a flag -j seguida do ID do job (da saída do act -l):

act -j build
# ou
gh act -j build

4. Acionar um Evento Específico

Os fluxos de trabalho muitas vezes são acionados por eventos além do push. Você pode simular esses eventos fornecendo o nome do evento como um argumento para o act:

# Simular um evento de pull request
act pull_request

# Simular um evento workflow_dispatch (acionamento manual)
act workflow_dispatch

# Simular um evento de agendamento
act schedule

# Simular um evento de release
act release -e event.json # Fornecer detalhes do payload do evento, se necessário

O act só executará fluxos de trabalho e jobs configurados para rodar on: o evento especificado.

5. Passando Entradas para workflow_dispatch

Fluxos de trabalho acionados por workflow_dispatch podem aceitar entradas. Você pode fornecer essas usando a flag --input ou -i:

# Assumindo que seu fluxo de trabalho tem uma entrada chamada 'environment'
act workflow_dispatch --input environment=staging

6. Manipulando Segredos

Os fluxos de trabalho do GitHub Actions frequentemente dependem de segredos (como chaves de API ou tokens). O act não acessa automaticamente seus segredos do GitHub. Você precisa fornecê-los localmente.

• Prompt Interativo: Use a flag -s. O act pedirá que você insira o valor para cada segredo definido em seu fluxo de trabalho:

act -s MY_SECRET_TOKEN -s ANOTHER_SECRET

Alternativamente, apenas act -s pedirá por todos os segredos.

• Variáveis de Ambiente: Segredos são frequentemente passados como variáveis de ambiente prefixadas com SECRET_. Você pode defini-los em seu shell antes de executar o act:

export SECRET_MY_SECRET_TOKEN="seu_valor"
act

• Arquivo de Segredos: Crie um arquivo (por exemplo, .secrets) com pares KEY=VALUE:

MY_SECRET_TOKEN=seu_valor
ANOTHER_SECRET=outro_valor

Depois, execute o act com a flag --secret-file:

act --secret-file .secrets

(Certifique-se de que este arquivo seja adicionado ao seu .gitignore para evitar commitar segredos!)

7. Manipulando Variáveis e Variáveis de Ambiente

• Variáveis de Fluxo de Trabalho: Você pode fornecer valores para variáveis definidas no nível do fluxo de trabalho (vars: contexto, embora o suporte completo do contexto vars no act possa ser limitado) usando a flag --var ou um --var-file, semelhante a segredos.
• Variáveis de Ambiente: Para definir variáveis de ambiente personalizadas para a execução do fluxo de trabalho, use a flag --env ou um --env-file.

act --env NODE_ENV=development --env CUSTOM_FLAG=true
act --env-file .env_vars

Gerenciando Ambientes e Imagens do Runner

Embora as imagens de runner padrão (Micro, Medium, Large) cubram muitos cenários, você frequentemente precisa de mais controle.

1. Limitações das Imagens Padrão

Lembre-se de que as imagens de runner padrão do act (especialmente Micro e Medium) não são idênticas aos ambientes fornecidos pelo GitHub. Elas podem faltar ferramentas específicas, bibliotecas ou serviços de sistema (como systemd) que seu fluxo de trabalho espera. As imagens Large oferecem maior fidelidade, mas vêm com a desvantagem significativa de tamanho.

2. Especificando Imagens Alternativas com -P

Se um job requer um ambiente específico ou conjunto de ferramentas que não estão presentes na imagem padrão, você pode dizer ao act para usar uma imagem Docker diferente para uma plataforma específica usando a flag -P (plataforma).

O formato é -P <plataforma>=<imagem-docker>.

• <plataforma>: O rótulo utilizado na diretiva runs-on: do seu fluxo de trabalho (por exemplo, ubuntu-latest, ubuntu-22.04, ubuntu-20.04).
• <imagem-docker>: O nome completo da imagem Docker a ser utilizada (por exemplo, node:18, python:3.10-slim, mcr.microsoft.com/devcontainers/base:ubuntu).

Exemplos:

# Use a imagem Large especificamente para jobs executando em ubuntu-22.04
act -P ubuntu-22.04=ghcr.io/catthehacker/ubuntu:full-22.04

# Use uma versão específica do Node.js para jobs ubuntu-latest
act -P ubuntu-latest=node:18-bullseye

# Use uma imagem mais completa de nektos/act-environments (muito grande!)
# AVISO: nektos/act-environments-ubuntu:18.04 é >18GB
act -P ubuntu-18.04=nektos/act-environments-ubuntu:18.04

# Especifique múltiplas plataformas se seu fluxo de trabalho as usar
act -P ubuntu-20.04=node:16-buster -P ubuntu-22.04=node:18-bullseye

3. Usando Imagens de Runner Locais (--pull=false)

Por padrão, o act tenta puxar a versão mais recente da imagem Docker especificada toda vez que é executado. Se você construiu uma imagem de runner personalizada localmente ou deseja garantir que está usando a versão exata que possui em cache, você pode desabilitar esse comportamento:

act --pull=false
# ou potencialmente usar modo offline
act --action-offline-mode

Isso informa ao act para usar a imagem localmente disponível, se presente, e apenas tentar puxar se estiver faltando.

4. Executando Nativamente no Host (-self-hosted)

Para fluxos de trabalho que têm como alvo macOS ou Windows (runs-on: macos-latest ou runs-on: windows-latest), se você estiver executando o act nesse mesmo sistema operacional host, você pode instruir o act não usar um contêiner Docker para o runner em si. Em vez disso, ele executará os passos diretamente na sua máquina host. Isso pode ser útil se a compatibilidade do Docker for um problema ou se você precisar de acesso direto aos recursos do host.

# Execute jobs macos-latest diretamente no seu host Mac
act -P macos-latest=-self-hosted

# Execute jobs windows-latest diretamente no seu host Windows
act -P windows-latest=-self-hosted

Atenção: Executar diretamente no host contorna o isolamento fornecido pelo Docker. Os passos do fluxo terão acesso ao seu sistema de arquivos e poderão modificar seu ambiente host. Use esta opção com cuidado. Passos dentro do job que usam explicitamente contêineres Docker (como contêineres de serviço ou ações de contêiner) ainda usarão o Docker.

Limitações e Considerações

Embora o act seja incrivelmente útil, é importante estar ciente de suas limitações:

• Não é uma Réplica Perfeita: O act simula o ambiente do GitHub Actions, mas não é idêntico. Existem diferenças em rede, serviços de sistema disponíveis (por exemplo, sem systemd em contêineres Docker de forma fácil), recursos de hardware específicos e o conjunto exato de ferramentas pré-instaladas (a menos que se utilizem as imagens de runner muito grandes). Alguns fluxos de trabalho, especialmente os complexos que interagem pesadamente com o sistema operacional subjacente ou com recursos específicos do GitHub, podem se comportar de maneira diferente no act em comparação com o GitHub.
• Diferenças de Contexto: Algumas partes do contexto github podem estar incompletas ou conter valores padrão/mock quando executadas localmente. O contexto secrets sempre precisa de entrada explícita. O suporte ao contexto vars também pode ter limitações em comparação com o ambiente do GitHub ao vivo.
• Concorrência: O act geralmente executa jobs sequencialmente com base em suas dependências needs. Ele não replica totalmente a capacidade do GitHub de executar jobs independentes simultaneamente usando estratégias de matriz em vários runners (embora o act suporte a execução de jobs de matriz, eles geralmente são executados sequencialmente localmente).
• Serviços Hospedados: Recursos como cache (actions/cache) podem funcionar de maneira diferente ou exigir configuração específica localmente em comparação com o serviço de cache integrado do GitHub. Contêineres de serviço definidos em fluxos de trabalho devem funcionar, já que o act usa o Docker para isso também.
• Disponibilidade de Plataforma: Você só pode executar jobs baseados em Linux dentro do Docker em qualquer host suportado pelo Docker (Mac, Windows, Linux). Para executar jobs macos-latest, você idealmente precisaria do act no macOS (ou usar a flag -self-hosted no macOS). Da mesma forma, jobs windows-latest normalmente exigem o act no Windows (ou -self-hosted no Windows). Embora o Docker possa executar contêineres do Windows no Windows, o foco principal do act e o suporte mais estável giram em torno de contêineres Linux.

Recomendação: Use o act para desenvolvimento rápido, verificação de sintaxe, teste básico de lógica e iteração em jobs ou passos individuais. Sempre realize a validação final executando seus fluxos de trabalho no próprio GitHub antes de mesclar alterações críticas, especialmente para pipelines de implantação. Consulte a documentação oficial do act para a matriz de suporte detalhada e problemas conhecidos.

Conclusão

Testar o GitHub Actions localmente é um grande impulsionador de produtividade, transformando o ciclo de depuração que pode ser lento e tedioso em um processo rápido e iterativo. A ferramenta de CLI act fornece uma maneira robusta e flexível de conseguir isso, aproveitando o Docker para simular o ambiente do runner do GitHub Actions em sua máquina local.

Ao integrar o act ao seu fluxo de trabalho, você ganha:

• Loops de feedback mais rápidos.
• Menor dependência de enviar para o GitHub para testes.
• A capacidade de usar suas definições de Actions como um executador de tarefas local.
• Capacidades de depuração aprimoradas.

Embora tenha limitações e não seja uma substituição perfeita 1:1 para o ambiente ao vivo do GitHub, o act cobre uma vasta gama de casos de uso e reduz significativamente a fricção envolvida no desenvolvimento de fluxos de trabalho confiáveis e eficazes do GitHub Actions. Instale-o, experimente executar seus fluxos de trabalho existentes localmente e experimente os benefícios de pensar globalmente enquanto age localmente.