How to Run GitHub Actions Locally on Windows

Background

This stems from an attempt to see if CI tests executed on GitHub could be run locally for optimization.
While many articles appear when searching online, I'm writing this partly as a reminder for myself.

Environment

OS: Windows 11

Required Tools

Install a container runtime (such as Docker Desktop) beforehand.

Commands to Use

act

act is formally known as nektos/act and is published on GitHub at the following repository:
nektos/act
According to the README, it is precisely a tool for running GitHub Actions locally.

Installation Method

There are various ways to install act, such as via Arch, Chocolatey, or Scoop.
Since Winget was available by default on my PC, I used that.
The installation command is:
winget install nektos.act
Once installed, verify it by running:
act --version
During installation, you may see a message in English: "Path environment variable modified; restart your shell to use the new value." This is a message telling you to restart your shell because the environment variables were changed, so be sure to follow it.

How to Run GitHub Actions

To run GitHub Actions, move to the folder containing the .github folder where the workflows are defined.
cd folder-containing-.github-folder
Once moved, execute the act command:
act
If there are errors in the workflow description, a message like the following will be displayed. It's also helpful to be able to see which line contains the error.

Error: workflow is not valid. '～～.yml': Line: 142 Column 5: Failed to match job-factory: Line: 190 Column 9: Unknown Variable Access matrix
Line: 142 Column 5: Failed to match workflow-job: Line: 143 Column 5: Unknown Property runs-on
Line: 190 Column 9: Unknown Variable Access matrix
Line: 191 Column 5: Unknown Property steps

If it runs successfully, a completion log like this will be output:
Job succeeded
If it fails at some point in the job, the following will be output:
Job Failure
If the workflow is long, it can be difficult to find where it failed, so I recommend outputting the standard output to a log file.

A Few Things I Ran Into

• An error "mvn command not found" occurred during installation using the mvn command.
  → This can be resolved by modifying the Docker image (for work-related tasks, you will need to escalate to check if modifications are permitted).
• Be careful when running act while containers are already active; if the workflow itself involves starting containers, it may fail due to conflicts.