Running GitHub Actions Workflows Locally with act CLI

To Nha Notes | Aug. 13, 2024, 6:25 p.m.

GitHub Actions is a powerful tool for automating your software development workflows. It allows you to define custom workflows in YAML files that execute various tasks, such as building, testing, and deploying your code. However, testing these workflows before pushing them to your repository can be challenging. That’s where the act CLI comes in handy.

What is act?

The act CLI is an open-source tool that simulates GitHub Actions locally. It allows you to run your workflows on your local machine, providing a faster feedback loop during development. Here’s how to get started:

Prerequisites

Before you begin, make sure you have the following installed:

1. Docker: The act CLI relies on Docker to create isolated environments for running your workflows. Install Docker from here.

2. act CLI:

   • On Windows: Use Chocolatey with choco install act-cli.
   • On macOS: Install via Homebrew with brew install act.
   • On Linux: Run the following command:

     curl -s "https://raw.githubusercontent.com/nektos/act/master/install.sh" | sudo bash
     

Using act

1. Navigate to Your Project Directory: Open a terminal and navigate to the root directory of your GitHub repository.

2. Run act:

   • Simply run act without any arguments to execute the workflows triggered by a GitHub push event.
   • Act will use the chosen Docker image to simulate GitHub Actions locally.

3. Choose a Docker Image:

   • When you run act for the first time, it will prompt you to choose a Docker image size:
     • Micro: A lightweight image (around 200 MB) suitable for small projects.
     • Medium: A larger image (around 500 MB) for more complex workflows.

4. Iterate and Test:

   • Make changes to your workflows or configuration files.
   • Run act again to test the updated workflows locally.
   • Iterate until you’re satisfied with the results.

Benefits of Using act

• Faster Feedback: Test your workflows without committing and pushing code to the repository.
• Isolated Environments: act creates Docker containers for each job, ensuring isolation.
• Debugging: Easily debug issues by inspecting the local workflow runs.

Useful Act CLI commands

The act CLI provides several useful commands for working with GitHub Actions locally. Here are some key ones:

1. List All Actions: To view all available actions defined in your .github/workflows directory, run:

   act -l
   

2. Run a Specific Action: To run a specific action (e.g., the build action), use:

   act build
   

3. Run Specific Jobs: You can execute a specific job from your workflows using the --job option:

   act --job my-job-name

Conclusion

The act CLI is a valuable tool for GitHub Actions development. By running workflows locally, you can catch errors early and streamline your CI/CD process. 

References

https://overcast.blog/run-the-github-actions-workflow-locally-a-complete-guide-8592e3169d48