Run GitHub Actions Locally 🚀

Adil Shehzad
4 min readDec 23, 2022

GitHub Actions is one of my favorite and best so far for the Continuous Integration/Continuous Delivery & Deployment(CI/CD) tool.

In Short, GitHub Actions is a tool for automating tasks in software development workflows, such as building and deploying code, running tests, and publishing packages. It is a cloud-based service that can be used to automate tasks on various platforms and is integrated with the GitHub ecosystem.

In this blog, we will explore how to use GitHub Actions locally. This can help you save on costs by avoiding using a GitHub Actions runner.

Installation of Docker & Act

act depends on docker to run workflows, so we need to install docker first. You can install docker from here, accordingly to the operating system you are currently using.

After installing Docker, now the next step is to install the ACT .Here is the best guide on how to install Act

Running Docker Image

If you are not much similar to Docker and know how to run commands through CLI, then definitely check out this Docker Cheatsheet.

Pull the ubuntu-latest image by using this command

docker pull catthehacker/ubuntu:act-latest

After the image is pulled, now the next step is to set up a scratch project to test the GitHub actions locally. I set up a very basic python project to testify it locally using GitHub Actions. Here is the GitHub Repository.

GitHub automatically provides a GITHUB_TOKEN secret when running workflows inside GitHub.

If your workflow depends on this token, you need to create a personal access token and pass it to act as a secret:

act -s GITHUB_TOKEN="your token"


So we pull the docker image and also learn how to store the GitHub tokens, which we need during the build. Now let's create a simple Hello World GitHub Action and test it

name: Run Hello World
- master
- main
- master
- main
name: Test
runs-on: ubuntu-latest

- name: Test with inputs
run: |
echo "Hello World"

use the command following commands

# to create your first job 

# List all actions for all events:
act -l

# List the actions for a specific event:
act workflow_dispatch -l

# List the actions for a specific job:
act -j test -l

I also checked on GitHub Actions, and it's working as expected

So it's working fine, but when I try to test it on python, it says that the python command is not found, so I troubleshoot the issue and found out that the act runners do not have all the packages which are pre-installed in it, you either need to customize it or you can use the big size act runner packages which have all the pre-installed developer tools. You can check out more information on this page.

To test the python code using GitHub actions locally, I made some changes to the yaml file

runs-on: ubuntu-latest
image: python:3.8.5

so, the act will create a python container and install the pytest and pip install to it. To clone the code to the container, you can either make your GitHub repository public or you can also clone it using the following command

- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install pytest
- name : Cloning GitHub Code
run: |
git clone https://oauth:$
cd pytest-github-actions

For example, git clone

You can store the GitHub Token secret to.env file, the act will automatically be picked up and used inside the container and clone the repository. More information is available here

Finally, now you need to run the following command, to test the python code inside a container :

act -j test built --secret-file .act.secrets -v -P python:3.8.5=nektos/act-environments-ubuntu:18.04

So far, I found this tool very useful, but still there is room for improvement. All commands are available here to get started


This is a very quick guide on how to run GitHub actions locally. You can do more fun with this tool:

GitHub Repo:

Connect with me: