What is act

act allows developers to run their GitHub Actions workflows locally, providing rapid feedback and streamlining the development process. This tool emulates the GitHub Actions environment, enabling users to test and debug workflows without committing and pushing changes to a remote repository. Unlike directly testing on GitHub, act offers faster iteration cycles and reduces the time spent waiting for CI/CD pipelines. It leverages Docker to execute actions, ensuring consistency with the GitHub environment. Developers benefit from quicker feedback loops, easier debugging, and the ability to manage and run actions directly from their preferred IDE, such as VS Code, through extensions.

act 's Core features

Local Workflow Execution

Enables developers to run GitHub Actions workflows locally, eliminating the need to push changes to a remote repository for testing. This significantly reduces feedback loops, allowing for faster iteration and debugging. It emulates the GitHub Actions environment, ensuring that workflows behave consistently locally as they would on GitHub's servers.

Docker-Based Execution

Leverages Docker to execute actions, ensuring a consistent and isolated environment that mirrors the GitHub Actions runtime. This approach guarantees that dependencies and configurations are managed correctly, preventing discrepancies between local and remote execution. It pulls or builds Docker images defined in your workflow files.

Environment Variable Simulation

Provides a simulated environment that mirrors GitHub's environment variables, including those related to the repository, commit, and runner. This ensures that workflows can access the same information locally as they would on GitHub, facilitating accurate testing and debugging of conditional logic and integrations.

VS Code Integration

Offers integration with Visual Studio Code through a dedicated extension. This integration allows developers to run and test workflows directly from their editor, providing a seamless development experience. It simplifies the process of iterating on workflows and reduces context switching.

Custom Container Engine Support

Allows users to specify a custom container engine, providing flexibility in managing the execution environment. This is particularly useful for users who have specific requirements or prefer to use a different container engine than the default Docker. It supports various container engines through configuration.

GitHub Enterprise Support

Supports GitHub Enterprise, enabling users to run workflows locally for repositories hosted on their private GitHub Enterprise instances. This is crucial for organizations that use GitHub Enterprise for their development and CI/CD pipelines, allowing them to test and debug workflows in a secure and controlled environment.

How to use act

Installation: Install act using your preferred package manager (e.g., brew install act for Homebrew on macOS, or follow the instructions on the website for other platforms).,2. Navigate to your repository: Change your directory to the root of your Git repository containing the .github/workflows directory.,3. Run a workflow: Execute a specific workflow using the command act -W .github/workflows/<your_workflow_file.yml>. Replace <your_workflow_file.yml> with the actual filename of your workflow.,4. Specify a job: Target a specific job within a workflow by adding the job name to the command: act -W .github/workflows/<your_workflow_file.yml> -j <job_name>.,5. View output: Observe the output in your terminal, which simulates the GitHub Actions runner, including logs, environment variables, and any artifacts generated.,6. Customize the environment: Use the -e flag to pass environment variables to the actions, or use the -s flag to provide secrets.

Use cases of act

Workflow Debugging

Software engineers can use act to debug complex workflows locally. They can step through each action, inspect logs, and modify configurations without committing changes. This accelerates the debugging process, reducing the time spent troubleshooting issues in remote CI/CD pipelines.

CI/CD Development

Developers can use act to develop and test new CI/CD workflows before deploying them to production. They can experiment with different configurations, test integrations, and validate the behavior of their workflows locally, ensuring they function correctly before deployment.

Local Testing of Actions

Maintainers of custom GitHub Actions can use act to test their actions locally. They can simulate different inputs, test various scenarios, and ensure their actions behave as expected. This improves the quality and reliability of custom actions before they are published.

Faster Iteration on Workflow Changes

Developers can use act to quickly iterate on changes to their workflow files. Instead of waiting for a full CI/CD run, they can test their changes locally and receive immediate feedback. This significantly speeds up the development process and increases productivity.

Who benefits from act

Software Engineers

Software engineers benefit from act by being able to rapidly test and debug their GitHub Actions workflows locally, reducing the time spent waiting for CI/CD pipelines and improving overall development efficiency.

DevOps Engineers

DevOps engineers can use act to develop and validate CI/CD pipelines locally, ensuring that workflows are configured correctly and function as expected before deploying them to production environments.

CI/CD Specialists

CI/CD specialists can leverage act to test and troubleshoot complex workflows, ensuring that all aspects of the CI/CD process are functioning correctly and efficiently.

Open Source Contributors

Open source contributors can use act to test and contribute to projects that use GitHub Actions. This allows them to quickly validate their changes and ensure compatibility with the project's CI/CD setup.