Test GitHub Actions locally
2024-01-01 | ๐ 765 words | โฑ 8 mins | ๐งพ History | โ NHS Notify | ๐ NHS Notify
Known Issues / Todo
- โ This page is draft and is subject to rapid change, and may not be fully accurate or complete
Guide: Test GitHub Actions locally
Overview
A GitHub workflow job can be run locally for the purpose of testing. The nektos/act project is an open-source tool that allows you to do so. The project aims to make it easier for developers to test and debug their GitHub Actions workflows before pushing changes to their repositories. By using act, you can avoid the potential delays and resource limitations associated with running workflows directly on GitHub. The tool provides a command-line interface and uses Docker containers to emulate the GitHub Actions runner environment. This enables you to execute the entire workflow or individual jobs and steps just as they would run on GitHub.
Key files
- init.mk: Provides the
runner-act
make target - .tool-versions: Defines the version of the
actions/actions-runner
Docker image
Prerequisites
The following command-line tools are expected to be installed:
Testing
Here is an example on how to run a GitHub workflow job:
$ make runner-act workflow="stage-1-commit" job="create-lines-of-code-report"
[Commit stage/Count lines of code] ๐ Start image=ghcr.io/nhs-england-tools/github-runner-image:20230101-abcdef0-rt
[Commit stage/Count lines of code] ๐ณ docker pull image=ghcr.io/nhs-england-tools/github-runner-image:20230101-abcdef0-rt platform=linux/amd64 username= forcePull=false
[Commit stage/Count lines of code] ๐ณ docker create image=ghcr.io/nhs-england-tools/github-runner-image:20230101-abcdef0-rt platform=linux/amd64 entrypoint=["tail" "-f" "/dev/null"] cmd=[]
[Commit stage/Count lines of code] ๐ณ docker run image=ghcr.io/nhs-england-tools/github-runner-image:20230101-abcdef0-rt platform=linux/amd64 entrypoint=["tail" "-f" "/dev/null"] cmd=[]
[Commit stage/Count lines of code] โญ Run Main Checkout code
[Commit stage/Count lines of code] โ
Success - Main Checkout code
[Commit stage/Count lines of code] โญ Run Main Count lines of code
[Commit stage/Count lines of code] โญ Run Main Create CLOC report
[Commit stage/Count lines of code] ๐ณ docker exec cmd=[bash --noprofile --norc -e -o pipefail /var/run/act/workflow/1-composite-0.sh] user= workdir=
[Commit stage/Count lines of code] โ
Success - Main Create CLOC report
[Commit stage/Count lines of code] โญ Run Main Compress CLOC report
[Commit stage/Count lines of code] ๐ณ docker exec cmd=[bash --noprofile --norc -e -o pipefail /var/run/act/workflow/1-composite-1.sh] user= workdir=
| updating: lines-of-code-report.json (deflated 68%)
[Commit stage/Count lines of code] โ
Success - Main Compress CLOC report
[Commit stage/Count lines of code] โ git clone 'https://github.com/actions/upload-artifact' # ref=v3
[Commit stage/Count lines of code] โญ Run Main Check prerequisites for sending the report
[Commit stage/Count lines of code] ๐ณ docker exec cmd=[bash --noprofile --norc -e -o pipefail /var/run/act/workflow/1-composite-check.sh] user= workdir=
[Commit stage/Count lines of code] โ
Success - Main Check prerequisites for sending the report
[Commit stage/Count lines of code] โ ::set-output:: secrets_exist=false
[Commit stage/Count lines of code] โ git clone 'https://github.com/aws-actions/configure-aws-credentials' # ref=v2
[Commit stage/Count lines of code] โ
Success - Main Count lines of code
[Commit stage/Count lines of code] โ ::set-output:: secrets_exist=false
[Commit stage/Count lines of code] โญ Run Post Count lines of code
[Commit stage/Count lines of code] โ
Success - Post Count lines of code
[Commit stage/Count lines of code] ๐ Job succeeded
FAQ
-
Can
act
be used to run Git hooks?The
act
project is a powerful tool that can run a 3rd-party GitHub Actions. You might think about using it to perform the same tasks you have set up in your CI/CD pipeline. However, it is not designed to run or replace Git hooks, like the ones managed by thepre-commit
framework. Whatact
does is mimic the actions that happen on GitHub after you push a commit or make some other change that kicks off a GitHub Actions workflow. This usually involves more rigorous tasks like building your software, running a set of tests or even deploying your code. Utilising it for any other purpose could introduce unnecessary complexity and reduce the reliability of both the development process and the software itself. It is best used only for testing locally jobs and workflows.