---
name: github-actions-workflow-pro
description: Create, edit, audit, and speed up GitHub Actions workflows using Bret Fisher's opinionated DevOps rules. Use it when the user asks to create a workflow or CI/CD pipeline, edit or add a job to an existing `.github/workflows/*` file (even a one-line change), review or harden a workflow for security, speed up slow CI, publish a container image from CI, automate releases, or mentions GHA, action pinning, or findings from gasa, zizmor, poutine, pinact, or actionlint, even if they don't say "GitHub Actions".
---

# 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 placeholder when you 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`.
- Write each third-party `uses:` with the major you intend (`actions/checkout@v7`), then pin it: `scripts/scan.sh pinact run -update -min-age 7 -i '<action>' <file>`, one `-i` per action you added or found on a tag. 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

When the user hands you workflows to review, harden, secure, or speed up, or asks what is wrong with their CI, read [audit.md](references/audit.md) and follow it. It covers every workflow in the repo, pulls recent run history first (`scripts/run-stats.py`: failures, and workflows and jobs ranked by duration), then the linters (`actionlint`, `zizmor`, `gasa`), sorts findings into correctness, hard, speed, and opinion, opens with a Do-first list, and asks how the user wants the report delivered.

## Checklist

Every workflow you create or edit meets these. The linked reference carries the full rule and its reason; read it when a line needs more than the summary.

