Run GitHub Actions Locally with Act

GitHub Actions has become a prominent tool in the CI/CD space. It offers easy and hassle-free configuration, and workflows can be set up in minutes, with many components available out of the box.

The most challenging part, however, is testing the workflow before actually pushing it to production. During the initial setup, we often need enough room to run and experiment with the workflow. Running such experiments directly in GitHub Actions is not always convenient. Wouldn’t it be amazing if we could run them locally, make changes, experiment, finalize, and then push everything to production? I always thought that would be a great idea.

Recently, while consulting with one of my clients, I needed to set up an automation workflow with GitHub Actions. During this process, I discovered a gem called Act. It's an open-source tool available on GitHub that makes it easy to run GitHub Actions locally. The tool is incredibly simple to install and use.

GitHub: https://github.com/nektos/act
Website: https://nektosact.com/

Docker Images for Act: Micro, Medium, and Large

Act offers three Docker images to suit different workflows:

Micro Image

• Lightweight and minimal, ideal for simple workflows with few dependencies.
• Suited For: Basic scripts or small actions

Medium Image

• A balanced environment with moderate dependencies.
• Suited For: Workflows that require some external services or APIs.

Large Image

• Feature-rich and includes extensive dependencies for complex workflows.
• Suited For: Large workflows requiring multiple services or infrastructure.

Installation:

Docker

Act uses Docker to simulate the GitHub Actions execution environment. Therefore, ensure that Docker Desktop is installed and the Docker daemon is up and running.

While it’s possible to run Act directly on your OS without Docker if container isolation is not required, this is generally not the case.

Act

You can install Act using available package managers or by directly downloading the pre-built executables. A list of supported package managers can be found in the installation guide. For simplicity, I prefer downloading the executable directly, which is also available in the installation guide.

Usage

Once installation is complete, we can simply browse the root directory of project and run act from command line.

Here is a step-by-step working example.

Setting up a sample in .NET project for demo.

Preparing a workflow

name: .NET Build and Test

 

on:

  workflow_dispatch:

 

jobs:

  build-and-test:

    runs-on: ubuntu-latest

 

    steps:

      - name: Check out code

        uses: actions/checkout@v3

 

      - name: Set up .NET

        uses: actions/setup-dotnet@v3

        with:

          dotnet-version: '8.0'

 

      - name: Restore dependencies

        run: dotnet restore

 

      - name: Build solution

        run: dotnet build --no-restore --configuration Release

 

      - name: Run tests

        run: dotnet test --no-build --configuration Release

Executing with Act

Navigate to the root folder of the project and run “act”. By Default, Act runs all the available workflows in “.github\workflows” directory. We can override the directory or choose a specific workflow by using --workflows flag to specify directory and file.

In My case, I have only one workflow file and the Act executable is stored in a directory. So, I can run

‘D:\ACT\Act\act.exe’ in the project root directory.

Finally, after the successful run.

Important points to remember

• The repository must be initialized and at least locally pointed to the origin.
• Different events can be specified, such as act push, act pull_request, and act schedule.
• Variables can be injected either using the --var flag (e.g., act --var ENV=DEV) or by specifying a .variable file using the --var-file flag (e.g., act --var-file var.variables).
• Similarly, secrets can be specified using the --secret flag (e.g., act --secret TOKEN=123) or by specifying a .secrets file using the --secret-file flag (e.g., act --secret-file sec.secrets).
• Both the .variable and .secrets files follow the format of a .env file.

 

Act is a user-friendly and effective tool for running GitHub Actions locally, streamlining the process of testing workflows before pushing to production. It offers three Docker image options—Micro, Medium, and Large—to cater to different workflow complexities, allowing us to choose the best fit for our needs. Whether you're working with simple tasks or more intricate processes, Act provides a flexible environment for experimentation. However, it's worth noting that while Act is a fantastic tool for most scenarios, it may not support every complex workflow. Some advanced features or services might not function exactly as they would in GitHub's production environment, so it's important to keep its limitations in mind when working with more complicated workflows.