--- title: "GitHub Actions optimizations: 18 best practices guides you can give to your agent to read" description: "Eighteen free GitHub Actions best practices guides with copyable YAML, verify steps, and markdown mirrors your coding agent can read and apply to your repo." date: 2026-08-19 url: https://starsling.dev/blog/github-actions-optimizations-18-best-practices-guides-you-can-give-to-your-agent-to-read canonicalUrl: https://starsling.dev/blog/github-actions-optimizations-18-best-practices-guides-you-can-give-to-your-agent-to-read --- # GitHub Actions optimizations: 18 best practices guides you can give to your agent to read
[Image: 18 best practices guides: GitHub Actions optimizations you can give to your coding agent]
Over the last few months we shipped three [open-source](https://github.com/starslingdev/skills) agent skills that read your GitHub Actions workflows and fix what is wrong with them: [ci-speedup](/ci-speedup) for what is slowing CI down, [ci-secure](/ci-secure) for the critical attack vectors, and [ci-score](/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](/best-practices/github-actions) 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](/best-practices/github-actions/cache-dependencies) 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](/best-practices/github-actions/shallow-checkout) 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](/best-practices/github-actions/shard-tests) splits one long test job across a matrix so wall-clock drops toward total divided by N. - [Build and test only what changed](/best-practices/github-actions/build-only-affected) 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](/best-practices/github-actions/path-filter-workflows) keeps a docs-only change from spinning up the full suite. - [Cancel superseded runs with concurrency and cancel-in-progress](/best-practices/github-actions/cancel-superseded-runs) 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](/best-practices/github-actions/keep-advisory-checks-non-blocking) 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](/best-practices/github-actions/cut-queue-time) 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](/best-practices/github-actions/right-size-runners) 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](/best-practices/github-actions/bound-job-timeouts) 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](/best-practices/github-actions/replace-fixed-sleeps-with-polling) removes the worst-case sleep from every fast run without turning slow runs flaky. - [Wait for container healthchecks instead of sleeping](/best-practices/github-actions/wait-for-container-healthchecks) blocks exactly until each service can answer a real request. ### Security The configuration side of the attack surface. - [GitHub Actions permissions: use least privilege](/best-practices/github-actions/limit-github-actions-permissions) sets a read-only top-level default so unrelated steps stop inheriting repository write access. - [GitHub Actions secrets: prevent leaks and overexposure](/best-practices/github-actions/protect-github-actions-secrets) scopes each secret to the step that consumes it and keeps credentials out of logs, arguments, caches, and artifacts. - [Secure pull_request_target](/best-practices/github-actions/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](/best-practices/github-actions/prevent-github-actions-cache-poisoning) keeps untrusted code from writing entries your release jobs restore. - [Pin GitHub Actions to commit SHAs](/best-practices/github-actions/pin-action-shas) replaces the mutable tag that a maintainer, or an attacker, can re-point. - [Scope id-token: write to the publishing job](/best-practices/github-actions/scope-id-token-per-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](/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](/ci-secure) checks the ten critical attack vectors an outsider can reach and reports each one as a plain-English attacker scenario. [ci-score](/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](/skills). 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](/best-practices/github-actions/pin-action-shas) and [scoping id-token write](/best-practices/github-actions/scope-id-token-per-job) 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: ```text 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](/best-practices/github-actions), 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: ```bash 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](/skills), and are readable in full in [the skills repo](https://github.com/starslingdev/skills).