GitHub Actions Shallow Clone Breaks git describe / Diff (fetch-depth)

actions/checkout fetches a shallow clone (depth 1) by default. Tools that need tags or prior commits - git describe, changelog generators, base-branch diffs - fail because the history is not there.

What this error means

git describe reports no tags, a versioning tool sees the wrong version, or a diff against the base branch fails because the merge base is missing from the shallow clone.

fatal: No names found, cannot describe anything.
# or
fatal: Not a valid object name origin/main

Common causes

Default shallow depth of 1

checkout fetches only the latest commit by default, so older commits and tags are absent. Tools that walk history cannot find what they need.

Base branch not fetched

A shallow clone does not include the base branch, so diffs against origin/main fail with an unknown ref.

How to fix it

Fetch full history with fetch-depth: 0

Set fetch-depth: 0 so all commits and tags are available to history-aware tools.

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

Fetch only what you need

1. Use fetch-tags: true if you only need tags, not full history.
2. For base-branch diffs, fetch the base ref explicitly, for example git fetch origin main.
3. Keep depth shallow where history is not required to stay fast.

How to prevent it

• Set fetch-depth: 0 for versioning and changelog jobs.
• Fetch the base branch before diffing in PR workflows.
• Document which jobs need full history so depth stays minimal elsewhere.

Related guides