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

The ‘act’ command is a tool that allows you to execute GitHub Actions locally using Docker. It provides a way to test and validate your workflows before pushing them to GitHub. With ‘act’, you can run specific events, actions, or workflows, and even perform a dry run to see what actions would be executed without actually running them.

Use case 1: List the available actions

Code:

act -l

Motivation: Listing the available actions can be helpful to see all the possible actions that can be executed in your GitHub Actions workflows. It allows you to quickly view the available options without having to go through the workflow files.

Explanation: The ‘-l’ flag is used to list all the available actions.

Example output:

Available actions:
- build
- test
- deploy

Use case 2: Run the default event

Code:

act

Motivation: Running the default event allows you to test the execution of your workflows based on the triggers defined in the workflow files. It helps to ensure that the workflow behaves as expected when triggered by certain events.

Explanation: Running ‘act’ without any additional arguments will execute the default event defined in your workflow files. The default event is usually triggered by a push event in most workflows.

Example output:

✔  (main) Push event
[INFO] Pulling nektos/act-environments-ubuntu:18.04 image (sha256:abcdef1234567890)
...

Use case 3: Run a specific event

Code:

act event_type

Motivation: Running a specific event enables you to simulate the execution of your workflows under different event scenarios. It allows you to test how your workflows respond to specific events, such as pull requests or scheduled events.

Explanation: To run a specific event, you need to provide the event type as an argument to the ‘act’ command. You can find the available event types in the workflow file. For example, if you have a workflow that triggers on a pull request event, you can simulate that event by running act pull_request.

Example output:

✔  (main) Pull request event
[INFO] Pulling nektos/act-environments-ubuntu:18.04 image (sha256:abcdef1234567890)
...

Use case 4: Run a specific action

Code:

act -a action_id

Motivation: Running a specific action allows you to focus on testing and validating a particular action in your workflow without executing the entire workflow. This is useful when you want to isolate and debug a specific action to ensure its correctness.

Explanation: The ‘-a’ flag is used to specify the ID of the action you want to run. The action ID can be found in your workflow files. Running act -a build will only execute the ‘build’ action in the workflow.

Example output:

✔  (main) Run build
[INFO] Pulling nektos/act-environments-ubuntu:18.04 image (sha256:abcdef1234567890)
...

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

Code:

act -n

Motivation: Performing a dry run allows you to see what actions would be executed in your workflow without actually running them. This is helpful when you want to verify and validate the actions that will be performed before executing them.

Explanation: The ‘-n’ flag is used to perform a dry run. It prints the actions that would be executed without actually running them.

Example output:

[DRYRUN] (main) Run build
[DRYRUN] (main) Run test
[DRYRUN] (main) Run deploy

Use case 6: Show verbose logs

Code:

act -v

Motivation: Showing verbose logs can be useful when you want to see more detailed information about the execution of your workflows. It provides additional insights into the steps and actions being performed, helping with troubleshooting and debugging.

Explanation: The ‘-v’ flag is used to show verbose logs. It prints out more detailed information about each step and action being executed.

Example output:

==> (main) Run build
[INFO] Pulling nektos/act-environments-ubuntu:18.04 image (sha256:abcdef1234567890)
...

Use case 7: Run a specific Workflow

Code:

act push -W path/to/workflow

Motivation: Running a specific workflow allows you to focus on testing and validating a particular workflow file without executing the other workflows in your repository. It provides a way to verify the correctness and behavior of a specific workflow in isolation.

Explanation: To run a specific workflow, you need to provide the name of the workflow as an argument to the ‘act’ command, followed by the ‘-W’ flag and the path to the workflow file.

Example output:

✔  (push) Run Workflow path/to/workflow
[INFO] Pulling nektos/act-environments-ubuntu:18.04 image (sha256:abcdef1234567890)
...

Conclusion:

The ‘act’ command is a powerful tool for testing and validating GitHub Actions workflows locally. It allows you to run specific events, actions, and workflows, providing a way to verify and validate the behavior of your workflows before pushing them to GitHub. The ability to perform dry runs, show verbose logs, and run specific workflows makes ‘act’ a valuable tool in your GitHub Actions development and debugging process.