Run GitHub Actions on Your Local Machine! 🐙 💻

New Month New Blog Post! I recently got Azure Dev-ops Certified, expect more devops related content as I've learned a lot while studying for the certification.

This month I will continue writing about GitHub Actions. If you are new to GitHub Actions, I recommend reading my previous blog posts:

Introduction

GitHub Actions is a great tool for automating your workflow. However, it is not always easy to test your workflow locally. This is because GitHub Actions is a cloud-based service and you need to push your code to GitHub to test it. This is not always convenient, especially when you are developing your workflows locally.

Example of typical development cycle including pushing code and waiting for workflow to complete.

Successful run

This is where act comes in. It is a command-line tool that allows you to run your GitHub Actions locally. It is a great tool for testing your workflows locally before pushing them to GitHub.

Act also allows you to run your workflows on a self-hosted runner. This is useful if you want to run your workflows on a machine that is not connected to the internet. For example, you can run your workflows on a Raspberry Pi.

For me act has allowed me to test my workflows locally before pushing them to GitHub and waiting for the results. This has saved me a lot of time and frustration. I hope it will do the same for you.

Installation ⚒️

Act is available on GitHub and Homebrew. You can install it using the following command:

# For macOS
brew install act

# For Ubuntu Linux 
sudo snap install act

# For Debian based Linux distributions
sudo apt install act

# For Fedora
sudo dnf install act

# For Arch Linux
sudo pacman -Syu act

# For Windows
choco install act

Act-install

Usage 📖

Act is a CLI tool thus you can use it in your terminal. The following command will run your GitHub Actions locally:

act

Example of running a workflow:

workflow running

You can also specify the name of the workflow you want to run using the -W flag. For example, the following command will run the workflow.yml file:

cd .github/workflows
act -W workflow.yml

Example of running a specific workflow file:

Running specific workflow

For the full list of commands and flags, you can run the following command:

act --help

Act help options

list workflows

How it works

Act uses Docker to run your GitHub Actions locally. This allows you to run your workflows on any machine that has Docker installed. There are two ways to run your workflows using act:

Using the act command
Using the act GitHub Action

Using the act command is the easiest way to run your workflows locally. However, it does not allow you to run your workflows on a self-hosted runner. This is where the act GitHub Action comes in. It allows you to run your workflows on a self-hosted runner. This is useful if you want to run your workflows on a machine that is not connected to the internet. For example, you can run your workflows on a Raspberry Pi.

Using docker containers allows for isolation of the environment. This means that you can run your workflows on a machine that has a different operating system than the one you are using. For example, you can run your workflows on a Windows machine using a Linux container. This is useful if you are developing your workflows on a Windows machine.

Base Docker images 🐳

First time running the act you have option of either using the default docker image or using your own docker image. The default docker image is nektos/act-environments-ubuntu:latest. You can use the following command to use the default docker image:

act

This image is based on the latest Ubuntu release . It has the a minimal set of tools installed. You can use the following command to use your own docker image:

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

Security

Secrets

Act allows to add secrets to your workflow. This is useful if you want to test your workflows locally. However, you need to be careful when using this feature. This is because act allows you to run any code locally. This means that if you are not careful, you can run malicious code on your machine.

Environment variables

Act supports adding environment variables using .env file(s). It checks the current directory and all parent directories for a file named .env. You can use the following command to add environment variables:

echo "FOO=BAR" >> .env

However you can overwrite the default location of the .env file using the -env-file flag. For example, the following command will add environment variables from the .env file in the current directory:

act -env-file .env

Configuration ⚙️

Act allows you to configure your workflows using the ./.actrc or a ~/.actrc file. This is useful if you want to change the default settings. For example, you can change the default docker image. Add the following line to your ~/.actrc file:

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

Read more about the configuration file here

Examples

Running a workflow

The following example shows how to run a workflow locally. The workflow is a simple one that gets the current time and prints it to the console. The workflow is located in the .github/workflows directory. The workflow file is named hello-world.yml.

name: Hello World

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Hello world action step
        uses: actions/hello-world-javascript-action@v1
        with:
          who-to-greet: 'Mona the Octocat'  # default is "World"

To run the workflow, you can use the following command:

act

This will first download the docker image and then run the workflow. The following image shows the output of the command:

Hello world

Running a workflow with secrets

The following example shows how to run a workflow locally with secrets. The workflow is a simple one that gets the current time and prints it to the console. The workflow is located in the .github/workflows directory. The workflow file is named hello-world-secrets.yml.

name: Hello World

on: [push]

jobs:
  build:
 runs-on: ubuntu-latest
 steps:
   - name: Hello world action step
  uses: actions/hello-world-javascript-action@v1
  with:
    who-to-greet: ${{ secrets.WHO_TO_GREET }}

The workflow uses a secret named WHO_TO_GREET. To run the workflow, you can use the following command:

act -s WHO_TO_GREET="Mona the Octocat"

This will first download the docker image and then run the workflow. The following image shows the output of the command:

Hello world secrets

GitHub Repository

Check the GitHub repo for the full workflow files.

Conclusion

This was a brief introduction to act. I hope it will help you run your GitHub Actions locally. If you have any questions or suggestions, feel free to leave a comment below.

Buy Me a Coffee

next time