Lorixen.
EN

CI builds missing tags or versions? Check your shallow clone

Short answer: Many CI systems clone your repository shallowly to save time: GitHub Actions' checkout step fetches only a single commit by default. That's fine for building and testing, but it breaks anything that reads history: version numbers from git describe, changelogs from tags, "changed files since main" checks, and some code-quality tools. Fix it per job by setting fetch-depth: 0 (full history) or fetching just enough history and tags, rather than turning off shallow clones everywhere.

How shallow clones cause strange CI failures

A shallow clone downloads only the most recent commits instead of the full history. Git's clone command supports this with --depth, --shallow-since and related options, and CI providers use it to make checkouts fast.

The GitHub Actions checkout action's documentation states the default plainly: only a single commit is fetched, for the ref or SHA that triggered the workflow. Its fetch-depth input defaults to 1, and setting it to 0 fetches all history for all branches and tags. Other CI services have similar settings with different defaults.

Problems appear when a step assumes history exists:

  • Version numbers. A build script runs git describe --tags to produce "v2.4.1-3-gabc123". With no tags fetched, it fails or returns a bare hash, and the app ships with a wrong or empty version string.
  • Changelogs and release notes generated from commits since the last tag come out empty or enormous.
  • "Only test what changed" steps compare against main. In a single-commit clone, main isn't there, so the diff fails or treats everything as changed.
  • Code-quality and coverage tools that report "new issues since the base branch" can't find the base.
  • Commit message checks for a whole pull request only see the last commit.
  • Blame-based tools see one commit that appears to have written every line.

The confusing part is that these steps work perfectly on developers' machines, where the repository has full history.

Option 1: fetch everything for the jobs that need it

The simplest fix is fetch-depth: 0 on the checkout step of jobs that read history. For most small and medium repositories, the extra time is modest. Leave the default in jobs that only build or test, so they stay fast.

Option 2: fetch just enough

For large repositories, fetch selectively:

  • Tags only: the checkout action has a fetch-tags option, which defaults to false, to fetch tags even with a limited depth. Note that a tag pointing at a commit outside your shallow history may still not help git describe find a path to it.
  • Deepen when needed: git fetch --deepen=50 adds commits from the current shallow boundary. Git's documentation explains that --deepen counts from the boundary rather than from the branch tip.
  • Fetch the base branch: for pull request checks, fetch the target branch explicitly, for example git fetch origin main, with enough depth to find the common ancestor.
  • Unshallow: git fetch --unshallow converts the shallow clone into a complete one, when the source repository is complete.

Option 3: avoid needing history

Some jobs can get the information another way:

  • Pass the version in from your release process, for example from the tag that triggered a release workflow, instead of calculating it from history.
  • Use the CI provider's environment variables for the base and head commits of a pull request.
  • Generate changelogs from merged pull requests through your host's API rather than from local Git history.

Debugging a suspected shallow clone

Add a temporary step that prints:

  • git rev-parse --is-shallow-repository (prints true in a shallow clone).
  • git log --oneline | wc -l (how many commits are present).
  • git tag --list | head (whether tags exist).
  • git branch -a (which branches were fetched).

If the repository is shallow, has one commit and no tags, you've found the cause.

Other CI services and hosts

Each platform names the setting differently. GitLab CI exposes a clone depth variable for pipelines, Bitbucket Pipelines has a clone depth option in its configuration file, and CircleCI and others have their own checkout settings. Some default to shallow clones, some to full ones, and defaults can change between versions. When you move a project from one CI service to another, check the checkout depth before anything else, because it's the most common reason a pipeline that worked for years suddenly produces odd version numbers or empty changelogs.

Tidy habits

  • Set fetch depth deliberately in every workflow that does more than build and test, with a short comment explaining why.
  • Keep version logic in one script that fails loudly when it can't find a tag, rather than quietly producing "0.0.0".
  • Test release workflows on a branch before you need them for a real release.
  • Watch build time after switching to full history in very large repositories, and switch to selective fetching if it grows too much.

A worked example

Picture a hypothetical Hamilton team building a job-quoting app for tradespeople, whose mobile builds suddenly showed "Version 0.0.0" on the settings screen after moving CI to GitHub Actions. Locally, the build script read the latest tag with git describe and worked fine. In CI, the checkout had a single commit and no tags. The team set fetch-depth: 0 for the release build job only, made the version script fail if no tag was found, and left test jobs on the fast default.

FAQ

Why do CI systems use shallow clones by default?

Full history can be slow to download for large repositories, and most build and test jobs don't need it.

Will fetch-depth: 0 slow down every build?

Only the jobs where you set it. For many repositories the extra time is small.

Does a shallow clone affect Git LFS files?

LFS downloads are configured separately. Check your checkout step's LFS setting too.

Can I push from a shallow clone?

Usually yes for simple cases, but some operations involving history may fail. Avoid complex Git work in shallow CI checkouts.

If your CI builds behave differently from local builds, describe what's going wrong and we'll help find the cause.

Sources

WhatsAppBook a call