nofx/.github/workflows

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-error for 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_TOKEN permissions 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_run executes in the base repository context
• Fork PRs exist in the base repository (not in the fork)
• The base repository's GITHUB_TOKEN has write permissions
• Therefore, workflow_run can 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

1. Fork the repository
2. Make changes in your fork
3. Create a PR to the main repository
4. Observe:
   • pr-checks-run.yml runs successfully with read-only access
   • pr-checks-comment.yml posts results as a comment
   • pr-checks.yml runs tests but skips labeling

Test with a Branch PR

1. Create a branch in the main repository
2. Make changes
3. Create a PR
4. Observe:
   • All workflows run with full permissions
   • Labels are added automatically
   • Comments are posted

References

• GitHub Actions: Keeping your GitHub Actions and workflows secure Part 1
• Safely posting comments from untrusted workflows
• GitHub Actions: workflow_run trigger