GitHub Actions Workflow Rules

Apply these defaults proactively to every workflow you touch, unless the repository has a clear conflicting convention or the user asks for a different tradeoff. The rules exist because a workflow runs arbitrary code with a token: security is built in from the first line, and speed is what keeps a workflow maintained.

Working Style

1. Inspect existing workflow files before editing so new changes match the repository's naming, trigger, and secret conventions.
2. Prefer the smallest correct change, and fix insecure or wasteful patterns in the code you are already touching.
3. Facts are yours to find (an action's SHA, its required permissions, whether a tool supports OIDC). Decisions are the user's (adding a manual trigger, choosing a registry, creating an environment): put each one to them and wait.
4. Use placeholders for secret names, environment names, package names, and cloud roles the repo does not reveal, and list every one under Placeholders in the hand-back.

Building a workflow

• Infer from the repo: the runtime version from its version file (.nvmrc, .python-version, go.mod) or engines, the lint and test commands from its scripts.
• Reusable workflows are named call-*.yaml or reusable-*.yaml.
• Pin each third-party uses: with pinact, one -i '<action>' per action. An action you add: write @v<major> and run scripts/scan.sh pinact run --update --min-age 7 -i '<action>' <file>, because new code takes the newest release at least 7 days old. An action already on a tag (@v4): run scripts/scan.sh pinact run --min-age 7 -i '<action>' <file> without --update, because --update jumps to the newest major (v4 to v7) and a major bump is the user's decision; name a newer major as a question in the hand-back. The scope matters: a whole-file --update bumps lines that were already pinned, which the user did not ask for. An action already on a tag in a file you are editing gets pinned too, whatever "keep everything else" covers: the tag is the one line an attacker can move, so pin it and name it in the hand-back (see pinned below).
• For a Docker build workflow, or a lint workflow in a repo with no linter of its own, offer a reusable workflow before writing a bespoke one and ask whether the user already has one: Bret's are https://github.com/BretFisher/docker-build-workflow and https://github.com/BretFisher/super-linter-workflow. A repo that already defines npm run lint or equivalent runs that.

Auditing an existing workflow