# GitHub Actions: fatal: couldn't find remote ref refs/heads/feature — The process '/usr/bin/git' failed with exit code 1 (actions/checkout)

**Code:** `couldn't find remote ref (checkout)` · **Category:** CI/CD · **Seen on:** GitHub Actions, Git

`actions/checkout` could not fetch the branch, tag or SHA it was asked for — it was deleted, never pushed, or is not reachable with the default shallow fetch.

## Meaning

Checkout fetches a single commit (`fetch-depth: 1`) of the triggering ref. Asking for another ref, a tag, or history (for `git describe`, changelogs, diffs) fails unless you widen the fetch. Deleted branches and PRs from forks also yield this error.

## Common causes

- Branch deleted or renamed before the job ran
- `ref:` input misspelled
- Tags or full history needed but fetch-depth is 1
- Fork PR ref not available with the given repository input
- Private repository requires a token with access

## Quick fix

1. Check that `ref:` exists on the remote
2. Use `fetch-depth: 0` (and `fetch-tags: true`) when you need history or tags
3. Pass `repository:` and `token:` for other repositories

## Detailed fix by platform

### GitHub Actions

1. Verify the ref: `git ls-remote origin refs/heads/feature`

## Code examples

### Full history

```yaml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0
    fetch-tags: true
```

## How to diagnose

1. **Ref** — Does it exist remotely?
2. **Depth** — History needed?
3. **Repo** — Same repository or another?

---
Source: [WhatIsMyError](https://whatismyerror.com/errors/cicd/gha-checkout-shallow-ref-not-found)