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.
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 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 withcancel-in-progress: true, 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
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-06