Home / Blog / Runners and limits
Run GitHub Actions locally: act and its limits
To run a GitHub Actions workflow on your machine, use act, which runs each job in Docker. The commands I ran, and what only GitHub can run: OIDC, GITHUB_TOKEN.
To run a GitHub Actions workflow on your own machine, install act, an open-source tool that reads your .github/workflows directory and runs each job in a Docker container. act push runs the jobs a push would start, and act -j test runs one job. I ran act 0.2.98 on a Mac. It reproduces your steps and their shell, not GitHub: there was no OIDC token, no GITHUB_TOKEN and no GitHub cache. If you find GitHub Actions slow, our guide has more fixes.
- act runs a workflow's jobs in Docker containers on your machine: act push runs the push jobs, act -j test runs one.
- Its default images are intentionally incomplete; GitHub lists what its own images hold in actions/runner-images.
- Under act there is no OIDC token and no GITHUB_TOKEN unless you pass one, and permissions, timeouts and concurrency are ignored.
- actions/cache saves to a cache server act runs on your machine, never to GitHub's cache.
- Without act, run a step's commands with GitHub's shell: bash -e with no shell set, or bash --noprofile --norc -eo pipefail.
- Anything that needs OIDC, an environment, macOS, Windows or GitHub's cache has to be tried on GitHub.
act’s README gives two reasons to use it: fast feedback, because you can try a change to a workflow file without committing and pushing it each time, and a local task runner, because the workflows you already have can stand in for a Makefile. Both are real. This guide shows the commands I ran and their output, then goes through what a local run cannot copy, from act’s own list of what it does not support and GitHub’s documentation of what a job is given. The pages were read on the date this post was last checked.
Install act and Docker
act needs Docker: its installation page says it depends on the Docker Engine API to run workflows in containers. On a Mac that means Docker Desktop or another engine that serves the same API. act itself is one binary. Its installation page lists package repositories, Homebrew and a GitHub CLI extension among them, an install script, and prebuilt binaries on the release page. I took the macOS arm64 binary of release 0.2.98, checked its SHA-256 against the release’s checksums.txt, and ran it from a scratch directory, so nothing was installed system-wide.
Run a workflow with act
The repository I ran it in held one script and one workflow. The script is the test suite in miniature; the workflow’s last step prints three things a job on GitHub would have.
#!/usr/bin/env bash
set -euo pipefail
test $((2 + 2)) -eq 4
echo "tests passed"
name: ci
on: [push, pull_request]
permissions:
contents: read
id-token: write
jobs:
test:
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- uses: actions/checkout@v4
- run: ./test.sh
- name: What only GitHub provides
run: |
echo "event: ${{ github.event_name }}"
echo "OIDC request URL: ${ACTIONS_ID_TOKEN_REQUEST_URL:-<unset>}"
echo "GITHUB_TOKEN empty: ${{ secrets.GITHUB_TOKEN == '' }}"
act -l lists what act found, without running anything:
act -l
Stage Job ID Job name Workflow name Workflow file Events
0 test test ci ci.yml push,pull_request
On Apple silicon it also warned that I had not specified a container architecture and that, if I met problems, I could try --container-architecture linux/amd64. The image I used has an arm64 build, so I left the flag off and met none.
Then the run. -P maps a runs-on label to a Docker image. act’s documentation lists three sizes of image for ubuntu-latest: micro is node:16-buster-slim, medium is catthehacker/ubuntu:act-latest and large is catthehacker/ubuntu:full-latest. I named the micro one, which is enough for a shell script:
act push -P ubuntu-latest=node:16-buster-slim
[ci/test] | tests passed
[ci/test] | event: push
[ci/test] | OIDC request URL: <unset>
[ci/test] | GITHUB_TOKEN empty: true
The job succeeded. The tests ran, the event was a push, and the two things GitHub hands every job were missing. That image is not GitHub’s, either. act’s documentation is blunt about it: its default runners are intentionally incomplete, and do not contain all the tools that GitHub Actions offers by default. GitHub lists what its own images hold in the actions/runner-images repository, so a step that relies on a preinstalled tool can pass on GitHub and fail under act, or the other way round.
The flags you will use
These are from act’s usage page and its own --help. I ran the dry run; the others are as the documentation gives them.
act pull_request # the jobs a pull_request event would start
act -j test # one job, by its id
act -W .github/workflows/checks.yml # one workflow file
act -n # validate only: no containers are created
act -s MY_SECRET # a secret, asked for if it is not in the environment
act --secret-file my.secrets # secrets from a file
act --var VARIABLE=some-value # a configuration variable, the vars context
act workflow_dispatch -e payload.json # an event with its payload
act push --matrix node:10 # only the matrix entries where node is 10
Keep a secrets file out of git. The event payload matters more than it looks: a step that reads github.event.pull_request sees only what your JSON file puts there.
What act reproduces
Your steps, in order, with their shell. act ran each run step that names no shell as bash -e, which is what GitHub’s workflow syntax says a Linux runner does when no shell is given. Expressions were evaluated, so ${{ github.event_name }} printed the event I asked for.
Actions are fetched from GitHub. For actions/cache@v4 act printed a git clone of https://github.com/actions/cache at v4, so a local run still needs the network. For actions/checkout it cloned nothing: it copied my working directory into the container. That is what you want while editing, and it means the run tests the files on your disk, uncommitted changes included, not the commit GitHub would check out.
What only GitHub can run
act publishes a list of what it does not support, and it is the most useful page in its documentation. It ignores concurrency, run-name, a job’s permissions, timeout-minutes and continue-on-error, and a job’s environment, so secrets scoped to a deployment environment are not supported. It discards step summaries, ignores problem matchers and annotations, has not implemented cancelling a run step, and has an incomplete github context. So the timeout-minutes my workflow set did nothing locally, and neither would concurrency settings.
GITHUB_TOKEN is the first thing most workflows miss. GitHub creates one at the start of each job, as an installation access token of the GitHub App that Actions installs on your repository, with permissions limited to that repository. Under act it was empty. act’s documentation shows how to pass one:
act -s GITHUB_TOKEN="$(gh auth token)"
That is your own GitHub CLI token, with whatever access you have, not a token scoped to one repository and one job. A step that works with it can still fail on GitHub with Resource not accessible by integration, because the real token has only the permissions the workflow grants.
OIDC cannot be faked at all. A job that grants id-token: write asks GitHub’s OIDC provider for a token, at the URL in ACTIONS_ID_TOKEN_REQUEST_URL, and gets one issued by https://token.actions.githubusercontent.com with claims for the repository, the ref and the environment. Your cloud provider trusts that issuer, not your laptop. My workflow granted the permission and the variable was unset, as act’s list says it will be. A deploy that signs in with OIDC has to be tried on GitHub.
macOS and Windows jobs have no container to run in. act’s documentation maps them to -self-hosted, which runs the job straight on your machine, so a macos-latest job runs only on a Mac and a windows-latest job only on Windows, against whatever that machine has installed.
actions/cache under act: a cache on your disk
act starts a cache server of its own and points actions/cache at it. I ran this workflow twice:
name: cache
on: push
jobs:
cache:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/cache@v4
id: deps
with:
path: deps
key: deps-${{ hashFiles('test.sh') }}
- run: echo "cache-hit=${{ steps.deps.outputs.cache-hit }}"
- run: mkdir -p deps && date > deps/stamp
With act’s defaults on Docker Desktop for Mac, the container could not reach the server. Both runs printed the same restore warning and missed, the first also failed to save, and both jobs still succeeded, because a cache that cannot be reached is a warning in actions/cache, not an error. The key is a 64-character hash, cut short here:
::warning::Failed to restore: getCacheEntry failed: socket hang up
[cache/cache] | Cache not found for input keys: deps-43116fd2…
Binding the server to the Mac’s loopback address on a fixed port, and giving the container an address it can reach, fixed it. The first run saved the entry and the second restored it, under the same key:
act push -W .github/workflows/cache.yml -P ubuntu-latest=node:16-buster-slim \
--cache-server-addr 127.0.0.1 --cache-server-port 34567 \
--cache-server-external-url http://host.docker.internal:34567
[cache/cache] | Cache restored successfully
[cache/cache] | Cache restored from key: deps-43116fd2…
[cache/cache] | cache-hit=true
The entry lives in a directory on your disk. So a local hit or miss says nothing about GitHub’s cache, which has rules of its own: by default 10 GB per repository, entries not accessed in over 7 days removed, and a run may restore only caches from its own branch, the default branch or, for a pull request, the base branch. The cache limit guide goes through them. Test your cache key locally if you like; test whether it hits in CI.
Without act: run the commands with GitHub’s shell
Most of a step is a command, and you can run the command without act at all. Run it with the shell GitHub uses, or a failure can hide. GitHub’s workflow syntax gives two commands for Linux: a step with no shell runs bash -e {0}, and a step with shell: bash runs bash --noprofile --norc -eo pipefail {0}. The difference is pipefail. I ran this script under both:
false | true
echo "still here"
bash -e pipe.sh # printed "still here", exit status 0
bash --noprofile --norc -eo pipefail pipe.sh # printed nothing, exit status 1
A failed command on the left of a pipe passes a step that names no shell and fails one that says shell: bash. Put set -euo pipefail at the top of your scripts, as the test script above does, and the two agree. The more of a job lives in scripts like that, the less there is left that only a runner can test.
For the tools, a dev container helps. GitHub describes dev containers as Docker containers configured to provide a fully featured development environment, set up in .devcontainer/devcontainer.json, and the Development Containers specification says one can aid continuous integration and testing. Pin the versions your job installs in that file and the scripts run against the same tools on your laptop as in CI.
What to test where
| Part of a job | Under act | Why |
|---|---|---|
| Your run steps and the shell they use | Yes | act ran a run step with no shell as bash -e, as GitHub documents |
| Actions from the marketplace (uses:) | Yes, fetched from GitHub | act cloned actions/cache from github.com |
| The image a job runs on | No | act's default images are intentionally incomplete |
| GITHUB_TOKEN | Only if you pass one | It was empty in my run |
| An OIDC token (id-token: write) | No | act: the OpenID Connect URL is not defined |
| Environments and their secrets | No | act ignores job.environment |
| permissions, timeout-minutes, continue-on-error, concurrency | No | act ignores them |
| Step summaries and annotations | No | act discards and ignores them |
| actions/cache | Against a local server | Never GitHub's cache |
| macOS and Windows jobs | Only on that system, outside a container | act's -self-hosted platform |
Use act, or the bare scripts, for the loop of editing a workflow: syntax, expressions, step order, the commands themselves. Push a branch for anything in the right-hand half of that table, and for anything that depends on GitHub’s image. The run on GitHub goes wherever runs-on sends it, a GitHub-hosted runner, one of your own, or managed GitHub Actions runners such as ours, and the token and the OIDC claims are GitHub’s on every one of them.
Sources
- act README (nektos/act) (github.com)
- act release v0.2.98 (github.com)
- act user guide: installation (nektosact.com)
- act user guide: usage (nektosact.com)
- act user guide: runners (nektosact.com)
- act user guide: unsupported functionality (nektosact.com)
- GITHUB_TOKEN (docs.github.com)
- Contexts reference (docs.github.com)
- OpenID Connect (docs.github.com)
- OpenID Connect reference (docs.github.com)
- Dependency caching reference (docs.github.com)
- Workflow syntax for GitHub Actions (docs.github.com)
- GitHub-hosted runners reference (docs.github.com)
- actions/runner-images (github.com)
- Introduction to dev containers (docs.github.com)
- Development Containers (containers.dev)
Frequently asked questions
How do I run GitHub Actions locally?
Install Docker and act, then run act push in the repository. act reads .github/workflows and runs each job in a container. act -l lists the jobs, act -j test runs one, and act -n validates the workflow without creating containers.
Does act give my workflow a GITHUB_TOKEN?
No. GitHub creates one at the start of each job, and under act it was empty. act's documentation shows passing one with -s GITHUB_TOKEN set from gh auth token, which is your own token with your own access, not the job's.
Does OIDC work when I run GitHub Actions locally?
No. A job with id-token: write asks GitHub's OIDC provider for a token, and act lists the OpenID Connect URL as not defined. In my run the request URL was unset, so a deploy that signs in with OIDC has to be tried on GitHub.
Does actions/cache work under act?
Yes, against a cache server act runs on your machine, never GitHub's cache. On Docker Desktop for Mac the container could not reach it until I set act's cache server address and external URL; then the second run restored the entry.
Can act run macOS or Windows jobs?
Not in a container. act's documentation maps macos-latest or windows-latest to -self-hosted, which runs the job straight on your machine, so only on that operating system and against whatever it has installed.