160-github-actions

GitHub Actions Engineering Gates

This rule owns mandatory GitHub Actions policy only. Use the GitHub Actions skill (${HANDBOOK_ROOT}/skills/cicd-github-actions/SKILL.md) for authoring workflows, reusable patterns, examples, troubleshooting, and migration procedures. Use the GitHub Actions CI/CD skill (${HANDBOOK_ROOT}/skills/cicd-github-actions/SKILL.md) together with the dependency currency workflow (${HANDBOOK_ROOT}/skills/core-engineering/references/dependency-and-toolchain-currency.md) when upgrading actions.

Workflow Documentation

• Use a descriptive Title Case workflow name: and a kebab-case workflow filename.
• Put a bordered operational comment block immediately after name:. Use the headings Purpose, Triggers, Required Secrets, and Dependencies, with blank comment lines between sections. Record approval, rollback, recovery, or runbook requirements under Dependencies.
• Document reusable workflow and action inputs, outputs, secrets, defaults, and side effects where they are declared.
• Give jobs and non-obvious steps descriptive names. Do not add comments that merely restate YAML.
• Never place secret values, sensitive identifiers, or production data in comments, summaries, examples, logs, or artifacts.
• Keep detailed operating procedures in repository documentation and link them from the workflow comment when needed.

Token, Event, and Runner Trust

• Set permissions: {} at workflow root, then grant each job only the capabilities it requires.
• Grant id-token: write only to jobs that perform OpenID Connect (OIDC) authentication.
• Use pull_request on GitHub-hosted runners for untrusted pull-request validation. Do not combine pull_request_target, privileged permissions, secrets, deployment capability, or privileged self-hosted runners with execution of untrusted code.
• Treat issue text, pull-request metadata, commit messages, branch and tag names, dispatch inputs, matrix values, and third-party action outputs as untrusted.
• Do not interpolate untrusted expressions directly into run: scripts. Assign them to step-level env, quote the shell variable, and validate constrained values before use.
• Secrets cannot be referenced directly in if: conditions. Map a secret to a narrowly scoped job environment variable, then test the env context at step scope.
• Use protected GitHub Environments for production authorization. Configure required reviewers and deployment-branch restrictions outside workflow code.
• Prefer OIDC and short-lived cloud credentials. Do not add long-lived cloud keys when federation is available.
• Treat self-hosted runners as privileged infrastructure. Isolate runner groups by trust boundary, prefer ephemeral single-job runners, restrict workflow access, and do not run untrusted fork code on runners with internal access.