GitHub Actions Guide

Critical Rules

Custom Action Deployment:

• New custom actions MUST be merged to the main branch before they can be used
• After the initial merge, they should be tested from feature branches

Debug Steps: Add debug steps that print non-secret parameters when:

• Creating a new action, OR
• Troubleshooting a particularly tricky issue

(Not required for every workflow - use when needed)

Effectiveness Principles

Actions cost CI minutes. Be deliberate, not iterative:

1. Monitor, don't poll - use gh run watch / gh pr checks --watch to follow runs live
2. Read logs, don't guess - fetch the failed job's log before changing code
3. Print actual values - debug steps reveal the real inputs/github context, not your assumptions
4. Test locally first - act runs workflows on your machine and avoids burning CI minutes
5. Plan the smallest reproduction - one job, minimal matrix, narrow trigger before scaling up

See README.md for the full debugging workflow, gh commands, and YAML debug-step examples.

Key Gotchas

1. Secrets unavailable in fork PRs - pull_request has no secrets for forks; pull_request_target does but never check out or execute fork PR code inside it (RCE with write permissions)
2. Pin action versions - Use @v4 or SHA, not @main (prevents breaking changes)
3. Explicit permissions - Set permissions: block for GITHUB_TOKEN operations
4. Artifacts for job-to-job data - Files don't persist between jobs without upload-artifact/download-artifact