Skip to main content

How to Run GitHub Actions Locally Using the act CLI Tool

Rajdeep SinghMarch 12, 2024About 8 minDevOpsGithubDockerArticle(s)blogfreecodecamp.orgdevopsgithubgithub-actionsdocker

How to Run GitHub Actions Locally Using the act CLI Tool ๊ด€๋ จ

Github > Article(s)
Article(s)
Docker > Article(s)
Article(s)
How to Run GitHub Actions Locally Using the act CLI Tool
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 pro...

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 nektos/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.

How to Install act for GitHub Actions

The nektos/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:

choco install act-cli

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:

  1. The Docker Micro image size is 200 MB, and small projects use it.
  2. The Docker Medium image size is 500 MB, and Big Project uses it.
  3. 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

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/vimtor-action-zip@v1.2/ dst=/var/run/act/actions/vimtor-action-zip@v1.2/
[Build Ghost and test theme/install]   ๐Ÿณ  docker exec cmd=[node /var/run/act/actions/vimtor-action-zip@v1.2/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.

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

  1. Open Docker desktop in your window, and your Docker service is started.
  2. Run Docker with the systemctl start docker command on Linux.

You can verify whether your Docker is running or not with the following command:

How to Use the act CLI Tool

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.

Syntax

act --job <name-of-your-job>

For example, we run a specific show job.

act --job 'show'

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

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.

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 (Official_R_deep) and Medium (officialrajdeepsingh).

How to Run GitHub Actions Locally Using the act CLI Tool
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 pro...
MIT Licensed | Copyright ยฉ 2022-present Chan Hee Lee
Copyright ยฉ 2025 Rajdeep Singh