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:
- Automate Docker Image Builds and Push to Docker Hub Using GitHub Actions ๐ณ๐
- Automate Docker Image Builds and Push to GitHub Registry Using GitHub Actions ๐
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.
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 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
Read more about the installation here
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:
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:
For the full list of commands and flags, you can run the following command:
act --help
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
Read more about runner images here
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:
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:
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
Top comments (3)
Great share ๐ฅ
" sudo snap install act " installs another act, not the one mentioned in this article. link
alternatively use curl:
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
Read more here