How to Install and Use act in Linux to Run GitHub Actions Locally

Continuous Integration (CI) pipelines using GitHub Actions are central to modern DevOps workflows. However, testing and iterating on GitHub Actions workflows by committing changes, pushing commits to remote branches, and waiting for remote runners to execute is tedious and wastes GitHub Action minutes. act is an open-source command-line tool written in Go that allows developers to run their GitHub Actions workflows locally inside Docker containers on Linux.

By parsing .github/workflows/ files and matching runner environments locally, act provides instantaneous feedback on pipeline syntax, script failures, secrets handling, and matrix builds before code is committed to Git.

Prerequisites and Docker Verification

Because act replicates the GitHub Actions runner environment inside containerised images, Docker must be installed and running on your Linux system:

1. Verify that the Docker daemon is active:

   docker --version
   sudo systemctl status docker

2. Ensure your standard user account can execute Docker commands without root privileges:

   sudo usermod -aG docker $USER

   If you recently added your user to the group, log out and back in to apply group permissions.

Installing act on Linux

act provides multiple installation channels across Linux distributions.

Method 1: Direct Binary Installation (Recommended)

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

This script detects your CPU architecture and installs the act binary directly into /usr/local/bin/.

Method 2: Using Homebrew or Go

# Via Linuxbrew
brew install act

# Via Go
go install github.com/nektos/act@latest

Method 3: Arch Linux (AUR)

yay -S act

Confirm the installation by checking the version:

act --version

Configuring Default Runner Image Sizes

When running act for the first time, the tool prompts you to select a default Docker runner image size based on your hardware storage capacity:

• Micro (approx. < 200 MB): Minimal Node.js image suitable for simple linting scripts.
• Medium (approx. 500 MB): Balanced image containing common build tools, Git, and package managers (recommended for general development).
• Large (approx. 17 GB): Full replica of the official GitHub Ubuntu runner containing complete language runtimes, Docker-in-Docker, and CLI utilities.

You can adjust this choice at any time by editing ~/.actrc.

Running Workflows and Inspecting Jobs Locally

Navigate to the root directory of any repository containing a .github/workflows/ directory:

List Available Jobs

To inspect all configured workflows and jobs without executing them:

act -l

act outputs a structured table detailing the Stage, Job ID, Job name, and Workflow file.

Triggering the Default "push" Event

To run all jobs configured to trigger on Git push events:

act

act spins up the designated Docker container, clones your local repository into the container workspace, executes steps sequentially, and outputs colour-coded terminal logs.

Triggering Specific Events and Jobs

To simulate a pull request event:

act pull_request

To run only a single targeted job rather than the entire pipeline matrix:

act -j test

Passing Secrets and Environment Variables

Real-world CI workflows frequently depend on API tokens, database credentials, and deployment keys:

Passing Secrets via the Command Line

act -s GITHUB_TOKEN=ghp_example123 -s API_KEY=secret_key_456

Using a Secrets File

To avoid passing sensitive credentials interactively, create a .secrets file in your project directory (ensure this file is listed in .gitignore):

NPM_TOKEN=npm_abc123
DATABASE_URL=postgres://user:pass@localhost:5432/db

Instruct act to ingest the secrets file during execution:

act --secret-file .secrets

Dry-Running and Debugging Workflows

To validate workflow YAML syntax and step execution order without executing bash commands inside containers, pass the dry-run flag:

act -n

If a job fails unexpectedly, you can keep the container alive or run act in verbose mode for troubleshooting:

act -v