GitHub Actions "fatal: detached HEAD" after actions/checkout

By Daniel Zoghalchali·Latchkey

By default actions/checkout checks out the exact commit that triggered the run, leaving HEAD detached. Commands that assume a current branch (push to HEAD, git symbolic-ref) then fail.

What this error means

A step that tries to commit/push or read the current branch fails because the repo is in detached-HEAD state, with "fatal: detached HEAD" or a push that has no upstream branch.

fatal: You are not currently on a branch.
To push the history leading to the current (detached HEAD) state now, use git push origin HEAD:<name-of-remote-branch>

Common causes

Default checkout detaches HEAD

checkout fetches and checks out the triggering SHA directly, so HEAD points at a commit rather than a branch ref.

Pushing without naming a branch

git push from detached HEAD has no current branch to map to a remote branch.

How to fix it

Check out a branch or push to an explicit ref

1. Pass ref: with the branch name to checkout, or check it out after.
2. When pushing, target HEAD:branch explicitly.
3. Set fetch-depth: 0 if you also need full history.

- uses: actions/checkout@v4
  with:
    ref: ${{ github.head_ref || github.ref_name }}
- run: git push origin HEAD:${{ github.ref_name }}

How to prevent it

• Decide explicitly whether you need a branch checkout vs a SHA.
• Push to HEAD:<branch> when on detached HEAD.
• Document that checkout detaches by default.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions