GitHub Actions optimizations: 18 best practices guides you can give to your agent to read

Over the last few months we shipped three open-source agent skills that read your GitHub Actions workflows and fix what is wrong with them: ci-speedup for what is slowing CI down, ci-secure for the critical attack vectors, and ci-score for how your configuration grades overall. Every finding those skills report rests on a practice: a specific thing a workflow should do, and a specific reason it should.

Today those practices are all published in one place. The GitHub Actions best practices catalog is 18 reference pages, one per practice, grouped into the six categories the CI Score uses. They're all available in markdown and can be handed directly to a coding agent.

What is on each page

Every practice gets the same shape, built so you can check your own repo against it in two minutes:

• What good looks like. The practice stated plainly, before any YAML.
• A good and bad YAML pair. Side by side, and copyable whole.
• How to verify it on your own repo. The command or the run view that shows you the practice is in place.
• Seen in the wild. Public open-source repositories running the practice today.
• The guardrails. How to keep the fix safe. Scoping a build to changed files keeps a full-run fallback, and moving a check off the critical path is for advisory output, not for the checks that run your tests.
• A copy-paste agent prompt. Hand the page to your coding agent and it applies the practice to your workflows and opens a reviewable PR, grounded in the upstream GitHub docs the page cites.
• A markdown mirror. Every page is also served as plain markdown at the same path plus .md, so an agent or an answer engine reads the content without executing a line of JavaScript.

The catalog

Caching and setup

Stop repeating work between runs.

• GitHub Actions cache: dependencies, keys, and cache hits covers cache: on the setup actions versus actions/cache, and why the key belongs on the lockfile.
• Set actions/checkout fetch-depth: 0 vs 1 vs 2 covers when a job genuinely needs git history and when cloning it is pure cost.

Parallelization

Make the remaining work finish sooner.

• Shard tests across parallel jobs in GitHub Actions splits one long test job across a matrix so wall-clock drops toward total divided by N.
• Build and test only what changed scopes the long-pole monorepo job to the packages a PR touched, with the fallback that keeps a resolution error from silently skipping tests.

Trigger scope

Do not start the run at all.

• Filter workflows with paths and paths-ignore keeps a docs-only change from spinning up the full suite.
• Cancel superseded runs with concurrency and cancel-in-progress covers the concurrency group scoped to the ref, and the cancel-in-progress default that is false when most teams assume otherwise.

Required-check hygiene

• Keep non-required checks off the critical path is about the slow check that gates your merge while producing nothing but a comment, and the line between narrowing it and gutting your test coverage.

Runner and queue

Time your team pays for before and after the useful work.

• Cut CI queue time in GitHub Actions starts with measuring the wait from a run being triggered to its job starting, because the concurrency ceiling on your plan is invisible in the run view.
• Right-size GitHub Actions runners without slowing CI compares the same commit on two runner sizes, because a short orchestration job cannot use extra cores but still pays the higher per-minute rate.
• Bound runner jobs with timeout-minutes is the difference between a hung run cancelled in minutes and one holding a runner for the 360-minute default.
• Replace fixed CI sleeps with bounded readiness polling removes the worst-case sleep from every fast run without turning slow runs flaky.
• Wait for container healthchecks instead of sleeping blocks exactly until each service can answer a real request.

Security

The configuration side of the attack surface.

• GitHub Actions permissions: use least privilege sets a read-only top-level default so unrelated steps stop inheriting repository write access.
• GitHub Actions secrets: prevent leaks and overexposure scopes each secret to the step that consumes it and keeps credentials out of logs, arguments, caches, and artifacts.
• Secure pull_request_target draws the line between metadata work on trusted code and running a contributor's branch with your token in scope.
• Prevent GitHub Actions cache poisoning keeps untrusted code from writing entries your release jobs restore.
• Pin GitHub Actions to commit SHAs replaces the mutable tag that a maintainer, or an attacker, can re-point.
• Scope id-token: write to the publishing job stops an OIDC publish token from being minted for jobs that run untrusted code.

How the guides and the skills fit together

The skills and the guides are the same knowledge at two different moments.

The skills act on your repo. ci-speedup reads your own runs and tells you what is actually costing you wall-clock, which is usually not the thing you assumed. ci-secure checks the ten critical attack vectors an outsider can reach and reports each one as a plain-English attacker scenario. ci-score grades your configuration against pass-or-fail checks and gives you the six-category breakdown these guides are organized by. All three are open source and install in one command from the skills page.

The guides explain the practice, standing alone. That matters in three places: when you are deciding whether to accept a fix an agent proposed, when a teammate asks why the concurrency group is scoped the way it is, and when the practice hardens your configuration. Each skill owns the axis it checks, so ci-secure reports the attack paths an outsider can walk end to end, while pinning actions to commit SHAs and scoping id-token write are graded by ci-score and documented here.

Hand the whole catalog to your agent

The hub carries a master prompt that points an agent at the machine-readable index and every practice page, then walks your workflows against all 18. Paste this into your coding agent:

Audit this repository's GitHub Actions CI against StarSling's best practices catalog at https://starsling.dev/best-practices/github-actions.md, read each per-practice page it links, and fix what is missing. 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.

It works with every coding agent. The pages are public, the markdown mirrors are public, and the fixes land in your repo as PRs you review.

Start here

Read the catalog, or pick the page for whatever is annoying you most this week. If you would rather have the audit run for you, install the skills:

npx skills add starslingdev/skills

Then invoke /ci-speedup, /ci-secure, or /ci-score in your agent. All three are MIT licensed, live on the skills page, and are readable in full in the skills repo.