6.7 KiB

Raw Blame History

Overview

"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 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!

Installation

To install with Homebrew, run:

brew install nektos/tap/act

Alternatively, you can use the following:

curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

If you are running Windows, download the latest release and add the binary in to your PATH.

If you are running Arch Linux, you can install the act package with your favorite package manager:

yay -S act

Commands

# List the actions
act -l

# Run the default (`push`) event:
act

# Run a specific event:
act pull_request

# Run a specific job:
act -j test

# Run in dry-run mode:
act -n

# Enable verbose-logging (can be used with any of the above commands)
act -v

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:

GitHub Runner	Docker Image
ubuntu-latest	node:12.6-buster-slim
ubuntu-18.04	node:12.6-buster-slim
ubuntu-16.04	node:12.6-stretch-slim
windows-latest	`unsupported`
windows-2019	`unsupported`
macos-latest	`unsupported`
macos-10.15	`unsupported`

These default images do not contain all the tools that GitHub Actions offers by default in their runners. 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 - this image is >18GB 😱***

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

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

Secrets

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

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 environment variable is not defined, prompt the user for a value.

Configuration

You can provide default configuration flags to act by either creating a ./.actrc or a ~/.actrc file. Any flags in the files will be applied before any flags provided directly on the command line. For example, a file like below will always use the nektos/act-environments-ubuntu:18.04 image for the ubuntu-latest runner:

# sample .actrc file
-P ubuntu-latest=nektos/act-environments-ubuntu:18.04

Additionally, act support loading environment variables from a .env file. The default is to look in the working directory for the file, but can be overriden by:

act --env-file my.env

Events

Every Github event is accompanied with a payload. You can provide these events in JSON format with the --eventpath to simulate specific Github events kicking off an action. For example:

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

act -e pull-request.json

Act will properly provide github.head_ref and github.base_ref to the action as expected.

Support

Need help? Ask on Gitter!

Contributing

Want to contribute to act? Awesome! Check out the contributing guidelines to get involved.

Building from source

Install Go tools 1.11.4+ - (https://golang.org/doc/install)
Clone this repo git clone git@github.com:nektos/act.git
Run unit tests with make check
Build and install: make install

6.7 KiB Raw Blame History