Blog

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

@apidog

@apidog

2 março 2026

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

Apidog para empresas

Implantação local

SSO & RBAC

Conforme SOC 2

Explorar Apidog Enterprise

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.

💡
Quer uma ótima ferramenta de Teste de API que gera documentação de API bonita?

Quer uma plataforma integrada, All-in-One para sua equipe de desenvolvedores trabalharem juntos com máxima produtividade?

Apidog atende a todas as suas demandas e substitui o Postman a um preço muito mais acessível!
button

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:
  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:
  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.

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]:

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.

act -s MY_SECRET_TOKEN -s ANOTHER_SECRET

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

export SECRET_MY_SECRET_TOKEN="seu_valor"
act

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

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>.

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:

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:

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.

💡
Quer uma ótima ferramenta de Teste de API que gera documentação de API bonita?

Quer uma plataforma integrada, All-in-One para sua equipe de desenvolvedores trabalharem juntos com máxima produtividade?

Apidog atende a todas as suas demandas e substitui o Postman a um preço muito mais acessível!
button

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs

Cadastre-se gratuitamenteBaixar