ER: How to Test GitHub Actions Documentation - nektos/act Emulation #8706

Emergent Requirement - Problem

Currently, developers rely heavily on trial-and-error by pushing commits to GitHub to see if workflow orchestration succeeds, or they struggle with permission errors when trying to test workflows on their personal forks. While standard CLI tools (gh api) are great for testing simple logic, nektos/act is required for simulating full event payloads and YAML orchestration locally via Docker. Creating this document will standardize the local testing environment for power-users, prevent credential leaks, and significantly speed up the development cycle for automation features.

Issue you discovered this emergent requirement in

#8584

Date discovered

06/23/2026

Did you have to do something temporarily

• YES
• NO

Who was involved

I've discussed with @daras-cu and she agreed it would be helpful.

Potential Solution:

I can create an additional document to supplement the existing 'How to Test GitHub Actions' series that is available in the Google Drive, to provide a testing track for developers who need to test or modify complex, event-driven GitHub Actions workflows (such as move-closed-issues) locally before pushing changes or reviewing pull requests.

(Note: I just went through this exact setup process successfully to test PR #8696 and would like to take the lead on writing this guide!)

Details

The guide will provide a step-by-step walkthrough for configuring act locally, specifically addressing the unique hurdles of our repository. It will be broken down into universal testing steps and OS-specific setup:

Universal Emulation Steps (Mac, Windows, Linux):

• Mocking GitHub Context: Explaining why event-driven workflows crash locally without payload data, and providing the exact curl/jq commands to fetch live issue data and format it into an event.json payload.
• Secure Authentication & Context Spoofing:
  • Setting up a .secrets file with a Personal Access Token (PAT) for GraphQL API queries.
  • Overriding the GITHUB_REPOSITORY environment variable during execution so act queries the main hackforla/website repository instead of a personal fork.
• Git Remote Configuration: (Optional but recommended) Ensuring developers have their Git remotes configured for SSH to streamline the testing and pushing pipeline.

Linux/WSL Specific Setup:

• Installation & Compilation Hurdles: How to bypass outdated apt packages to install modern Go (1.21+) and compile act from source (this serves as a crucial troubleshooting fallback for developers when standard package managers fail).

Resources

Hack for LA Google Drive:
\HackforLA.org website\HackforLA.org website folder\3 - Developers\GitHub Actions (GHA)\1. How to test GitHub Actions.gdoc
1. How to Test GitHub Actions - using nektos/act

\HackforLA.org website\HackforLA.org website folder\3 - Developers\GitHub Actions (GHA)\2. Additional Notes for GitHub Actions.docx
2. Additional Notes for GitHub Actions

External Resources:
nektos/act Official Repository
GitHub API: Fetching an Issue
jq Manual (for JSON parsing)