s0sta
EN NL عربي
Filters
How to search
  • Plain words find names, texts and examples.
  • "two words" finds the exact phrase.
  • --name or -x finds an option.
  • #word looks only inside commands.
  • @grep finds lessons and labs that use grep.
  • Filters: cat:network · in:labs · in:notes · level:rhcsa · ch:8 · root:yes. Put ! before a word to leave it out. OR between words means one of them.
  • ↑ ↓ to move · Enter to open · Esc to close · / to search

act

Run GitHub Actions workflows on your own machine in Docker — test a pipeline before you push.

Level
DevOps tool
Group
Git and CI/CD
Needs root
No
Package
act

What it does

Changing a workflow and pushing again and again to see if it works is slow. act reads .github/workflows/*.yml and runs the jobs locally in Docker containers that look like the GitHub runners. You see errors in seconds.

Not everything is the same as on GitHub (for example OIDC to the cloud and some services), but builds, tests, linters and scripts work well.

How to write it

act [EVENT] [OPTIONS]

Options 13

Most used

Options

EVENT
The event to simulate: push (default), pull_request, workflow_dispatch …
-j, --job NAME
Run only this job.
-l, --list
List the jobs and workflows.
-W, --workflows PATH
Use this workflow file or folder.
-n, --dryrun
Show what would run.
-s NAME=VALUE / --secret-file FILE
Give secrets.
--var NAME=VALUE / --var-file FILE
Give repository variables.
-e, --eventpath FILE
JSON file with the event payload.
-P ubuntu-latest=IMAGE
Choose the runner image.
--matrix KEY:VALUE
Run only one matrix entry.
--container-architecture linux/amd64
Needed on Apple Silicon for some images.
-v
Verbose output.
--input NAME=VALUE
Inputs for workflow_dispatch.

Examples 11

$ run as a normal user# run as root (or with sudo)

  1. 1List the jobs

    act -l

  2. 2Run the push workflows

    act

  3. 3Run one job of a pull request workflow

    act pull_request -j test

  4. 4Give a secret

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

  5. 5Secrets from a file (never commit it)

    cat .secrets
NPM_TOKEN=xxxx
act --secret-file .secrets

  6. 6Dry run

    act -n

  7. 7A bigger runner image (more tools inside)

    act -P ubuntu-latest=catthehacker/ubuntu:full-latest

  8. 8One matrix entry only

    act -j test --matrix node:22

  9. 9A manual workflow with inputs

    act workflow_dispatch --input environment=staging

  10. 10A custom event payload (for example a tag push)

    cat event.json
{ "ref": "refs/tags/v1.4.0" }
act push -e event.json

  11. 11On a Mac with Apple Silicon

    act --container-architecture linux/amd64

Watch out

  • Add .secrets and .vars to .gitignore.
  • Steps with if: ${{ !env.ACT }} are a way to skip things that only work on GitHub.
  • The default small image misses many tools; jobs that pass locally can still fail on GitHub (and the other way).

Files

.actrc
Default options (for example the runner images).
.secrets / .vars
Local secrets and variables.

Exit codes

0All jobs passed.
1A job failed.

Full manual

This page explains the command in simple words. The original manual has every detail.

In your terminal: man act

Open the man page (linux.die.net)