GitHub Actions

CI has one job: tell the truth about a commit, fast enough that people wait for the answer. A workflow that is green because a step swallowed its exit code is worse than no CI, because now the badge is lying with authority.

The workflow file is source code with production credentials in scope, and its most common triggers are supplied by strangers.

When this fires

A workflow file is being added or changed, CI is slow or intermittently failing, a failure did not turn the run red, or you are reviewing workflow YAML. It does not fire for deciding which stages a pipeline should have at all, or for the content of the tests themselves.

Procedure

1. Read the existing workflows first. Know what already runs on this event, what is already cached, and which checks are required on the protected branch. A second workflow on the same trigger doubles the minutes and halves the clarity about which run is authoritative.
2. State the trigger and the question precisely. Pull request validation, main-branch build, scheduled maintenance, and manual dispatch are different workflows with different privileges. Narrow with branch and path filters so unrelated commits do not queue work nobody reads.
3. Add a concurrency group so superseded pull request runs cancel instead of piling up — keyed by workflow and ref. Do not cancel in progress for deployment or release workflows: an interrupted deploy leaves state nobody planned for.
4. Set permissions explicitly and minimally. Declare read-only at the top level and raise the specific permission on the one job that needs it. Default token permissions vary by repository and organization setting, so a workflow that never mentions permissions has privileges you have not read.
5. Treat pull request content as hostile input. Forked pull requests get no secrets and a read-only token by design — do not engineer around that. The pull_request_target event runs with the base repository's token and secrets: never check out and never execute the pull request's code under it. Adding it to make a fork workflow "work" is how repositories get taken over.
6. Never interpolate event data into a shell step. A pull request title, branch name, or body pasted directly into a run: block is executed by the shell. Pass the value through the step's environment and reference the variable inside the script instead. This applies to any attacker-controlled field, not just the obvious ones.
7. Pin third-party actions to a full commit SHA, with the version in a trailing comment. A tag is mutable and points at whatever the author moves it to. First-party setup actions are the usual exception teams make deliberately — make it deliberately.
8. Cache dependencies keyed on the lockfile, with a looser restore key for partial hits. The language setup actions have dependency caching built in; prefer it over hand-rolling. Never cache anything whose staleness could let a broken commit pass: build output and test results are verification evidence, not cacheable input.
9. Make the matrix express a real support surface, not a product of every axis. Each cell costs a runner and a queue slot. Keep fail-fast on when the first failure is representative; turn it off when you genuinely need to see which cells fail. Add odd one-off combinations through the matrix's include list rather than a second job.
10. Keep failure honest. No continue-on-error and no || true on a step whose result is the point of the job. Set a timeout on every job so a hang fails in minutes rather than burning an hour. The assertion must be the exit code — a check whose failure only appears in log text nobody reads is not a check.
11. Emit evidence from the run. Upload test reports, coverage, logs, and screenshots as artifacts with a condition that also runs on failure — the failing run is precisely the one whose artifacts you need. Write a short summary of what ran and what it proved to the step summary, so the answer is visible without opening raw logs.
12. Handle secrets as references, never values. Use repository or environment secrets and short-lived cloud credentials via OIDC rather than long-lived keys. Log masking is a safety net, not a control: a secret that has been base64'd, split, or JSON-encoded is no longer masked. Do not echo, do not write to an artifact, do not pass into a pull_request_target job.
13. Keep it fast enough to be trusted. Look at the actual job durations, find the long pole, and split or parallelize that one rather than optimizing everything. When pull request feedback takes longer than a coffee, people stop waiting for it and CI stops being a gate.
14. Deployment workflows are a separate concern and a separate authorization. Put them behind a protected environment with required reviewers. Proposing a workflow that ships on merge changes who can deploy and when: describe that consequence and get explicit confirmation before adding it. Do not trigger a deployment workflow to test your YAML.
15. Run it before claiming it works. Push the branch and read the run. A workflow file is written, not working, until a real run on real runners has passed and, ideally, failed for the right reason once.

Checklist

• Trigger, branch and path filters match the question the workflow answers
• Concurrency group set for pull request runs, and deliberately absent for deploys
• permissions declared top level, raised only where needed
• No untrusted event data interpolated into any run: block
• Third-party actions pinned to commit SHAs
• Cache key derives from the lockfile; no verification output is cached
• Every job has a timeout; no step masks its own failure
• Artifacts uploaded on failure, not only on success
• Secrets referenced only; nothing echoed, nothing crossing a fork boundary
• Workflow observed passing in a real run, with durations recorded

Failure handling

• The run is green but the thing is broken. Look for a step that continued on error, a command piped into something that resets the exit status, a job skipped by an if: condition that reads as success, or a required check that does not exist under the name the branch rule expects. A skipped job is not a passed job — confirm from the run which jobs actually executed.
• Fails in CI, passes locally. Compare the environments before touching the test: runner OS and version, tool version resolved by the setup action, a cached dependency tree from an earlier lockfile, absent env vars, and the clean checkout having no untracked files you rely on.
• Intermittent failures. Do not paper over them with a retry. Capture the failing run's artifacts and logs, name the flake, and quarantine it with an owner and a date. A retried test reported as a pass is a false statement about the commit.
• A fork's pull request cannot run the full suite. That is the design, not a bug. Run what the read-only token allows, and say clearly which checks could not run on that pull request.
• No repository access to push and observe a run. Say the workflow is unrun. Reviewing YAML is review, not verification, and the two must not be reported as the same thing.

Evidence to report

The run URL or id, and its conclusion. Which jobs ran, which were skipped, and why. Wall-clock duration per job before and after any change you made for speed. Cache hit or miss for the dependency step. The artifacts produced, by name. For a review with no run: the specific lines you changed or flagged, and an explicit statement that the workflow has not been executed.