Introduction

"Think globally, act locally"

Run your GitHub Actions locally! Why would you want to do this? Two reasons:

Fast Feedback - Rather than having to commit/push every time you want to test out the changes you are making to your .github/workflows/ files (or for any changes to embedded GitHub actions), you can use act to run the actions locally. The environment variables and filesystem are all configured to match what GitHub provides.
Local Task Runner - I love make. However, I also hate repeating myself. With act, you can use the GitHub Actions defined in your .github/workflows/ to replace your Makefile!

How Does It Work?

When you run act it reads in your GitHub Actions from .github/workflows/ and determines the set of actions that need to be run. It uses the Docker API to either pull or build the necessary images, as defined in your workflow files and finally determines the execution path based on the dependencies that were defined. Once it has the execution path, it then uses the Docker API to run containers for each action based on the images prepared earlier. The environment variables and filesystem are all configured to match what GitHub provides.

Let's see it in action with a sample repo!

Demo

Installation

Necessary prerequisites for running `act`

act depends on docker (exactly Docker Engine API) to run workflows in containers. As long you don't require container isolation, you can run selected (e.g. windows or macOS) jobs directly on your System see Runners. In the latter case you don't need to have docker installed or running.

If you are using macOS, please be sure to follow the steps outlined in Docker Docs for how to install Docker Desktop for Mac.

If you are using Windows, please follow steps for installing Docker Desktop on Windows.

If you are using Linux, you will need to install Docker Engine.

