Skip to main content

Testing Github Actions locally using act

This guide dives into the process of testing GitHub Actions locally. Unlike Jenkins, where you can quickly copy and paste your pipeline code into a test job and execute it (a messy but effective workaround), GitHub Actions demands that you commit and push every change before the runner processes it. For those who rely on an iterative trial and error workflow like me, this approach can feel like an unnecessary drain on time.

To solve this problem, I found and tried Act, a tool made by the community that lets you run GitHub Actions workflows on your own computer. Act uses the Docker API, so you need Docker installed, and it works with Ubuntu-based images set up like GitHub’s runners (with similar environment variables and file structures).

Testing sample

For this article, we’ll use a sample repository: cplee/github-actions-demo. This repository features a simple Node.js application designed to demonstrate how GitHub Actions work.

The workflows for testing, building, and deploying the code are already defined in the .github/workflows/ directory. This eliminates the need for a separate Makefile to handle local development tasks. Instead, you can rely on Act to run the actions locally.

Key Commands

Here are some useful Act commands for working with the repository:

bash
# Run the tests
act -j test

# Run the entire pipeline
act

# View the execution graph
act -l

By using Act, you can efficiently test and debug your GitHub Actions workflows without the need to repeatedly commit and push changes. This approach saves time and streamlines your development process.

Running a Workflow

To run a GitHub Actions workflow using act. Follow these steps:

  1. Ensure you have a repository with a GitHub Actions workflow defined in .github/workflows/test.yml.

  2. Run the following command to execute the workflow:

    bash
    act -W .github/workflows/test.yml

Using Secrets

To address this issue, you'll need to use a Personal Access Token (PAT) from your GitHub account and provide it to act. The token should have at least the repo scope (although, to be honest, GitHub's token scopes can be a bit confusing or overly broad/narrow at times).

To pass the token to act, use the following command:

bash
act -W .github/workflows/test.yml -s GITHUB_TOKEN="yourtoken"

You can also use the GitHub CLI (gh) to generate and retrieve your token. To do this, run the following command:

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

Installation

Before installing, ensure you meet the necessary prerequisites for running act.

act depends on Docker (specifically the Docker Engine API) to run workflows in containers. If you don't require container isolation, you can run selected jobs (e.g., Windows or macOS) directly on your system. In this case, Docker installation is not required.

  • Linux users: Install Docker Engine by following the Docker Docs.
  • macOS users: Follow the Docker Docs to install Docker Desktop for Mac.
  • Windows users: Follow the steps in the Docker Docs to install Docker Desktop for Windows.

Note: act currently does not support Podman or other container backends (it might work, but it’s not guaranteed). For updates, check issue #303.

For a complete installation guide, visit the official act website to choose the best option for your setup.