actions/checkout "ref ... not found" in CI

By Kaveh Alemi·Latchkey

actions/checkout could not resolve the value you gave to its ref input. The branch, tag, or SHA does not exist on the remote as named, so the action fails before any code is available.

What this error means

The checkout step fails early stating the ref cannot be found, for example when ref: is set to a branch that was deleted or a SHA that is not on the remote.

Error: fatal: couldn't find remote ref refs/heads/feature/gone
The process '/usr/bin/git' failed with exit code 128

Common causes

A stale or misspelled ref input

The ref points at a branch or tag that was deleted, renamed, or typed wrong, so the remote has no such ref.

A SHA not reachable on the fetched remote

Passing a commit SHA that was never pushed, or that lives only in a fork, leaves nothing for checkout to resolve.

How to fix it

Verify and correct the ref

1. List remote refs to confirm the branch or tag exists.
2. Fix the ref input to a real, pushed ref or SHA.
3. For PRs from forks, check out the merge/head ref the event provides.

git ls-remote --heads --tags https://github.com/acme/app.git

Pin to an existing ref

Set the checkout ref to a value that exists on the remote.

- uses: actions/checkout@v4
  with:
    ref: ${{ github.sha }}

How to prevent it

• Reference refs that are guaranteed pushed, such as github.sha.
• Avoid hard-coding branch names that may be deleted.
• Confirm cross-repo SHAs exist on the target remote.

Frequently asked questions

Related guides

References

• Git reference manual
• GitHub Actions documentation