# actions/checkout fetch-depth: stop cloning history

actions/checkout fetches one commit by default. When fetch-depth: 0 is worth it, and how shallow, blobless and sparse checkouts, LFS and a mirror cut the rest.

By Grant Unwin, published 2026-10-28. Checked against GitHub's documentation, git's documentation and the actions/checkout source on 2026-11-17. The web page: https://www.runners.io/blog/actions-checkout-fetch-depth-sparse-checkout

`actions/checkout` fetches one commit by default: the one that triggered the workflow. `fetch-depth: 0` changes that to all history for all branches and tags, which is the right setting for a few jobs and a waste for most. To cut what a checkout downloads, keep the default depth, ask only for the history a step reads, and use `filter` or `sparse-checkout` when the repository is large. Large files tracked with Git LFS are a separate download that you opt into. Every input is in our [actions/checkout](https://www.runners.io/blog/actions-checkout-every-input-v4-to-v7) guide.

**In short**

- actions/checkout fetches one commit by default; fetch-depth: 0 fetches all history for all branches and tags.
- Tags alone do not make git describe work on a shallow clone: it needs the commits between the tag and yours.
- filter: blob:none keeps the history and defers file contents until git needs them.
- sparse-checkout writes only the directories you name, and fetches with blob:none unless you set a filter.
- lfs: true downloads large files on every job, counted against the repository owner's LFS bandwidth.
- runners-io/checkout keeps a mirror on a sticky disk, and runs the plain action for sparse-checkout, filter and lfs.

This guide goes through each lever with the YAML, and says what the action’s source and git’s and GitHub’s own documentation promise for it. The pages were read on the date this post was last checked, and where I ran git myself, on 16 November 2026 with git 2.54.0 against the public `actions/checkout` repository, I say so.

## What the default fetches, and what it leaves out

With no inputs the action fetches one commit for the ref or SHA that triggered the run, and no tags. `fetch-tags` is `false`, `lfs` is `false`, `submodules` is `false`, and the working tree is complete: every file at that commit is written out. The action’s source passes `--no-tags` to every `git fetch` and fetches tags explicitly only when you ask. That default is a good one. It is the smallest fetch that still gives a step a whole working tree, and the README states it plainly: only a single commit is fetched by default, for the ref or SHA that triggered the workflow.

```yaml
name: ci
on:
  pull_request:

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v7
      - run: make test
```

Pin `actions/checkout` to a full commit SHA in a real repository, with the version in a trailing comment. The [security hardening checklist](https://www.runners.io/blog/github-actions-security-hardening) says why, and two checkout defaults that changed recently are near the end of this guide.

## What fetch-depth: 0 costs

With `fetch-depth: 0` the action’s source fetches every branch and every tag, not only the history behind your commit. A shallow clone, in the words of git’s own documentation, truncates the history to a number of commits; depth zero removes the truncation and widens the fetch to `refs/heads/*` and the tags. What that costs grows with your repository’s history: more commits, more trees and, unless you filter them, the file contents that go with them. A small repository will not notice. A repository with a long history and large binaries will, on every job, because a job starts on a fresh machine that has nothing from the last run.

So the question is not “is full history faster” but “does a step read history”. Many jobs that were copied with `fetch-depth: 0` do not.

## When a job really needs history

Four things need more than one commit. The first is `git describe`, and anything built on it. Git’s documentation says it finds the most recent tag that is reachable from a commit, and adds the number of commits since. On a one-commit clone there is nothing to walk back through. I ran it against a depth-1 clone of `actions/checkout` and it stopped with `fatal: No names found, cannot describe anything.` I then fetched every tag at depth 1 and it still stopped, with `fatal: No tags can describe`, because the tag’s commit was not in the clone. After `git fetch --unshallow` it printed `v6.0.3-22-gf548e57`. So `fetch-tags: true` on its own does not fix a version script; the history between the tag and your commit has to be there.

The second is a version or changelog tool. A changelog built from `git log <last-tag>..HEAD` asks for the commits reachable from `HEAD` but not from the tag, which is exactly how git’s revision documentation defines that range, and git can only answer it if both the tag and those commits are present. The third is `git merge-base` and any diff against a base branch: GitHub’s own explainer on shallow clones says commands such as `git merge-base` or `git log` can show different results than they would in a full clone. The fourth is `git blame` and file history, which the same article says a shallow clone cannot give you.

For those jobs, set the depth to zero and no more:

```yaml
name: release
on:
  push:
    tags: ['v*']

permissions:
  contents: read

jobs:
  version:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - run: git describe --tags
```

If only one step reads history, fetch it in that step instead of in the checkout. `git fetch` can deepen a shallow clone by a number of commits (`--deepen`), back to a date (`--shallow-since`), or all the way (`--unshallow`), all documented on git’s `git-fetch` page:

```yaml
      - uses: actions/checkout@v7
      - name: Fetch history only for the release notes
        run: git fetch --shallow-since="2026-01-01" origin "${GITHUB_REF}"
```

The date is an example; use the date of your last release. I ran `git fetch --shallow-since` against a depth-1 clone of `actions/checkout`, and the clone went from one commit to 28 and stayed shallow.

And for the very common “which files did this pull request change” question, you do not need history at all. On a pull request the action checks out GitHub’s merge commit. I fetched the merge ref of an open pull request on `actions/checkout` at depth 2 and the commit had two parents, the first the base branch’s tip and the second the pull request’s head, so a depth of 2 gives you the base to diff against:

```yaml
name: changed-files
on:
  pull_request:

permissions:
  contents: read

jobs:
  changed:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 2
      - name: List the files this pull request changes
        run: git diff --name-only HEAD^1 HEAD
```

That relies on how GitHub builds the merge commit, and the order of its parents is something I observed rather than something GitHub documents, so test it on your own pull requests, including one that is out of date with its base. The README’s own example for reaching a parent, `fetch-depth: 2` followed by `git checkout HEAD^`, uses the same depth.

## Partial clones: keep the history, defer the contents

When a job needs history but not every historical file, a partial clone is the tool. Git’s clone documentation describes `--filter` as asking the server for a subset of reachable objects, and `--filter=blob:none` as filtering out all blobs, the file contents, until git needs them. `actions/checkout` exposes it as `filter`, which it passes to `git fetch` as `--filter=`. The commits and trees arrive, so `git log`, `git describe` and `git merge-base` work, and the contents of files arrive when git needs them, which for a checkout is the files at your commit.

```yaml
name: ci
on:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
          filter: blob:none
      - run: git describe --tags
```

I checked the combination with git itself, in the same sequence the action runs. A blobless fetch of every branch and tag from `actions/checkout`, then a checkout of `main`, gave a repository that was not shallow, had the full history and wrote out the working tree, and `git describe` printed `v6.0.3-22-gf548e57`. A `tree:0` fetch behaved the same.

Which filter? GitHub’s engineering explainer says blobless clones, `blob:none`, are best for developers and build environments that span multiple builds, and treeless clones, `tree:0`, for build environments where the repository is deleted after a single build. A job on a fresh machine is the second case, but the same article warns that later commands that need a missing tree cost more, that submodules in a treeless clone ask for trees for every new commit, and that the server can deny your filter and fall back to a full clone. It dates from December 2020, so measure on your own repository before choosing, and start with `blob:none`, which has fewer surprises.

## Sparse checkout: write only the directories a job needs

A monorepo job that builds one package does not need the other forty in its working tree. `sparse-checkout` takes directories, one per line. It uses cone mode by default (`sparse-checkout-cone-mode: true`), and git’s documentation describes cone mode as the default, where you list directories: everything below a listed directory is included, and so are the files immediately under its parent directories, the top-level directory among them.

```yaml
name: api
on:
  pull_request:
    paths:
      - 'libs/api/**'
      - 'libs/shared/**'

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v7
        with:
          sparse-checkout: |
            libs/api
            libs/shared
      - run: make -C libs/api test
```

Three details are in the action’s source rather than the README. First, a sparse checkout implies a partial clone: if you set `sparse-checkout` and no `filter`, the action fetches with `blob:none`, so you save on the download as well as on the disk. Second, if you do set a `filter`, that filter replaces the implied `blob:none`, and the sparse checkout is still applied. Third, the action needs git 2.28 or later for a sparse checkout and refuses an older git with an error naming that version.

Two cautions. The README’s single-file example sets `sparse-checkout-cone-mode: false`, but git’s own documentation says non-cone mode is deprecated, so prefer a directory. And top-level files always come along in cone mode: I ran `git sparse-checkout set src` on a sparse clone and the root files stayed, so a sparse checkout shrinks directories, not the root.

## Large files: what LFS adds

Git LFS keeps large files out of the repository: GitHub’s documentation says the repository holds a pointer file, and the file itself is stored somewhere else. That is why a plain checkout stays small, and why the default `lfs: false` leaves you with pointer files rather than the files. Set `lfs: true` and the action installs LFS and, as its source explains, runs an explicit `git lfs fetch` so the objects download in parallel, except for a sparse checkout, where it lets the checkout fetch only the objects it needs.

```yaml
      - uses: actions/checkout@v7
        with:
          lfs: true
```

Two consequences follow. A fresh machine downloads the LFS objects on every job, and GitHub’s billing page says a download is counted in the repository owner’s bandwidth usage, with the example of GitHub Actions downloading a 500 MB file and using 500 MB. So give `lfs: true` only to jobs that open those files, and give the lint job the default. If a job needs one directory of LFS files, combine `lfs: true` with `sparse-checkout`.

## A mirror on our runners: runners-io/checkout

If your jobs run on our runners, there is one more option. Our [checkout cache documentation](https://www.runners.io/docs/caching/git-checkout-cache) says `runners-io/checkout` is `actions/checkout` with one addition: when the job has a [sticky disk](https://www.runners.io/docs/caching/using-sticky-disks), it keeps a mirror of your repository on it and checks out from there, fetching only what the repository gained since the last job. When the job cannot use the mirror, it runs `actions/checkout` itself, unchanged. Every input of `actions/checkout` is accepted with the same default, and the `ref` and `commit` outputs are the same. Sticky disks have to be turned on for your organisation, because the mirror lives on the repository’s disk. Build times measured on GitHub’s runner and on ours are on our [faster GitHub Actions runners, measured](https://www.runners.io/faster-github-actions) page.

```yaml
jobs:
  build:
    runs-on: runnersio-4vcpu-ubuntu-2404
    steps:
      - uses: runners-io/checkout@v1
        with:
          fetch-depth: 0
      - run: make test
```

What the documentation claims, and no more: it saves the download, so a workflow that fetches the whole history of a large repository saves the most; at the default depth the saving is a couple of seconds on a large repository and close to nothing on a small one. The first build of your default branch on a disk with no mirror yet is slower than a plain checkout, once, because it builds the mirror from your full history; pull requests never do that. At the default depth the workspace is not shallow: it has the repository’s whole history, borrowed from the mirror, so tools that read `git log` or `git describe` see more history than with `actions/checkout`.

Tags are the commonest reason to ask for full history, so it is worth knowing where they are. The action’s public source fetches every branch and every tag into the mirror, and writes those tags into the workspace only when `fetch-depth` is `0` or `fetch-tags` is `true`, so a version step on the mirror still sets one of the two.

The honest limits are in the same document’s table. The job gets plain `actions/checkout`, with the reason on one log line, when it has no sticky disk, comes from a fork’s pull request or runs a tag, sets `repository` to another repository, sets `ssh-key`, `submodules`, `lfs`, `sparse-checkout` or `filter`, or sets `fetch-depth` to anything other than 0 or 1. So the mirror and the levers above are alternatives, not a stack. If your repository’s cost is a long history, `fetch-depth: 0` on the mirror is where the document says the saving is largest. If the cost is a monorepo’s size, `sparse-checkout` is the lever, and the mirror steps aside for it. The step never fails a job because of the mirror: if GitHub cannot be reached or the disk is nearly full, it logs a warning and runs the plain checkout.

On cost, the checkout cache is billed as sticky-disk storage and nothing else. It counts against the same cap and is priced at the same rate as the rest of the disk, which the [GitHub Actions runner pricing](https://www.runners.io/pricing) page has, and there is no separate price. The mirror is deleted with the disk after seven days without a job, and a repository whose mirror is over 20 GiB gets the plain checkout and a warning.

## Two checkout defaults that changed

Two newer defaults sit next to the inputs above. Since v6, `persist-credentials` stores the token in a separate file under `$RUNNER_TEMP` rather than in `.git/config`. And since v7 the action refuses to check out a fork pull request’s code by default when the workflow runs on `pull_request_target` or `workflow_run`; `allow-unsafe-pr-checkout: true` is the opt-in, after reviewing the risks. If a later step does not push, set `persist-credentials: false`.

## Which setting for which job

| The job | Set |
| --- | --- |
| Tests, lint, a build that reads files | The default, fetch-depth: 1 |
| A pull-request step that lists the files it changes | fetch-depth: 2, then git diff --name-only HEAD^1 HEAD |
| Computes a version with git describe, or reads the commits since a tag | fetch-depth: 0, with filter: blob:none if the repository is large |
| Builds one package of a monorepo | sparse-checkout with that package's directories |
| Opens files tracked with Git LFS | lfs: true, on that job only |
| Long history, on our runners, full depth wanted | runners-io/checkout@v1 with fetch-depth: 0 |

Start by deleting `fetch-depth: 0` from every job that does not read history, then run the job and see whether anything fails. Most will not. The [guide to making GitHub Actions faster](https://www.runners.io/blog/how-to-make-github-actions-faster) puts checkout in context with the other levers, and [keeping a build cache between runs](https://www.runners.io/blog/persist-build-cache-between-github-actions-runs) covers the rest of a cold start.

## Sources

- [actions/checkout README at v7.0.1](https://github.com/actions/checkout/blob/v7.0.1/README.md)
- [actions/checkout action.yml at v7.0.1](https://github.com/actions/checkout/blob/v7.0.1/action.yml)
- [actions/checkout git-source-provider.ts at v7.0.1](https://github.com/actions/checkout/blob/v7.0.1/src/git-source-provider.ts)
- [actions/checkout git-command-manager.ts at v7.0.1](https://github.com/actions/checkout/blob/v7.0.1/src/git-command-manager.ts)
- [actions/checkout ref-helper.ts at v7.0.1](https://github.com/actions/checkout/blob/v7.0.1/src/ref-helper.ts)
- [git clone (Git documentation)](https://git-scm.com/docs/git-clone)
- [git fetch (Git documentation)](https://git-scm.com/docs/git-fetch)
- [git describe (Git documentation)](https://git-scm.com/docs/git-describe)
- [gitrevisions (Git documentation)](https://git-scm.com/docs/gitrevisions)
- [git sparse-checkout (Git documentation)](https://git-scm.com/docs/git-sparse-checkout)
- [Get up to speed with partial clone and shallow clone (GitHub Blog, December 2020)](https://github.blog/open-source/git/get-up-to-speed-with-partial-clone-and-shallow-clone/)
- [About Git Large File Storage](https://docs.github.com/en/repositories/working-with-files/managing-large-files/about-git-large-file-storage)
- [Git Large File Storage billing](https://docs.github.com/en/billing/concepts/product-billing/git-lfs)
- [Events that trigger workflows](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows)
- [runners-io/checkout checkout.sh at v1](https://github.com/runners-io/checkout/blob/v1/checkout.sh)
- [The checkout cache](https://www.runners.io/docs/caching/git-checkout-cache)

## Frequently asked questions

### What is the default fetch-depth in actions/checkout?

The default is 1: a single commit, for the ref or SHA that triggered the workflow. Set fetch-depth: 0 to fetch all history for all branches and tags. Tags are not fetched at the default depth unless you set fetch-tags: true.

### Why does git describe fail after actions/checkout?

A depth-1 clone has no tags to walk back to, so git stops with No names found. Fetching tags alone does not help, because the tagged commit is not in the clone. Use fetch-depth: 0, or deepen the history before the step that needs it.

### How do I do a sparse checkout with actions/checkout?

Pass sparse-checkout a list of directories, one per line, and leave cone mode on. Files at the top level always come along. The action needs git 2.28 or later, and fetches with blob:none unless you set a filter of your own.

### Does Git LFS count against my LFS bandwidth in GitHub Actions?

Yes. GitHub's billing page says a download counts towards the repository owner's bandwidth usage, and gives GitHub Actions downloading a large file as its example. Set lfs: true only on the jobs that open those files.
