DEV Community

Cover image for Run GitHub Actions on Your Local Machine! ๐Ÿ™ ๐Ÿ’ป
Zoo Codes
Zoo Codes

Posted on • Updated on

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


Enter fullscreen mode Exit fullscreen mode


# For Debian based Linux distributions
sudo apt install act


Enter fullscreen mode Exit fullscreen mode


# For Fedora
sudo dnf install act


Enter fullscreen mode Exit fullscreen mode


# For Arch Linux
sudo pacman -Syu act



Enter fullscreen mode Exit fullscreen mode


# For Windows
choco install act


Enter fullscreen mode Exit fullscreen mode

Read more about the installation here

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


Enter fullscreen mode Exit fullscreen mode

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


Enter fullscreen mode Exit fullscreen mode

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


Enter fullscreen mode Exit fullscreen mode

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:

  1. Using the act command
  2. 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


Enter fullscreen mode Exit fullscreen mode

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


Enter fullscreen mode Exit fullscreen mode

Read more about runner images here

Runner images

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


Enter fullscreen mode Exit fullscreen mode

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


Enter fullscreen mode Exit fullscreen mode

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


Enter fullscreen mode Exit fullscreen mode

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"


Enter fullscreen mode Exit fullscreen mode

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



act


Enter fullscreen mode Exit fullscreen mode

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 }}


Enter fullscreen mode Exit fullscreen mode

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"


Enter fullscreen mode Exit fullscreen mode

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

Hello world secrets

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

References

Top comments (3)

Collapse
 
hartley94 profile image
Martin Thuo

Great share ๐Ÿ”ฅ

Collapse
 
josephrana11 profile image
Joseph Rana • Edited

" sudo snap install act " installs another act, not the one mentioned in this article. link

Collapse
 
ken_mwaura1 profile image
Zoo Codes

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

Read more here