act

act is a tool that allows you to run GitHub Actions locally. It provides fast feedback by letting you test .github/workflows/ files without committing and pushing to GitHub, and it can serve as a local task runner to replace tools like make using your existing GitHub Actions definitions.

How it works:

1. Parsing: act reads your GitHub Actions from the .github/workflows/ directory.
2. Dependency Resolution: It determines the set of actions required and the execution path based on defined dependencies.
3. Image Preparation: It uses the Docker API to pull or build the necessary images defined in your workflow files.
4. Execution: It uses the Docker API to run containers for each action. The environment variables and filesystem are configured to match the GitHub-hosted runner environment.

Instead of passing long lists of flags every time, you can define your configuration in .actrc files. act searches for these files in the following order:

1. The XDG configuration directory (e.g., ~/.config/act/actrc).
2. The user's HOME directory (~/.actrc).
3. The current working directory (./.actrc).

The act CLI allows you to run GitHub Actions workflows on your local machine using Docker. By default, if no event name is provided, act will attempt to run workflows triggered by the push event. If your workflows only handle a single specific event, act will use that as the default instead.

# Run the default event (usually push)
act

# Run a specific event
act pull_request

# Run a specific job
act -j build

If you need to build act manually, ensure you have Go tools 1.20 or higher installed. Follow these steps:

1. Clone the repository.
2. Run unit tests to verify the build.
3. Build and install the binary.

# Install Go tools 1.20+
# Clone this repo
git clone git@github.com:nektos/act.git

# Run unit tests
make test

# Build and install
make install

By default, act attempts to fetch version-specific notices from the act API. You can disable this behavior by setting the ACT_DISABLE_VERSION_CHECK environment variable to 1. This prevents the tool from making network requests to https://api.nektosact.com/notices to check for updates or announcements.

export ACT_DISABLE_VERSION_CHECK=1

When providing secrets to act, they are processed as a case-insensitive map of key-value pairs. The tool resolves secret values using the following precedence:

1. Explicit Key-Value Pairs: If a secret is provided in the format KEY=VALUE, that value is used.
2. Environment Variables: If a secret is provided as just a KEY (without an =), act looks for an existing environment variable with that name. If found and non-empty, it uses that value.
3. Interactive Input: If the key is not provided with a value and no matching environment variable exists, act will prompt the user to enter the password/value manually via the terminal (using term.ReadPassword for secure input).

Note: All secret keys are converted to uppercase internally, making them case-insensitive.

For environments that closely mimic GitHub Actions runners, you can use images based on actions/virtual-environments.

Nektos Environments: Note: nektos/act-environments-ubuntu images were last updated in February 2020. It is recommended to manually update the image after docker pull if you choose to use them.

• nektos/act-environments-ubuntu:18.04
• nektos/act-environments-ubuntu:18.04-lite
• nektos/act-environments-ubuntu:18.04-full

Catthehacker Virtual Environment Forks:

• catthehacker/ubuntu:full-latest
• catthehacker/ubuntu:full-20.04
• catthehacker/ubuntu:full-18.04

Use act to inspect your workflow configurations without executing them.

• -l, --list: List all available workflows/jobs.
• -g, --graph: Draw a graph of the workflows.
• --list-options: Print a JSON structure of compatible CLI options.

act --list
act --graph

You can use images based on buildpack-deps for your act runs.

Important Considerations:

• Node images: These are based on the Debian root filesystem. While similar to Ubuntu, there may be differences.
• Slim images: node -slim images do not have python installed. If your actions or software depend on Python, you must specify a non-slim image manually.

Available Images:

• node:16-bullseye
• node:16-bullseye-slim (No Python)
• node:16-buster
• node:16-buster-slim (No Python)

Ubuntu-based images (catthehacker): These use an Ubuntu root filesystem:

• catthehacker/ubuntu:act-latest
• catthehacker/ubuntu:act-22.04
• catthehacker/ubuntu:act-20.04
• catthehacker/ubuntu:act-18.04