# Git "fatal: couldn't find remote ref" in CI

> Fix Git "fatal: couldn't find remote ref" in CI - checking out a branch, tag, or SHA that does not exist on the remote, was deleted, or was never fetched.

Source: https://latchkey.dev/learn/git/git-fatal-couldnt-find-remote-ref  
Updated: 2026-06-25

Git asked the remote for a specific ref and the remote does not have it. The branch or tag name is wrong, was deleted, or the ref simply was never created on the remote you are pointing at.

## Diagnose it: depth, refs, or credentials?

CI checkouts are shallow and detached by default, which breaks anything that needs history or a branch name. Before treating it as a credential problem, confirm what the runner actually fetched.

```.github/workflows/ci.yml
- run: |
    git rev-parse --is-shallow-repository
    git rev-parse --abbrev-ref HEAD      # prints HEAD when detached
    git log --oneline -3
    git remote -v
    git for-each-ref --format="%(refname)" | head
```

> `actions/checkout` fetches depth 1 and leaves you on a detached HEAD. Anything diffing against a base ref, reading the branch name, or running `git describe` needs `fetch-depth: 0` and usually an explicit ref.

## The checkout options that fix most of this

```.github/workflows/ci.yml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0        # full history: diffs, tags, git describe
    submodules: recursive # submodules are NOT fetched by default
    persist-credentials: false  # if a later step pushes with its own token
```

## FAQ

### What causes Git "fatal: couldn't find remote ref" in CI?

There are 3 common causes: the branch or tag name is wrong or deleted, the default branch was renamed, and tags were never fetched. A typo (relase vs release), a branch that was merged and deleted, or a tag that was never pushed all mean the remote has no such ref to return.

### How do I fix Git "fatal: couldn't find remote ref" in CI?

There are 2 fixes depending on which cause you have: list what the remote actually has and reference the correct ref. Work through them in order, since the first is the most common.

### What does Git "fatal: couldn't find remote ref" in CI actually mean?

A fetch or checkout of a named ref fails with fatal: couldn't find remote ref <ref>.

### How do I stop Git "fatal: couldn't find remote ref" in CI happening again?

Derive the default branch dynamically instead of hard-coding main/master. The prevention section lists 3 changes that keep it from recurring.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt