What Is fetch-depth?

fetch-depth is a CI checkout setting that controls how many commits of history a job downloads, trading speed against access to the past.

fetch-depth is the knob you turn to decide how much Git history a CI job pulls. Set it low and checkouts are fast but history is shallow; set it to fetch everything and you get the full log at the cost of a slower clone. Choosing the right value is a small but real CI optimization.

What fetch-depth controls

fetch-depth maps directly to the clone depth. A depth of 1 fetches only the commit being built. A larger number fetches that many commits of history. By convention, a depth of 0 means fetch the complete history with no truncation at all.

Setting fetch-depth

In a GitHub Actions checkout, fetch-depth is a parameter on the checkout step.

Fetching full history

steps:
  - uses: actions/checkout@v4
    with:
      fetch-depth: 0

When you need more depth

Some jobs require history beyond the latest commit: computing a diff against the base branch, deriving a version from tags, or generating a changelog all walk back through commits. If a tool reports missing history or an unknown revision, increasing fetch-depth is usually the fix.

fetch-depth and CI/CD performance

Because checkout runs on every job, fetch-depth has an outsized effect on total pipeline time for large repositories. The default shallow depth keeps things fast; only raise it for the specific jobs that need history. On managed runners, leaving most jobs shallow keeps the fleet efficient.

Choosing a value

Use depth 1 (the default) for plain build and test jobs.
Use depth 0 for changelog, diff, or version-from-tag steps.
Raise depth only on the jobs that actually need history.
Remember deeper fetches slow down every run that uses them.

Key takeaways

fetch-depth sets how many commits of history a CI job downloads.
Depth 0 means full history; depth 1 fetches just the build commit.
Keep it shallow for speed; deepen only for diffs, tags, or changelogs.