--- title: "Fetch only the repository history a job needs" description: "Limit checkout depth and fetched refs to the comparisons or release history the job actually consumes." url: https://starsling.dev/ci-playbooks/techniques/fetch-needed-history canonicalUrl: https://starsling.dev/ci-playbooks/techniques/fetch-needed-history --- # Fetch only the repository history a job needs Limit checkout depth and fetched refs to the comparisons or release history the job actually consumes. ## How to choose an approach Compare the examples by repository setup, prerequisites, and risks before adopting one. Each company implemented this in its own environment; measure each change against your own baseline. - **[Linear](https://starsling.dev/ci-playbooks/linear#fetch-only-what-each-job-needs)**: Use it when A job uses only GitHub API metadata or a bounded subset of the repository. Check before adopting: Resolve merge bases, local actions, hashFiles and indirect scripts first. API-only jobs need an explicit repository context; history-dependent checks must retain enough history. - **[Mastra](https://starsling.dev/ci-playbooks/mastra#shallow-checkout)**: Use it when Tests consume a source tree without history-based versioning or change detection. Check before adopting: Test tags and ancestry before giving release automation a shallow checkout. - **[OpenAI](https://starsling.dev/ci-playbooks/openai#shallow-checkout)**: Use it when Checkout steps fetch full history or LFS files that the job never reads. Check before adopting: Jobs that compute versions, changelogs or diffs from Git history still need full history. - **[Stripe](https://starsling.dev/ci-playbooks/stripe#fetch-needed-history)**: Use it when Checkout dominates CI, but lint or affected-target selection needs history. Check before adopting: Change detection needs a verified comparison base. Validate the PR head, the base and the merged tree, and run the full check whenever the base is ambiguous. ## Apply this technique ````text Evaluate and apply this CI technique to my repository: Fetch only the repository history a job needs. Limit checkout depth and fetched refs to the comparisons or release history the job actually consumes. Read the technique and its source-backed company examples: https://starsling.dev/ci-playbooks/techniques/fetch-needed-history.md Inspect this repository’s CI workflows, build and test commands, dependencies, and recent run timings. Identify where this technique applies and explain the expected benefit using this repository’s evidence. Measure a baseline from recent comparable runs: elapsed time, queue time, runner minutes and failures where available. If data is unavailable, say what cannot be measured. Compare relevant company approaches, checking prerequisites, platform differences and tradeoffs. Rank applicable options by evidence, fit and measurable opportunity; do not present company results as predictions for this repo. Recommend the smallest safe change, show what checks and fallback paths remain, and ASK ME WHICH CHANGE TO APPROVE BEFORE EDITING ANY FILES. Only after approval, work on a new feature branch, make one reversible change, and open a reviewable pull request. Never merge or push to a default or protected branch. Keep required checks, test coverage, deployment and release behavior intact. Validate the change and compare equivalent runs where possible; report limitations and what should be monitored after merge. ```` ## How companies used this technique Read what each company changed and follow the original sources. ### Linear: Give each checkout only the files and history it uses Linear capped fetch depth, removed checkout from jobs that never used a working tree, and used sparse, blobless checkouts where it diffs paths. Capping fetch depth took the slowest change-detection gate from 94 to 20 seconds; removing checkout from jobs that never needed a working tree took them from 27 to 7 seconds. Evidence: Company-reported result or observation The median duration of the change-detection job fell from 26 to 8 seconds, p90 from 31 to 12 seconds, and the slowest run from 138 to 37 seconds. ([Source](https://linear.app/now/ci-bottleneck-reworked#fetch-only-what-each-job-needs)) Use it when: A job uses only GitHub API metadata or a bounded subset of the repository. Before applying it: Resolve merge bases, local actions, hashFiles and indirect scripts first. API-only jobs need an explicit repository context; history-dependent checks must retain enough history. [Read more in the Linear playbook](https://starsling.dev/ci-playbooks/linear#fetch-only-what-each-job-needs) [Primary source](https://linear.app/now/ci-bottleneck-reworked#fetch-only-what-each-job-needs) ### Mastra: Fetch only the release history the job consumes The workspace test workflow removed fetch-depth: 0 while preserving the triggering workflow’s head SHA. Release publishing now fetches only main’s history, deepening it in batches without tags. Evidence: Source PR/commit evidence Release publishing deepens main’s history in batches of 50 commits, without tags. ([Source](https://github.com/mastra-ai/mastra/blob/f92e947a448a47515acf14df1eddc5fd5c36f424/.github/workflows/npm-publish.yml)) Use it when: Tests consume a source tree without history-based versioning or change detection. Before applying it: Test tags and ancestry before giving release automation a shallow checkout. [Read more in the Mastra playbook](https://starsling.dev/ci-playbooks/mastra#shallow-checkout) [Primary source](https://github.com/mastra-ai/mastra/pull/14432) ### OpenAI: Check out only the history the job reads Four lint and test workflows in frontier-evals switched from a full-history checkout to a single commit, and three of them stopped downloading LFS files. Evidence: Source PR/commit evidence Four workflows check out one commit, and the three lint workflows stopped fetching LFS files ([Source](https://github.com/openai/frontier-evals/pull/53)) Use it when: Checkout steps fetch full history or LFS files that the job never reads. Before applying it: Jobs that compute versions, changelogs or diffs from Git history still need full history. [Read more in the OpenAI playbook](https://starsling.dev/ci-playbooks/openai#shallow-checkout) [Primary source](https://github.com/openai/frontier-evals/pull/53) ### Stripe: Fetch the comparison, not every branch Stripe iOS replaced a fetch that could pull every branch with a shallow checkout of the PR head followed by progressively deeper fetches of only the PR and master histories until their merge base resolves. Evidence: Source PR/commit evidence Some jobs had spent up to 30+ minutes fetching history; in Stripe’s combined CI runs with the related changes, lint went from about 7 to about 6 minutes. ([Source](https://github.com/stripe/stripe-ios/pull/7331)) Use it when: Checkout dominates CI, but lint or affected-target selection needs history. Before applying it: Change detection needs a verified comparison base. Validate the PR head, the base and the merged tree, and run the full check whenever the base is ambiguous. [Read more in the Stripe playbook](https://starsling.dev/ci-playbooks/stripe#fetch-needed-history) [Primary source](https://github.com/stripe/stripe-ios/pull/7331) ## CI optimization is continuous work. Apply this technique yourself, or use StarSling Runners for faster GitHub Actions and optional agent-driven optimization PRs, which teams on eligible paid plans can turn on. [Get self-improving CI](https://starsling.dev/products/runners) ## Related techniques ### [Keep full history and download old blobs on demand](https://starsling.dev/ci-playbooks/techniques/blobless-history) Change detection often needs commit history and filenames, not old file contents. 1 implementation · 1 company (Mastra) ### [Serve checkouts from pre-warmed repository clones](https://starsling.dev/ci-playbooks/techniques/git-checkout-service) Keep repository clones warm on a few machines and run Git operations against them, so jobs skip the cold clone. 1 implementation · 1 company (Uber) ### [Bake stable dependencies into runner images](https://starsling.dev/ci-playbooks/techniques/prebuild-runner-images) Prepare versioned system dependencies and build downloads once in the runner image instead of installing them on every job. 2 implementations · 2 companies (Anthropic, Linear) ## Company Playbooks ### [Anthropic](https://starsling.dev/ci-playbooks/anthropic) Run only affected tests ### [DoorDash](https://starsling.dev/ci-playbooks/doordash) Run build and test in parallel, sharded across CI agents ### [Linear](https://starsling.dev/ci-playbooks/linear) Benchmark the same job on faster hardware ### [Mastra](https://starsling.dev/ci-playbooks/mastra) StarSling runners for the slowest test workflow ### [OpenAI](https://starsling.dev/ci-playbooks/openai) Rank CI fixes by the minutes they save ### [Ramp](https://starsling.dev/ci-playbooks/ramp) Move a CPU-bound test suite to a faster CPU ### [Shopify](https://starsling.dev/ci-playbooks/shopify) Let an agent iterate against one CI metric ### [Spotify](https://starsling.dev/ci-playbooks/spotify) Build arm64 on native arm64 runners ### [Stripe](https://starsling.dev/ci-playbooks/stripe) Run only the tests a change can reach ### [Uber](https://starsling.dev/ci-playbooks/uber) Build the merge-queue speculations most likely to be needed ## Related guides Implementation guides for this technique. ### [Filter workflows by changed files](https://starsling.dev/best-practices/github-actions/path-filter-workflows) Use paths and job conditions while keeping required checks reporting. ### [Cancel superseded CI runs](https://starsling.dev/best-practices/github-actions/cancel-superseded-runs) Cancel obsolete PR runs with a correctly scoped concurrency group.