GitHub Actions Workflows
This directory contains the GitHub Actions workflows for the NOFX project.
๐ Documentation Index
- README.md - This file, overview of all workflows
- PERMISSIONS.md - Detailed permission analysis and security model
- TRIGGERS.md - Comparison of event triggers (pull_request vs pull_request_target vs workflow_run)
- FORK_PR_FLOW.md - Complete analysis of what happens when a fork PR is submitted
- FLOW_DIAGRAM.md - Visual flow diagrams and quick reference
- SECRETS_SCANNING.md - Secrets scanning solutions and TruffleHog setup
๐ Quick Start
Want to understand how fork PRs work? โ Read FLOW_DIAGRAM.md
Need security details? โ Read PERMISSIONS.md
Confused about triggers? โ Read TRIGGERS.md
PR Check Workflows
We use a two-workflow pattern to safely handle PR checks from both internal and fork PRs:
1. pr-checks-run.yml - Execute Checks
Trigger: On pull request (opened, synchronize, reopened)
Permissions: Read-only
Purpose: Executes all PR checks with read-only permissions, making it safe for fork PRs.
What it does:
- โ Checks PR title format (Conventional Commits)
- โ Calculates PR size
- โ Runs backend checks (Go formatting, vet, tests)
- โ Runs frontend checks (linting, type checking, build)
- โ Saves all results as artifacts
Security: Safe for fork PRs because it only has read permissions and cannot access secrets or modify the repository.
2. pr-checks-comment.yml - Post Results
Trigger: When pr-checks-run.yml completes (workflow_run)
Permissions: Write (pull-requests, issues)
Purpose: Posts check results as PR comments, running in the main repository context.
What it does:
- โ
Downloads artifacts from
pr-checks-run.yml - โ Reads check results
- โ Posts a comprehensive comment to the PR
Security: Safe because:
- Runs in the main repository context (not fork context)
- Has write permissions but doesn't execute untrusted code
- Only reads pre-generated results from artifacts
3. pr-checks.yml - Strict Checks
Trigger: On pull request
Permissions: Read + conditional write
Purpose: Runs mandatory checks that must pass before PR can be merged.
What it does:
- โ Validates PR title (blocks merge if invalid)
- โ Auto-labels PR based on size and files changed (non-fork only)
- โ Runs backend tests (Go)
- โ Runs frontend tests (React/TypeScript)
- โ Security scanning (Trivy, Gitleaks)
Security:
- Fork PRs: Only runs read-only operations (tests, security scans)
- Non-fork PRs: Can add labels and comments
- Uses
continue-on-errorfor operations that may fail on forks
Why Two Workflows for PR Checks?
The Problem
When a PR comes from a forked repository:
- GitHub restricts
GITHUB_TOKENpermissions for security - Fork PRs cannot write comments, add labels, or access secrets
- This prevents malicious contributors from:
- Stealing repository secrets
- Modifying workflow files to execute malicious code
- Spamming issues/PRs with automated comments
The Solution
Two-Workflow Pattern:
Fork PR Submitted
โ
[pr-checks-run.yml]
- Runs with read-only permissions
- Executes all checks safely
- Saves results to artifacts
โ
[pr-checks-comment.yml]
- Triggered by workflow_run
- Runs in main repo context (has write permissions)
- Downloads artifacts
- Posts comment with results
This approach:
- โ Allows fork PRs to run checks
- โ Safely posts results as comments
- โ Prevents security vulnerabilities
- โ Follows GitHub's best practices
Can workflow_run Comment on Fork PRs?
Yes! โ The permissions are sufficient.
Key Understanding:
workflow_runexecutes in the base repository context- Fork PRs exist in the base repository (not in the fork)
- The base repository's
GITHUB_TOKENhas write permissions - Therefore,
workflow_runcan comment on fork PRs
Security:
- Fork PR code runs in isolated environment (read-only)
- Comment workflow doesn't execute fork code
- Only reads pre-generated artifact data
For detailed permission analysis, see: PERMISSIONS.md
Workflow Comparison
| Workflow | Fork PRs | Write Access | Blocks Merge | Purpose |
|---|---|---|---|---|
pr-checks-run.yml |
โ Yes | โ No | โ No | Advisory checks |
pr-checks-comment.yml |
โ Yes | โ Yes* | โ No | Post results |
pr-checks.yml |
โ Yes | โ ๏ธ Partial | โ Yes | Mandatory checks |
* Write access only in main repo context, not available to fork PR code
File History
pr-checks-advisory.yml.old- Old advisory workflow that failed on fork PRs (deprecated)- Now replaced by the two-workflow pattern (
pr-checks-run.yml+pr-checks-comment.yml)
Testing the Workflows
Test with a Fork PR
- Fork the repository
- Make changes in your fork
- Create a PR to the main repository
- Observe:
pr-checks-run.ymlruns successfully with read-only accesspr-checks-comment.ymlposts results as a commentpr-checks.ymlruns tests but skips labeling
Test with a Branch PR
- Create a branch in the main repository
- Make changes
- Create a PR
- Observe:
- All workflows run with full permissions
- Labels are added automatically
- Comments are posted