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 guide.
- 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.
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 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:
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:
- 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:
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.
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.
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.
- 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 says runners-io/checkout is actions/checkout with one addition: when the job has a sticky disk, 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 page.
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 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 puts checkout in context with the other levers, and keeping a build cache between runs covers the rest of a cold start.
Sources
- actions/checkout README at v7.0.1 (github.com)
- actions/checkout action.yml at v7.0.1 (github.com)
- actions/checkout git-source-provider.ts at v7.0.1 (github.com)
- actions/checkout git-command-manager.ts at v7.0.1 (github.com)
- actions/checkout ref-helper.ts at v7.0.1 (github.com)
- git clone (Git documentation) (git-scm.com)
- git fetch (Git documentation) (git-scm.com)
- git describe (Git documentation) (git-scm.com)
- gitrevisions (Git documentation) (git-scm.com)
- git sparse-checkout (Git documentation) (git-scm.com)
- Get up to speed with partial clone and shallow clone (GitHub Blog, December 2020) (github.blog)
- About Git Large File Storage (docs.github.com)
- Git Large File Storage billing (docs.github.com)
- Events that trigger workflows (docs.github.com)
- runners-io/checkout checkout.sh at v1 (github.com)
- The checkout cache (/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.