To use act with remote Docker Engine API compatible host, see Custom container engine act is currently not supported with podman or other container backends (it might work, but it's not guaranteed). Please see #303 for updates.

Pre-built artifacts

Bash script

You can easily install a pre-built act executable on any system with bash via below commandline

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

⚠ Script can't install non-released versions ⚠

Manual download of prebuilt executable

Prebuilt executables for multiple platforms are available via latest release page. You can unpack and run them in terminal specifying full path or add them to one of the paths included in PATH environment variable.

Build from source

Requires Go toolchain 1.18+

git clone https://github.com/nektos/act.git
cd act/
make build
# OR
go build -ldflags "-X main.version=$(git describe --tags --dirty --always | sed -e 's/^v//')" -o dist/local/act main.go

Installation via software package manager

act is available in below package repositories

Arch (Linux)
Homebrew (Linux, macOS)
Chocolatey (Windows)
COPR (Linux)
GitHub CLI (Linux, macOS, Windows, FreeBSD)
Nix/NixOS (Linux, macOS)
MacPorts (macOS)
Scoop (Windows)
Winget (Windows)

Packaging status

Arch (Linux)

pacman -Syu act

Chocolatey (Windows)

choco install act-cli

COPR (Linux)

dnf copr enable goncalossilva/act
dnf install act-cli

Installation as GitHub CLI extension

Act can be installed as a GitHub CLI extension:

gh extension install https://github.com/nektos/gh-act

Homebrew (Linux/macOS)

brew install act

or if you want to install version based on latest commit, you can run below (it requires compiler to be installed but Homebrew will suggest you how to install it, if you don't have it):

brew install act --HEAD

MacPorts (macOS)

sudo port install act

Nix (Linux/macOS)

Nix recipe

Global install:

nix-env -iA nixpkgs.act

or through nix-shell:

nix-shell -p act

Using the latest Nix command, you can run directly :

nix run nixpkgs#act

Scoop (Windows)

scoop install act

Winget (Windows)

winget install nektos.act

Usage guide

Events

act has basic event support, it will try to get as much information from local repository as possible, although this might be not enough for certain event types.
Running act without any event name specified will run with event push.
For a list of event names, please see events that trigger workflows.

push:

act push

Runs all workflows with push event

pull_request:

act pull_request

schedule:

act schedule

To list all workflows for a given event, use -l/--list:

act -l pull_request

Using event file to provide complete event payload

If your workflow relies on passed event properties, you will have to provide required properties in the event file, example:

To partially simulate pull_request event, you to provide at least head_ref and base_ref. This values can be later accessed via ${{ github.event.pull_request.<...> }}

{
  "pull_request": {
    "head": {
      "ref": "sample-head-ref"
    },
    "base": {
      "ref": "sample-base-ref"
    }
  }
}

To partially simulate push event with a tag, you need to provide ref which will be accessible via ${{ github.event.ref }}

{
  "ref": "refs/tags/this-is-a-tag"
}

Workflows

By default act will run all workflows in .github/workflows.

You can override that behaviour with -W/--workflows flag by specifying directory containing workflow files

act -W '.github/workflows/'

This example will run all jobs in all workflows in directory .github/workflows but only if the trigger event is push

or by specifying exact workflow file to run

act -W '.github/workflows/checks.yml'

This example will run all jobs in .github/workflows/checks.yml workflow file but only if it's trigger event is push

Jobs

By default act will run all jobs in all workflows that are triggerred by push event

act -j 'test'

This example will run all jobs named test in all workflows that trigger on push event

Configuration file

Act can be configuring using .actrc files. All found arguments will be parsed and appended to a list, in order of: .actrc as per the XDG spec, .actrc in HOME directory, .actrc in invocation directory, cli arguments.

Format: One argument per line, no comments supported.

Example:

--container-architecture=linux/amd64
--action-offline-mode

Vars

To run act with repository variables that are acessible inside the workflow via ${{ vars.VARIABLE }}, you can enter them interactively or load them from a file. The following options are available for providing github repository variables:

act --var VARIABLE=somevalue - use somevalue as the value for VARIABLE.
act --var-file my.variables - load variables values from my.variables file.
The variables file format is the same as .env format

Secrets

To run act with secrets, you can enter them interactively, supply them as environment variables or load them from a file. The following options are available for providing secrets:

⚠ WARNING ⚠

When inserting sensitive data in your terminal, it might be saved as plain text to history file provided by your shell. To mitigate that, prefix act ... command with a space (not all shells respect that) or use secure input (explained below) to insert data.

act -s MY_SECRET=somevalue - use somevalue as the value for MY_SECRET.
act -s MY_SECRET - check for an environment variable named MY_SECRET and use it if it exists. If the environment variable is not defined, prompt the user for a value. This is recommended way of typing/pasting a secret into terminal, as act will provide secure input prompt for you to type/paste your secret which will not be saved in your shell history file.
act --secret-file my.secrets - load secrets values from my.secrets file.
- secrets file format is the same as .env format

`GITHUB_TOKEN`

GitHub automatically provides a GITHUB_TOKEN secret when running workflows inside GitHub. If your workflow fails with an error about token, it most likely requires GITHUB_TOKEN to be set up. If your workflow depends on this token, you need to create a personal access token and pass it to act as a secret:

act -s GITHUB_TOKEN=[insert token or leave blank and omit equals for secure input]

If GitHub CLI is installed, the gh auth token command can be used to autmatically pass the token to act

act -s GITHUB_TOKEN="$(gh auth token)"

WARNING: GITHUB_TOKEN will be logged in shell history if not inserted through secure input or (depending on your shell config) the command is prefixed with a whitespace.

`.env`/`.secrets` files structure

.env and .secrets files are using Ruby's gem dotenv format through godotenv library

Example:

export MY_ENV='value'
PRIV_KEY="---...\nrandom text\n...---"
JSON="{\n\"name\": \"value\"\n}"
SOME_VAR=SOME_VALUE

To see more examples, go to https://github.com/joho/godotenv/tree/v1.4.0/fixtures

Skipping jobs

You cannot use the env context in job level if conditions, but you can add a custom event property to the github context. You can use this method also on step level if conditions.

on: push
jobs:
  deploy:
    if: ${{ !github.event.act }} # skip during local actions testing
    runs-on: ubuntu-latest
    steps:
    - run: exit 0

And use this event.json file with act otherwise the Job will run:

{
    "act": true
}

Run act like

act -e event.json

Hint: you can add / append -e event.json as a line into ./.actrc

Skipping steps

Act adds a special environment variable ACT that can be used to skip a step that you don't want to run locally. E.g. a step that posts a Slack message or bumps a version number. You cannot use this method in job level if conditions, see Skipping jobs

- name: Some step
  if: ${{ !env.ACT }}
  run: |
    ...

Pass Inputs to Manually Triggered Workflows

Example workflow file

on:
  workflow_dispatch:
    inputs:
      NAME:
        description: "A random input name for the workflow"
        type: string
      SOME_VALUE:
        description: "Some other input to pass"
        type: string
jobs:
  test:
    name: Test
    runs-on: ubuntu-latest
    steps:
      - name: Test with inputs
        run: |
          echo "Hello ${{ github.event.inputs.NAME }} and ${{ github.event.inputs.SOME_VALUE }}!"

via input or input-file flag

act --input NAME=somevalue - use somevalue as the value for NAME input.
act --input-file my.input - load input values from my.input file.
- input file format is the same as .env format

via JSON

Example JSON payload file conveniently named payload.json

{
  "inputs": {
    "NAME": "Manual Workflow",
    "SOME_VALUE": "ABC"
  }
}

Command for triggering the workflow

act workflow_dispatch -e payload.json

Specifying Matrix

You can selectively choose a subset of matrix options to run by specifying the --matrix flag. It will only run those matrix configurations which include your specified values.

Example workflow file

name: matrix-with-user-inclusions
on: push
jobs:
  build:
    name: Matrix
    runs-on: ubuntu-latest
    steps:
      - run: echo ${NODE_VERSION}
        env:
          NODE_VERSION: ${{ matrix.node }}
    strategy:
      matrix:
        os: [ubuntu-18.04, macos-latest]
        node: [4, 6, 8, 10]
        exclude:
          - os: macos-latest
            node: 4
        include:
          - os: ubuntu-16.04
            node: 10

In this case if we only wanted to run this workflow for node 8, then we would run act push --matrix node:8

This will trigger the workflow to use the following matrix configurations only:

os: ubuntu-18.04, node: 8
os: macos-latest, node: 8

Similarly if we just wanted to trigger this workflow for node 10 and macos-latest then we would run act push --matrix node:10 --matrix os:macos-latest.

This will trigger the workflow to use the following matrix configurations only:

os: macos-latest, node 10

Note that using the --matrix flag you can't add new values (for e.g. running the above workflow for node 20). It will simply ignore it. Moreover, the exclude field in the workflow will take precedance over the --matrix flag (for e.g. running the above workflow for only macos-latest and node 4 will result in no matrix configuration being used)

Action Offline Mode

If you want to speed up running act and using cached actions and container images you can enable this mode.

stops pulling existing images
stops failing if an action has been cached and you cannot connect to GitHub
pulls non existent actions and images
act will work offline if it has at least ran once while you are online
get rid of unnecessary timeouts when you have an unstable connection to GitHub or Container registries
workaround rate limit problems

  act --action-offline-mode

or a .actrc file in your cwd like

--action-offline-mode

Runners

GitHub Actions offers managed virtual environments for running workflows. In order for act to run your workflows locally, it must run a container for the runner defined in your workflow file. Here are the images that act uses for each runner type and size:

GitHub Runner	Micro Docker Image	Medium Docker Image	Large Docker Image
`ubuntu-latest`	`node:16-buster-slim`	`catthehacker/ubuntu:act-latest`	`catthehacker/ubuntu:full-latest`
`ubuntu-22.04`	`node:16-bullseye-slim`	`catthehacker/ubuntu:act-22.04`	`catthehacker/ubuntu:full-22.04`
`ubuntu-20.04`	`node:16-buster-slim`	`catthehacker/ubuntu:act-20.04`	`catthehacker/ubuntu:full-20.04`
`ubuntu-18.04`	`node:16-buster-slim`	`catthehacker/ubuntu:act-18.04`	`catthehacker/ubuntu:full-18.04`

If you want to run Windows and macOS based platforms and you are running act within that specfic environment you can opt out of docker and run them directly on your host system.

Here are some examples

act -P ubuntu-latest=-self-hosted
act -P windows-latest=-self-hosted
act -P macos-latest=-self-hosted

Default runners are intentionally incomplete

These default images do not contain all the tools that GitHub Actions offers by default in their runners. Many things can work improperly or not at all while running those image. Additionally, some software might still not work even if installed properly, since GitHub Actions are running in fully virtualized machines while act is using Docker containers (e.g. Docker does not support running systemd). In case of any problems please create issue in respective repository (issues with act in this repository, issues with nektos/act-environments-ubuntu:18.04 in nektos/act-environments and issues with any image from user catthehacker in catthehacker/docker_images)

Alternative runner images

If you need an environment that works just like the corresponding GitHub runner then consider using an image provided by nektos/act-environments:

nektos/act-environments-ubuntu:18.04 - built from the Packer file GitHub uses in actions/virtual-environments.

:warning: :elephant: *** WARNING - this image is >18GB 😱***

catthehacker/ubuntu:full-* - filesystem dump of the Runners provided by GitHub, see ChristopherHX/runner-image-blobs or catthehacker/docker_images for more information

Use an alternative runner image

To use a different image for the runner, use the -P option.

act -P <platform>=<docker-image>

If your workflow uses ubuntu-18.04, consider below line as an example for changing Docker image used to run that workflow:

act -P ubuntu-18.04=nektos/act-environments-ubuntu:18.04

If you use multiple platforms in your workflow, you have to specify them to change which image is used. For example, if your workflow uses ubuntu-18.04, ubuntu-16.04 and ubuntu-latest, specify all platforms like below

act -P ubuntu-18.04=nektos/act-environments-ubuntu:18.04 -P ubuntu-latest=ubuntu:latest -P ubuntu-16.04=node:16-buster-slim

Using local runner images

The --pull flag is set to true by default due to a breaking on older default docker images. This would pull the docker image everytime act is executed.

Set --pull to false if a local docker image is needed

  act --pull=false

Alternatively turn on offline mode

  act --action-offline-mode

Custom container engine

You can use a different container engine that is compatible with the Docker Engine API, by setting the DOCKER_HOST environment variable to a custom socket path.

Example how to use `podman` with `act` using `sh` shell

DOCKER_HOST='unix:///var/run/podman/podman.sock' act # ...

export DOCKER_HOST='unix:///var/run/podman/podman.sock'
act # ...

Using `act` with remote Docker engine via SSH

DOCKER_HOST='ssh://user@host' act # ...

Using `act` with remote Docker engine via SSH in PowerShell

$env:DOCKER_HOST = 'ssh://user@host'
act # ...

GitHub Enterprise

Act supports using and authenticating against private GitHub Enterprise servers. To use your custom GHE server, set the CLI flag --github-instance to your hostname (e.g. github.company.com).

Please note that if your GHE server requires authentication, we will use the secret provided via GITHUB_TOKEN.

Please also see the official documentation for GitHub actions on GHE for more information on how to use actions.

Unsupported functionality

While we try to implement all features of GitHub Runners, due to design choices and manpower available it's not possible to make act completely compatible.

Here is a list of features that is (yet) to be implemented or is decided as not going to be worked on by act maintainers.

Planned

concurrency is ignored
run-name is ignored
Context availability is not checked, so you can use the env context on more places
Step summary not processed
Problem matcher ignored
Annotations ignored
No vars context
Incomplete github context
Run steps cancellation not implemented
job.permissions ignored
timeout-minutes ignored
job.continue-on-error ignored
PATH of container / of act must contain node for nodejs actions, github runner has their own copy for both container and host
Openid Connect url is not defined
job.environment ignored and scoping secrets by deployment environment is not supported

Functionality that is not going to be worked on

Docker context (#583)

`docker context` support

The current docker context isn't respected (#583).

You can work around this by setting DOCKER_HOST before running act, with e.g:

export DOCKER_HOST=$(docker context inspect --format '{{.Endpoints.docker.Host}}')

If your other host requires client certificates, the DOCKER_CERT_PATH environment variable is respected.

export DOCKER_CERT_PATH=$(docker context inspect --format '{{.Storage.TLSPath}}')/docker

Known issues

To see all current issues, go to https://github.com/nektos/act/issues

MODULE_NOT_FOUND

`MODULE_NOT_FOUND`

A MODULE_NOT_FOUND during docker cp command #228 can happen if you are relying on local changes that have not been pushed. This can get triggered if the action is using a path, like:

- name: test action locally
  uses: ./

In this case, you must use actions/checkout@v2 with a path that has the same name as your repository. If your repository is called my-action, then your checkout step would look like:

steps:
  - name: Checkout
    uses: actions/checkout@v2
    with:
      path: "my-action"

If the path: value doesn't match the name of the repository, a MODULE_NOT_FOUND will be thrown.

Integrations

act is used as part of:

act - User Guide | Manual | Docs | Documentation