GitHub Actions CI best practices
Practical, copyable ways to make your GitHub Actions CI faster, leaner, and cheaper: caching, sharding, scoped build and test, path filters, concurrency, and queue time, plus the security practices (SHA pinning, per-job OIDC) that keep a fast pipeline safe. One reference page each, with good and bad YAML and how to verify it on your own repo.
Trying to make GitHub Actions faster?
If you do not know why a run is slow yet, start with the diagnostic guide. If your workflows are already optimized but still slow, see our guide to fast GitHub Actions and GitHub Actions runner alternatives. Building containers in CI? The Docker workflow guide covers layer caching end to end.
Caching & Setup
Cache dependencies in GitHub Actions
Cache your package manager's downloads so CI restores dependencies from a keyed cache instead of reinstalling them from scratch on every run.
Use a shallow checkout with fetch-depth in GitHub Actions
Let
actions/checkoutfetch only the commit under test (its defaultfetch-depth: 1) instead of the whole git history, and reach forfetch-depth: 0only when a job genuinely needs history.
Parallelization
Shard tests across parallel jobs in GitHub Actions
Split one long test job into parallel shards with a matrix so the suite finishes in a fraction of the wall-clock time.
Build and test only what changed in GitHub Actions
Scope your slowest build/test job to only the packages a PR actually changed, using your monorepo tool's affected mode, with a mandatory full-run fallback so a resolution error never silently skips work.
Trigger Scope
Filter workflows by path in GitHub Actions
Add
pathsorpaths-ignoreto expensive workflows so a docs-only or unrelated change doesn't trigger the full test suite.Cancel superseded runs with concurrency groups
Add a GitHub Actions
concurrencygroup scoped to the ref and turn oncancel-in-progressfor PR runs (it defaults tofalse), so a new push cancels the now-obsolete run instead of leaving both to occupy runners.
Required-check Hygiene
Runner & Queue
Security
Pin GitHub Actions to commit SHAs
Reference every third-party action by its full 40-character commit SHA (with the version as a trailing comment), not a mutable
@v4tag or@mainbranch that its maintainer, or an attacker, can re-point.Scope id-token: write to the publishing job
In GitHub Actions, declare
id-token: writein the specific publishing job'spermissions:block, never at the workflow's top level, so an OIDC publish token isn't minted for jobs that run untrusted code.
Hand your whole CI to an agent
Paste this into your coding agent (Claude Code, Cursor, and the like) to audit your repo against every practice above and open a reviewable PR for each gap.
Audit this repository's GitHub Actions CI against StarSling's best-practices catalog and fix what's missing. Start by reading the machine-readable index at https://starsling.dev/best-practices/github-actions.md, then read each per-practice page it links (at https://starsling.dev/best-practices/github-actions/{slug}.md) so you have the full guidance for every practice. Go through this repo's .github/workflows and check them against each practice: dependency caching, shallow checkout, test sharding, building and testing only what changed, path filters, cancelling superseded runs with concurrency groups, keeping advisory checks off the critical path, queue time, pinning actions to commit SHAs, and scoping id-token write to the publishing job. For every gap, apply the fix following that practice's page and respect its guardrails (for example, keep a full-run fallback when scoping to changed files, and never de-scope a check that runs real tests). Show me the diff and open a PR for each change rather than applying anything blindly, and skip any practice that genuinely does not apply to this repo, noting why.FAQ
How do I optimize GitHub Actions?
Work the pipeline in the order the time is actually spent. First cut the wait before a job starts: scope each concurrency group to ${{ github.ref }} so unrelated PRs don't serialize, and cancel superseded PR runs with cancel-in-progress. Then stop doing work you don't need: paths filters (or a job-level if: when the check is required) keep a docs-only change from spinning up the suite, actions/checkout runs at its default fetch-depth: 1 instead of cloning the whole history, and in a monorepo the long-pole job builds and tests only what the diff affected (with a full-run fallback). Then make the remaining work faster: cache the dependency store keyed on the lockfile (cache: on actions/setup-node / setup-python / setup-go, or actions/cache keyed on hashFiles(...)), and shard the slowest test job across a matrix so wall-clock drops toward total/N. Finally, keep it safe: pin every action to a full-length commit SHA and grant id-token: write only to the job that publishes. Each practice below has its own page with the good and bad YAML side by side.
What are the most important GitHub Actions CI best practices?
The highest-impact ones are caching dependencies so installs don't repeat every run, sharding long test suites across parallel jobs, scoping expensive workflows with path filters, cancelling superseded runs with a concurrency group, and hardening security by pinning actions to commit SHAs. Each has its own page here with copyable YAML.
How is this catalog organized?
Practices are grouped into the six categories the StarSling CI Score uses: Caching & Setup, Parallelization, Trigger Scope, Required-check Hygiene, Runner & Queue, and Security. Every page shows what good looks like, a good/bad YAML pair, and how to verify the practice on your own repo.
Do I have to use StarSling to apply these?
No. Every practice is a change you can make to your own GitHub Actions workflows by hand, and each page includes the verify steps to check it. StarSling's agents automate the same fixes by opening reviewable PRs, but the practices stand on their own.
References
Every practice on this page, enforced in your repo.
One line to install. Faster runs on day one, and agents that open reviewable PRs to keep your GitHub Actions pipeline following these practices.
Last updated 2026-07-15