Run GitHub Actions on Your Local Machine! 🐙 💻
Tags: devops, docker, githubactions, tutorial
Published: 2023-04-05 20:12:00

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 🐳🐙](https://dev.to/ken_mwaura1/automate-docker-image-builds-and-push-to-docker-hub-using-github-actions-32g5)
- [Automate Docker Image Builds and Push to GitHub Registry Using GitHub Actions 🐙](https://dev.to/ken_mwaura1/automate-docker-image-builds-and-push-to-github-registry-using-github-actions-4h20)

## 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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/neo5kiz05sz2gy93dxfc.png)

This is where [act](https://github.com/nektos/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](https://github.com/nektos/act) and [Homebrew](https://formulae.brew.sh/formula/act). You can install it using the following command:

```bash
# For macOS
brew install act
```

```bash
# For Debian based Linux distributions
sudo apt install act
```

```bash
# For Fedora
sudo dnf install act
```

```bash
# For Arch Linux
sudo pacman -Syu act

```

```bash
# For Windows
choco install act
```
Read more about the installation [here](https://nektosact.com/installation/index.html)

![Act-install](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/o59qlkf3yig39zlbx1c3.png)

## Usage 📖

Act is a CLI tool thus you can use it in your terminal. The following command will run your GitHub Actions locally:

```bash
act
```

Example of running a workflow:

![workflow running](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/oieurcfny5g9wy16xl8m.png)

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:

```bash
cd .github/workflows
act -W workflow.yml
```

Example of running a specific workflow file:

![Running specific workflow](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/azniddtqogem1b4pfwa5.png)

For the full list of commands and flags, you can run the following command:

```bash
act --help
```

![Act help options](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/trx9qxrpd5xzhg93myln.png)


![list workflows](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/wabp1d46t7ls0wsl0ush.png)

## 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:

```bash
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:

```bash
act -P ubuntu-latest=nektos/act-environments-ubuntu:22.04
```

Read more about runner images [here](https://github.com/nektos/act#runners)

![Runner images](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6jivkepw4nqtqc43uooa.png)

## 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:

```bash
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:

```bash
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:

```bash
-P ubuntu-latest=nektos/act-environments-ubuntu:22.04
```

Read more about the configuration file [here](https://github.com/nektos/act#configuration)

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

```yaml
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:

```bash
act
```

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


![Hello world](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/lrllsgyq68029pye2tyv.png)

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

```yaml
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:

```bash
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:

![Hello world secrets](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/n9fti2n75hc0gtio3q56.png)

## 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](https://ko-fi.com/kenmwaura1)

![next time](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/toh8lan0cct7ptv4yx8y.gif)



## References

- [act](https://github.com/nektos/act)
- [act-docs](https://nektosact.com/installation/index.html)
- [GitHub Actions](https://developer.github.com/actions/)
- [Docker](https://www.docker.com/)
- [Act Docker images](https://github.com/nektos/act/blob/master/IMAGES.md)