How to Run GitHub Actions Locally Using the act CLI Tool
![How to Run GitHub Actions Locally Using the act CLI Tool](https://talalzaman.com/wp-content/uploads/2024/03/How-to-run-GitHub-actions-locally.png)
[ad_1]
GitHub Actions help automate tasks like building, testing, and deploying in your GitHub repository.
With one click, you can publish your production-ready code or package on npm, GitHub pages, docker images, deploy your production code on a cloud provider, and so on.
The problem starts when you’re testing GitHub Actions. It can be time-consuming and painful. First, you have to change the GitHub Actions file locally, push your local code into your GitHub repository, and wait for the result.
To solve this issue, You can use the act
CLI tool to test and write the GitHub action locally. With act
CLI, you do not need to commit/push your local code to the GitHub Repository. You test GitHub action locally on your laptop or machine.
Here are the steps involved:
How to Install act
for GitHub Actions
The act
CLI tool works with Docker. Before starting with act
CLI, First, install Docker on your system or laptop.
To install the act
CLI, you need to run the following command:
# Window
choco install act-cli
# MacOS
brew install act
# Linux
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
How to Configure and Initialize the act
CLI
After the act
CLI installation is successful on your laptop or machine, the next step is to run it in your project.
act
CLI asks which Docker image size—large, medium, or micro—must be installed during installation.
There are various Docker image sizes:
- The Docker Micro image size is 200 MB, and small projects use it.
- The Docker Medium image size is 500 MB, and Big Project uses it.
- The Docker Large image size is 17 GB, and Enterprise uses it.
The act
CLI uses the Docker image to run the GitHub action locally.
$ act
act
CLI without any argument.The command output in the terminal looks like this:
$ test-github-actions git:(main) ✗ act
? Please choose the default image you want to use with act:
- Large size image: ca. 17GB download + 53.1GB storage, you will need 75GB of free disk space, snapshots of GitHub Hosted Runners without snap and pulled docker images
- Medium size image: ~500MB, includes only necessary tools to bootstrap actions and aims to be compatible with most actions
- Micro size image: <200MB, contains only NodeJS required to bootstrap actions, doesn't work with all actions
Default image and other options can be changed manually in ~/.actrc (please refer to https://github.com/nektos/act#configuration for additional information about file structure) Micro
[Build Ghost and test theme/install] 🚀 Start image=node:16-buster-slim
INFO[0023] Parallel tasks (0) below minimum, setting to 1
[Build Ghost and test theme/install] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true
INFO[0031] Parallel tasks (0) below minimum, setting to 1
[Build Ghost and test theme/install] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[Build Ghost and test theme/install] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[Build Ghost and test theme/install] ☁ git clone 'https://github.com/vimtor/action-zip' # ref=v1.2
[Build Ghost and test theme/install] ☁ git clone 'https://github.com/softprops/action-gh-release' # ref=v0.1.15
[Build Ghost and test theme/install] ⭐ Run Main actions/checkout@v4
[Build Ghost and test theme/install] 🐳 docker cp src=/home/officialrajdeepsingh/medium/test-github-actions/. dst=/home/officialrajdeepsingh/medium/test-github-actions
[Build Ghost and test theme/install] ✅ Success - Main actions/checkout@v4
[Build Ghost and test theme/install] ⭐ Run Main Easy Zip Files
[Build Ghost and test theme/install] 🐳 docker cp src=/home/officialrajdeepsingh/.cache/act/[email protected]/ dst=/var/run/act/actions/[email protected]/
[Build Ghost and test theme/install] 🐳 docker exec cmd=[node /var/run/act/actions/[email protected]/dist/index.js] user= workdir=
| Ready to zip "build/ home.txt" into example.zip
| - build/
| - home.txt
|
| Zipped file example.zip successfully
[Build Ghost and test theme/install] ✅ Success - Main Easy Zip Files
[Build Ghost and test theme/install] Cleaning up container for job install
[Build Ghost and test theme/install] 🏁 Job succeeded
After downloading the image from the Docker repository, the act
CLI runs the GitHub action.
act
CLI generates the ~/.actrc
file in the laptop for configuration. The ~/.actrc
file contains the Docker image name.
# .actrc
-P ubuntu-latest=node:16-buster-slim
-P ubuntu-22.04=node:16-bullseye-slim
-P ubuntu-20.04=node:16-buster-slim
-P ubuntu-18.04=node:16-buster-slim
To install other Docker images, remove the ~/.actrc
file and re-run the act
CLI to install the different Docker images.
Error
Due to dependence on Docker, we may face some errors when initializing an act
CLI for the first time.
$ act
The error should look like this:
$ test-github-actions git:(main) ✗ act
ERRO[0000] daemon Docker Engine socket not found and containerDaemonSocket option was not set
? Please choose the default image you want to use with act:
- Large size image: ca. 17GB download + 53.1GB storage, you will need 75GB of free disk space, snapshots of GitHub Hosted Runners without snap and pulled docker images
- Medium size image: ~500MB, includes only necessary tools to bootstrap actions and aims to be compatible with most actions
- Micro size image: <200MB, contains only NodeJS required to bootstrap actions, doesn't work with all actions
Default image and other options can be changed manually in ~/.actrc (please refer to https://github.com/nektos/act#configuration for additional information about file structure) Micro
[Build Ghost and test theme/install] 🚀 Start image=node:16-buster-slim
INFO[0305] Parallel tasks (0) below minimum, setting to 1
[Build Ghost and test theme/install] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true
Error: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
You’re seeing the Cannot connect to the Docker daemon
error in the above code. This issue occurs due to the Docker daemon. In simple words, the Docker daemon is not running. You can resolve this issue by starting your Docker and re-running your act
command.
There are two ways to run Docker services.
- Open Docker desktop in your window, and your Docker service is started.
- Run Docker with the
systemctl start docker
command on Linux.
You can verify whether your Docker is running or not with the following command:
$ systemctl status docker
● docker.service - Docker Application Container Engine
Loaded: loaded (/etc/systemd/system/docker.service; enabled; preset: enabled)
Drop-In: /nix/store/fibzdkfv6in4xw39rm0c7bq4nadzisas-system-units/docker.service.d
└─overrides.conf
Active: active (running) since Mon 2024-02-26 12:38:37 IST; 3h 39min ago
TriggeredBy: ● docker.socket
Docs: https://docs.docker.com
Main PID: 1186 (dockerd)
IP: 0B in, 0B out
IO: 109.0M read, 152.0K written
Tasks: 40
Memory: 148.5M
CPU: 1min 40.817s
CGroup: /system.slice/docker.service
├─1186 /nix/store/7pzis8dkhs461kl1bg2fp0202dw6r5i5-moby-24.0.5/libexec/docker/dockerd --config-file=/nix/store/3rlv5f0zldcc120b01szywidl0qz9x4p-daemon.json
└─1256 containerd --config /var/run/docker/containerd/containerd.toml
Feb 26 12:38:37 nixos dockerd[1256]: time="2024-02-26T12:38:37.532987858+05:30" level=info msg="containerd successfully booted in 0.016901s"
Feb 26 12:38:37 nixos dockerd[1186]: time="2024-02-26T12:38:37.562515048+05:30" level=info msg="[graphdriver] using prior storage driver: overlay2"
Feb 26 12:38:37 nixos dockerd[1186]: time="2024-02-26T12:38:37.564062690+05:30" level=info msg="Loading containers: start."
Feb 26 12:38:37 nixos dockerd[1186]: time="2024-02-26T12:38:37.778478313+05:30" level=info msg="Default bridge (docker0) is assigned with an IP address 172.17.0.0/16. Daemon option --bip can be used to set a preferred IP address"
Feb 26 12:38:37 nixos dockerd[1186]: time="2024-02-26T12:38:37.805931545+05:30" level=info msg="Loading containers: done."
Feb 26 12:38:37 nixos dockerd[1186]: time="2024-02-26T12:38:37.828589904+05:30" level=info msg="Docker daemon" commit=v24.0.5 graphdriver=overlay2 version=24.0.5
Feb 26 12:38:37 nixos dockerd[1186]: time="2024-02-26T12:38:37.828929197+05:30" level=info msg="Daemon has completed initialization"
Feb 26 12:38:37 nixos systemd[1]: Started Docker Application Container Engine.
Feb 26 12:38:37 nixos dockerd[1186]: time="2024-02-26T12:38:37.841992729+05:30" level=info msg="API listen on /run/docker.sock"
Feb 26 12:38:37 nixos dockerd[1186]: time="2024-02-26T12:38:37.841993669+05:30" level=info msg="API listen on /run/docker.sock"
act
CLI has many options, but we’ll look at some important ones. You can check all the options by running the act --help
command.
act
CLI Options
Here are some act
CLI options:
Events
act
CLI’s default action is the push action, which triggers only push events by default.
$ act
act
CLI with default push event.You can change the event after passing the second argument, which is the name of your action. In our case, we’ll pass pull_request.
$ act pull_request
There is a long list available to trigger workflows. You can read it on the GitHub action documentation.
Lists
The list option prints all the available jobs that you write in .github/workflows
.
$ act -l
.github/workflows
folder.The command output in the terminal looks like this.
$ act -l
Stage Job ID Job name Workflow name Workflow file Events
0 zip zip Convert files into Zip build-project.yml release
0 request_test request_test Pull Request fork.yml fork
0 pull_request_test pull_request_test Pull Request issues.yml issues
0 show show Convert files into Zip folder test.yml pull_request
Running Specific Jobs
You use the --job
option command to run specific jobs from your workflows.
Make sure your job name is unique – otherwise, it runs all jobs containing the same in your workflow. Whenever you can not pass an event by default, trigger the push event.
Syntax
act --job <name-of-your-job>
For example, we run a specific show job.
$ act --job 'show'
Graph
The graph option draws the available workflow jobs structure in your terminal as a graph.
$ act --graph
The command output in the terminal looks like this:
$ act --graph
╭─────╮ ╭──────────────╮ ╭───────────────────╮ ╭──────╮
│ zip │ │ request_test │ │ pull_request_test │ │ show │
╰─────╯ ╰──────────────╯ ╰───────────────────╯ ╰──────╯
Environment Variables
Using environment variables with the act
CLI is easy. You only need to create a new .env
file. act
CLI automatically loads the environment that is available in the .env
file. For example, we add a ENV_ID
variables.
# .env
ENV_ID='My Env'
To use the ENV_ID
environment variables, use the following syntax ${{ env.ENV_ID }}
in your GitHub action:
# .github/workflows/test.yml
name: Convert files into Zip folder
on: pull_request
jobs:
show:
runs-on: ubuntu-latest
steps:
- name: Show Env
run: echo "Env ${{ env.ENV_ID }}"
With the --env-file
option, you can change the default .env
file name to my-custom.env
file.
$ act --env-file=my-custom.env
Secrets
You must create a new .secrets
file to load the environment secrets with the act
CLI. This automatically loads the environment secrets that are available in the secrets
file. For example, we add a APP_SECRET
and APP_ID
variables.
APP_SECRET='7824jurd789gyu45esxgfgf48822166974gtredsyujn'
APP_ID='7878974561587'
.secrets
fileTo use the APP_SECRET
environment variables, use the following syntax ${{ secrets.APP_SECRE}}
in your GitHub action:
# .github/workflows/test.yml
name: Learn environment secrets
on: pull_request
jobs:
show:
runs-on: ubuntu-latest
steps:
- name: Show env
run: echo "App SECRET ${{ secrets.APP_SECRET }}"
- name: Show varibale
run: echo "App ID ${{ secrets.APP_ID }}"
You can load your custom my-custom.secrets
file containing all your secrets with the --secret-file
option.
$ act --secret-file=my-custom.secrets
Conclusion
act
CLI helps save time and energy when working and testing GitHub locally. Currently, there is no alternative to act
CLI, which allows us to run GitHub actions locally.
act
CLI isn’t fully compatible with GitHub actions. Some features are not implemented, for example, concurrency, no vars
context, incomplete github
context, and so on.
You can hire me as a freelance developer with Upwork and other updates. Follow me on Twitter (X) and Medium.
[ad_2]
Source link