GitHub Actions Best Practices

A CI/CD pipeline runs your code with your tokens, on every push, often with permission to write to the repo and reach your cloud. That makes Actions hygiene a security posture, not a tidiness preference: the same workflow that ships your release is the one an attacker most wants to compromise. The disciplines here keep that pipeline both secure and fast.

This page consolidates the Actions concepts from earlier chapters into the configuration you actually commit to .github/workflows. The unifying idea is least privilege and least trust — pin what runs, scope what it can touch, and prefer short-lived identity over stored keys.

Pinning Third-Party Actions

Pin every third-party action to a full commit SHA, not a mutable tag like @v4. A tag is a pointer the action's maintainer (or an attacker who compromises the repo) can move, and when they do, that code runs in your pipeline with your tokens. The 2025 tj-actions compromise did exactly this: a hijacked tag exfiltrated secrets across thousands of consumers who had pinned to a tag. A SHA is immutable, so what you reviewed is what runs.

Least-Privilege GITHUB_TOKEN

The default GITHUB_TOKEN is over-scoped for most jobs. Set permissions: {} at the top of the workflow and grant each job only what it needs — usually contents: read. Without this, a single compromised step or malicious dependency can push to the repo, move tags, or publish a release using a token you handed it by default.

Caching That Actually Hits

Key caches on the hash of your dependency lockfile, with sensible restore-keys for partial fallbacks. A cache keyed on a constant never invalidates, so it serves stale dependencies that poison builds; one keyed too finely (on a timestamp or commit SHA) never hits, so every run pays full install cost. The lockfile hash is the key that changes exactly when dependencies change.

Reusable Workflows and Composite Actions

Extract shared pipeline logic into workflow_call reusable workflows and composite actions so thirty repositories do not each maintain a divergent copy of the deploy job. When the logic lives in one place, a fix is one edit; when it is copy-pasted, a fix is thirty edits that drift the moment one is missed.

Secrets and OIDC

Never echo secrets into logs, and prefer OIDC for cloud authentication over storing long-lived keys. Scope deploy secrets to protected Environments so they require approval, and remember that pull requests from forks cannot read secrets by design — a deliberate guardrail you should not work around. OIDC mints a short-lived token per run, scoped to the repository and environment, so there is no standing credential to leak.

Concurrency and Cost Control

Use a concurrency group to cancel superseded runs so five pushes in a minute do not run five full pipelines, add path filters so a docs change does not trigger the full test matrix, and set timeout-minutes so a hung job fails in minutes instead of burning an hour of runner time. These keep the pipeline fast and the bill predictable.