Act Local GitHub Actions

act cheatsheet — run GitHub Actions locally with act -j jobname, use secrets, override runners. Debug CI pipelines without pushing to GitHub every time.

6 min read

What it is

Act is a tool that allows you to run your GitHub Actions locally on your machine, enabling faster iteration and debugging without needing to push to a repository.

Installation

Linux

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

Mac

brew install act

Windows (using PowerShell)

Invoke-WebRequest -Path "https://raw.githubusercontent.com/nektos/act/master/install.ps1" -OutFile "install.ps1"; .\install.ps1

Alternatively, use Scoop:

scoop install act

Core Concepts

Workflows: .github/workflows/*.yml files that define your CI/CD processes.
Events: Triggers that start a workflow (e.g., push, pull_request, schedule).
Jobs: A set of steps that run on the same runner.
Steps: Individual tasks within a job, which can be commands or actions.
Actions: Reusable units of code that can be executed in a workflow. These can be from the GitHub Marketplace, a public repository, or a private repository.
Runners: The environment where your jobs execute. Act simulates these locally.

Commands / Usage

Running Workflows

Run all workflows:
```
act
```
Runs all workflows defined in .github/workflows/ that are triggered by the default push event.
Run a specific workflow:
```
act -W my-workflow.yml
```
Runs only the workflow defined in my-workflow.yml.
Run a workflow by event:
```
act push
```
Runs all workflows triggered by the push event.
Run a workflow by event and name:
```
act --event pull_request --workflow CI
```
Runs the workflow named "CI" that is triggered by the pull_request event.
Run a specific job within a workflow:
```
act -j build
```
Runs only the job named "build" from any applicable workflow.
Run a specific job within a specific workflow:
```
act -W deploy.yml -j deploy-production
```
Runs the job named "deploy-production" from the deploy.yml workflow.

Simulating Events and Inputs

Simulate a push event with a specific branch:
```
act push -b main
```
Triggers workflows on a push event to the main branch.
Simulate a pull request event:
```
act pull_request -b feature/new-login -P origin/main:feature/new-login
```
Triggers workflows for a pull request from feature/new-login to main. The -P flag specifies the ref mapping.
Provide input to a workflow:
```
act --input MY_INPUT_VAR=my_value --input ANOTHER_VAR=another_value
```
Passes custom input variables to the workflow.

Use a JSON file for inputs:

act --input-file inputs.json

Where inputs.json contains:

{
  "MY_INPUT_VAR": "my_value",
  "ANOTHER_VAR": "another_value"
}

Environment and Secrets

Set environment variables:
```
act -e MY_ENV_VAR=my_env_value
```
Sets environment variables available to all jobs.

Use a JSON file for environment variables:

act --env-file env.json

Where env.json contains:

{
  "MY_ENV_VAR": "my_env_value",
  "ANOTHER_ENV": "another_env_value"
}

Add secrets from the command line:

act --secret MY_SECRET=my_secret_value --secret ANOTHER_SECRET=another_secret_value

Makes secrets available to the workflow.

Add secrets from a file:
```
act --secret-file secrets.txt
```
Where secrets.txt contains secrets, one per line, in the format KEY=VALUE.
```
MY_SECRET=my_secret_value
ANOTHER_SECRET=another_secret_value
```

Use a JSON file for secrets:

act --secret-file secrets.json

Where secrets.json contains:

{
  "MY_SECRET": "my_secret_value",
  "ANOTHER_SECRET": "another_secret_value"
}

Workflow and Action Management

List available workflows:
```
act -l
```
Shows all workflows found in the .github/workflows/ directory.
List available jobs:
```
act -j
```
Shows all jobs across all workflows.
List available events:
```
act -e
```
Shows all possible events that can trigger workflows.
Specify the working directory:
```
act --dir /path/to/repo
```
Runs act within a specified directory (useful if you’re not in the root of your repo).
Use a specific runner image:
```
act --container-architecture amd64
act --container-image ubuntu:20.04
```
Forces act to use a specific container architecture or image.
Disable color output:
```
act --no-color
```
Turns off colored output in the terminal.
Use local actions:
```
act --local-github-path /path/to/local/actions
```
Specifies a path to local action definitions.

Debugging and Verbosity

Enable verbose logging:
```
act -v
```
Increases the verbosity of act’s output.
View logs from a previous run:
```
act --log-level debug --rm --pull never
# After the run, find the container ID and use:
docker logs <container_id>
```
This is a bit more involved, but running with --rm and then inspecting the Docker logs is how you’d get detailed debugging information.
Disable Docker image pulling:
```
act --pull never
```
Prevents act from pulling Docker images, useful if you have them cached locally.
Re-use existing Docker containers:
```
act --container-reuse
```
Speeds up subsequent runs by reusing Docker containers.

Common Patterns

Simulate a specific commit push to main:
```
act push -b main --commit-ref HEAD
```
This is often the default behavior but explicitly states the intent.
Running a workflow that depends on specific environment variables and secrets:
```
act \
  -W my-deploy.yml \
  -j deploy-staging \
  --env-file ./.github/env_staging.conf \
  --secret-file ./.github/secrets_staging.conf
```
Where .github/env_staging.conf and .github/secrets_staging.conf contain the necessary configuration.
Testing a pull request from a fork:
```
act pull_request -b develop -P origin/develop:my-fork/feature-branch
```
Simulates a PR from my-fork/feature-branch into develop.
Running a scheduled workflow manually:
```
act schedule
```
Triggers any workflows with a schedule event.
Running a workflow with a specific tag/commit hash:
```
act --ref v1.2.3
```
Runs workflows as if the code was at tag v1.2.3.

Gotchas

Default Branch: If you don’t specify a branch with -b, act defaults to the repository’s default branch (usually main or master).
Secrets vs. Environment Variables: Secrets are intended for sensitive information and are typically accessed via secrets.<SECRET_NAME> in your workflow. Environment variables are for general configuration and accessed via env.<VAR_NAME> or $VAR_NAME. Act handles both.
GITHUB_TOKEN: Act automatically provides a GITHUB_TOKEN secret, which is usually x0b2v3n4j5m6l7k8p9o1i2u3y4t5r6e7w8q9. This token has limited permissions and is primarily for interacting with the GitHub API.
Action Dependencies: Act downloads actions from GitHub. If you’re using private actions, you might need to configure authentication or provide them locally.
Container Networking: By default, act containers run on a bridge network. If your workflow needs to access external services or be accessed by other local services, you might need to configure Docker networking.
pull_request_target Event: Simulating pull_request_target events locally is more complex as it involves running code from the base branch with the context of the head branch. Act’s simulation might not perfectly replicate all nuances of this event type.
Runner Images: Act relies on Docker. Ensure Docker is running and configured correctly. If you encounter issues, try specifying a different runner image (--container-image) or ensure your Docker setup is healthy.
Context Objects: While act tries to simulate the GitHub Actions context (e.g., github context, runner context), there might be subtle differences compared to a real GitHub Actions runner, especially for complex or newer features.