Github Actions locally with act

GitHub Actions is a powerful automation platform that allows developers to create and manage CI/CD pipelines (Continuous Integration/Continuous Deployment) directly within their GitHub repositories. While running workflows directly on GitHub offers many advantages, there are situations where it’s beneficial to test and debug these workflows locally. This is where act comes in.

What is act?

act is an open-source tool that enables developers to run GitHub Actions workflows locally on their computers. This provides the advantage of quickly testing changes without needing to commit and push to a remote repository every time. It simulates the GitHub Actions environment using Docker containers.

Installing act

To use act, you need to have Docker installed on your computer. After that, you can install act via Homebrew, npm, or directly from the GitHub release page.

• Homebrew (macOS and Linux):

  1brew install act
  

• npm (Node.js):

  1 npm install -g act
  

• Directly from GitHub: Visit the act release page, download the appropriate version for your operating system, and install it.

Setting Up and Using act

Once act is installed, you can use it in any GitHub repository that contains GitHub Actions workflows. Here are the basic steps:

Navigate to your repository and run a workflow:

1cd /path/to/your/repository
2act

This command looks for a push event in your .github/workflows configuration and runs the corresponding workflow.

Run a specific job or event:

You can also run a specific job or event. For example, to run a pull_request event:

1act pull_request

Or to run a specific job:

1act -j job-name

Or to run a specific workflow:

1act --workflows .github/workflows/my-workflow.yml

Customizing act

You can further customize act to better suit your needs:

Configuration with actrc:

You can create an .actrc file in your home directory or in the root of your repository to configure default options for act.

1# Example .actrc
2-P ubuntu-latest=catthehacker/ubuntu:act-latest

Setting environment variables:

Often, you need to set environment variables that are typically defined in GitHub Secrets or repository settings. This can be done using the -s flag:

1act -s MY_SECRET=mysecretvalue

Using a different Docker image:

By default, act uses a generic Docker image for running workflows. However, you can specify a particular image to simulate an environment closer to your production setup.

1act --platform ubuntu-latest=catthehacker/ubuntu:act-latest

Benefits of Running GitHub Actions Locally with act

• Quick Debugging: You can quickly and easily test changes to your workflows without pushing them to a remote repository each time.

• Offline Usage: You can run workflows without an internet connection.

• Consistency: Ensure that your workflows run consistently across different development environments.

Conclusion

Act is a valuable tool for developers who regularly work with GitHub Actions and want to test and debug their workflows locally. It offers a fast, efficient, and flexible way to enhance the development and maintenance of CI/CD pipelines. By integrating act into your development process, you can ensure that your automation workflows function smoothly and error-free before they transition to the production environment.