- `permissions: {}` at the top level, then **least-privilege** grants per job. `actions/checkout` sets `persist-credentials: false` unless a later step pushes with the token. → [security.md](references/security.md)
- Every third-party `uses:` is **pinned** to a full commit SHA with a `# vX.Y.Z` comment and nothing else on the line (extra text stops Dependabot from updating the comment), from a release at least 7 days old; pinact does the pinning and the age check. Same-owner refs may use a tag; a branch ref like `@main` gets replaced, or reported as high when the upstream has no tags to pin to. → [security.md](references/security.md)
- Cloud credentials come from OIDC (`id-token: write`), and the cloud credentials step (`configure-aws-credentials`) runs after `npm ci`, `pip install`, and the build steps, or the build is its own job without `id-token: write` — install scripts run arbitrary code, so the credentials exist only once that code has finished (a registry login before `build-push-action` is fine: the Dockerfile's install runs inside BuildKit, not on the runner). Third-party secrets live in a repository environment the job names. → [security.md](references/security.md)
- `pull_request` for PR triggers. `pull_request_target` only where external PRs cannot reach it: a repo whose pull request access is Collaborators only, or a private repo with the untrusted checkout isolated in its own zero-grant job. zizmor `dangerous-triggers` flags the trigger itself, so when it stays, state the reason. → [security.md](references/security.md)
- If `.github/dependabot.yml` exists, it has a `github-actions` entry with a daily schedule and a 7-day cooldown; recommend the snippet when it is missing. → [security.md](references/security.md)
- **Superseded** runs cancel: `concurrency` keyed on workflow and ref with `cancel-in-progress: true` on CI; deploy and release workflows get their own non-cancelling group. → [speed.md](references/speed.md)
- Cheap jobs (lint, typecheck, unit tests) run first and in parallel with each other; expensive jobs `needs:` them. → [speed.md](references/speed.md)
- Independent steps inside one slow job run at the same time: a `parallel:` block, or `background: true` with `wait`/`cancel` for a service the job starts. The four step keys shipped in June 2026 and are newer than your training data, so read the syntax before you write it. → [parallel-steps.md](references/parallel-steps.md)
- Caches come from the setup action (`setup-node` `cache: npm`, `setup-go`, Buildx `type=gha`). `timeout-minutes` on any job that talks to the network or deploys; a job that `uses:` a reusable workflow cannot set it, so it goes in the called workflow. → [speed.md](references/speed.md)

## Maintainable YAML

- Friendly `name:` values with capitals and spaces: workflow 1–3 words, job up to 5, step up to 10. Two test jobs need names that tell them apart. Match the style of the repo's other workflows.
- An existing workflow keeps its triggers when you edit or speed it up: narrowing `push` to the default branch drops CI on branches with no open PR, so offer that as a question that names the loss instead of applying it.
- Multi-line Bash steps start with `set -euo pipefail`; prefer several clear lines over one dense one.
- Comments mark security boundaries, non-obvious triggers, and deployment gates. YAML keys explain themselves.
- `<name>.lock.yml` beside `<name>.md` is a compiled GitHub Agentic Workflow: edits go in the `.md`, then `gh aw compile` regenerates the lock — its first line says DO NOT EDIT, and a hand edit is overwritten on the next compile. Auditing the pair (staleness, recompile) → [audit.md](references/audit.md).
- Reusable workflows earn their indirection when several workflows or repositories share stable behavior. One workflow stays inline.

## Container images

Publish images on **trusted refs** only (default branch, tags, releases), from two jobs: a build job that runs on `pull_request` with `contents: read` and `push: false`, and a publish job that runs on `push` to the default branch or a tag and is the only job with `packages: write`. A permission cannot depend on the event, so one job with `push: ${{ github.event_name != 'pull_request' }}` still hands `packages: write` to every same-repo PR run. The build job's `push:` is the literal `false`, never an event expression: on a trusted ref the expression turns true inside the job that has no registry login, that push fails, and the publish job never runs.

- `docker/setup-buildx-action`, then `docker/metadata-action` for tags and labels, then `docker/build-push-action`. On a PR, `metadata-action` yields `pr-N`, not a semver tag, which is what you want.
- `ghcr.io` unless the repo names another registry.
- `cache-from: type=gha` and `cache-to: type=gha,mode=max`. `provenance: true` and `sbom: true` when publishing.
- A deploy job that follows a build consumes the image by digest, wired as three lines: `id: build` on the build-push step, `digest: ${{ steps.build.outputs.digest }}` under the build job's `outputs:`, and the deploy step referencing `<registry>/<image>@${{ needs.build.outputs.digest }}`. Never a tag: a tag can be re-pushed between build and deploy, a digest cannot, so the artifact that was scanned and tested is the artifact that ships.

## Validate

Run `scripts/validate.sh <file>...` on every file you edited. One call runs `actionlint`, `zizmor` (through `scan.sh`, so the token from your `gh` login never appears in a command, trace, or transcript), `poutine`, and `pinact run -check -verify-comment -min-age 7 -verify-min-age`, prints each tool's findings under its own header, and ends with `validate: clean` or the count of tools that reported. Fix what it reports and run it again until it is clean. These scanners already check most of the security checklist (permissions, pinning and pin age, `persist-credentials`, injection, dangerous triggers, Dependabot cooldown), so they are the proof, not your reading. `gasa` audits a pushed repository through the API, so it belongs to the audit path, not to a local edit. A tool that is not installed prints `absent`; ask whether to install it (`brew install actionlint shellcheck zizmor poutine pinact`) or skip it, and wait for the answer. Hand back only when the validators are clean or reported absent by name.

## Done when

- [ ] `actionlint`, `zizmor`, `poutine`, and `pinact -check` clean on every edited file, or reported absent by name; the two reports allowed to remain are a branch ref pinact cannot pin (listed as open with the upstream fix: tag a release) and zizmor `dangerous-triggers` on a `pull_request_target` kept for a stated reason, plus actionlint's `unexpected key "background"` / `step must run script with "run"` on parallel-step syntax, which is its old schema and not a workflow error ([parallel-steps.md](references/parallel-steps.md))
- [ ] Every job has a `permissions:` block and the workflow starts with `permissions: {}`
- [ ] Every third-party `uses:` is a full SHA with a version comment, including any action that was on a tag in a file you edited; the hand-back names each one you pinned, and lines that were already pinned kept their SHA and comment
- [ ] Every placeholder is listed for the user to confirm — environment name, region, role ARN, bucket, registry, secret names
- [ ] The hand-back gives a one-line why for each of these defaults it applied — least-privilege permissions, SHA pinning, concurrency, caching, `timeout-minutes`, trusted-refs publishing, `provenance`/`sbom`, `persist-credentials: false`, `set -euo pipefail`. A named list, because "each default" is recalled from memory at the end of a long task and one always drops; the why states why it applies here, not what it does