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

You can specify directory containing workflow files:

act -W .github/workflows/

or which workflow to run with -W/--workflows flag:

act -W .github/workflows/checks.yml

Jobs

You can specify which job to use via -j/--job flag:

act -j test

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

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 Actions provides secrets.GITHUB_TOKEN and github.token automatically, on which many actions rely. This is possible to do so in act, if you use set it as a secret (GITHUB_TOKEN=ghp_...). If your workflow fails with an error about token, it most likely requires GITHUB_TOKEN to be set up.

.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