How to use the command 'act' (with examples)

Act is a powerful command-line tool designed to execute GitHub Actions locally using Docker. This utility allows developers to run their continuous integration and delivery pipelines without pushing commits to the GitHub repository, thereby reducing the need for unnecessary cloud computations and providing a suitable environment for testing workflows before they are deployed remotely. The tool is primarily useful for debugging and rapid iteration of the GitHub Actions workflows across various environments.

Use case 1: List the available jobs

Code:

act -l

Motivation:

When working with GitHub Actions, a workflow may contain multiple jobs that perform different tasks as part of the continuous integration process. Developers need a quick way to view these jobs to understand the workflow structure better or when they need to execute a specific job for testing or debugging purposes. Listing the jobs helps in gaining insight into what tasks the workflow automates and ensures clarity about each job’s role.

Explanation:

• act is the base command for executing GitHub Actions locally.
• -l is the argument that lists all the available jobs within the workflow file. This option aids users in identifying all the defined jobs, which might otherwise be difficult to trace in a complex workflow configuration.

Example Output:

- job_id: test
  job_name: Unit Tests
  job_status: success

- job_id: build
  job_name: Build Project
  job_status: pending

Use case 2: Run the default event

Code:

act

Motivation:

Running the default event is crucial when a user wants to test how a workflow behaves upon a typical GitHub event trigger, like a push or pull request, without specifying any event type. It helps verify the general execution flow and ensures that the automated processes run as intended in usual scenarios.

Explanation:

• The command act without any additional arguments runs the default event specified in the workflow configuration. This is useful to quickly verify that the workflow executes smoothly in a typical setting with preset configurations.

Example Output:

[Push] 🚀  Start image=cimg/node:14.16.0
[Push]   ✅  Success - Main workflow

Use case 3: Run a specific event

Code:

act event_type

Motivation:

Workflows in GitHub Actions are often configured to respond to multiple distinct events, such as pushes, pull requests, or schedule triggers. Running a specific event allows a developer to verify how changes within the workflow affect actions triggered by that particular event. This specificity is essential in testing customized event configurations or conditional steps within the workflow.

Explanation:

• event_type represents a placeholder for the actual event name you want to run. For example, push, pull_request, or schedule.
• By specifying the event_type, this command focuses the execution on simulations triggered by specific events, providing a more targeted validation method for workflows.

Example Output:

[Pull Request] 🏃  Running build job <matrix>
[Pull Request]   ✅  Success - Build completed

Use case 4: Run a specific job

Code:

act -j job_id

Motivation:

Executing a specific job is immensely beneficial when a developer is debugging or iteratively working on a part of the workflow. By focusing solely on a particular job, a developer can quickly identify the root cause of issues, if any, without executing the entire workflow. This approach is time-efficient and resource-friendly.

Explanation:

• -j stands for job execution.
• job_id must be replaced by the actual identifier of the job you wish to execute. This option narrows down the workflow operation to a single job, aiding in focused testing and debugging.

Example Output:

[Build] 🏗️  Building Project...
[Build]   ✅  Success - Build complete

Use case 5: Do not actually run the actions (i.e., a dry run)

Code:

act -n

Motivation:

A dry run is essential for understanding what steps and jobs will execute in a workflow without actually invoking the process. It is primarily used for getting a high-level overview of the workflow without consuming any Docker resources. Developers might use this option to verify what changes would trigger and ensure that no unintended actions will execute before formal testing.

Explanation:

• -n stands for a dry run.
• Using -n simulates the execution of the workflow pipeline, providing expected logs and outputs without starting any containers or running any jobs.

Example Output:

[Dry Run] ⏳  Workflow 'build' will activate
[Dry Run] 🔍  Steps include: setup, install, test, deploy

Use case 6: Show verbose logs

Code:

act -v

Motivation:

Verbose logging becomes crucial when developers need in-depth details about each action that occurs within a job. This is particularly useful during debugging, where minute details in the process can unveil the cause of unexpected workflow behavior. Comprehensive logs help developers better trace the execution path and gather insights into any issues that arise.

Explanation:

• -v means verbose output.
• Verbose logging increases the verbosity of the command output, providing detailed information, including step-by-step execution, environment variables, and any debug output produced by the actions.

Example Output:

Step: Checkout code
  ⤷ Using ref: master
  ⤷ Previous status: success

Step: Install dependencies
  ⤷ Command: npm install
  ⤷ Output:
     ├─> installed 200 packages
     └─> success: 105 vulnerabilities fixed

Use case 7: Run a specific Workflow with the push event

Code:

act push -W path/to/workflow

Motivation:

Running a specific workflow file for a push event is paramount when dealing with projects that have multiple workflow configurations located in separate files. This capability allows the developer to test precisely the desired workflow context related to code modifications, avoiding unwanted interference or unnecessary action from other workflows.

Explanation:

• push indicates the type of event that triggers the workflow.
• -W allows specifying a particular workflow file path.
• path/to/workflow should be replaced by the actual path to the workflow YAML file. This ensures that only the specified workflow executes, regardless of commits or other workflow files present.

Example Output:

[Push] ▶️ Starting workflow /workflow/folder/workflow.yml
[Push]   ✅ Finished - Deploy step completed

Conclusion:

Using act to run GitHub Actions workflows locally offers significant benefits in terms of efficiency and development cycle acceleration by allowing for comprehensive local testing and debugging. Whether you’re listing jobs, executing specific jobs or events, performing dry runs, or examining verbose output, act streamlines workflow management and ensures robust code deployment readiness.