GitHub Actions "fatal: detached HEAD" after actions/checkout
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>Diagnose it: print the context before you change anything
Most workflow-expression bugs are not syntax errors, they are an expression reading something that is empty. GitHub resolves a missing property to an empty string instead of failing the run, so a wrong reference looks like a logic bug rather than a mistake. Dump the contexts first and you will usually see the answer immediately.
- name: Dump contexts
run: |
echo '--- github ---' ; echo '${{ toJSON(github) }}'
echo '--- needs ---' ; echo '${{ toJSON(needs) }}'
echo '--- steps ---' ; echo '${{ toJSON(steps) }}'
echo '--- matrix ---' ; echo '${{ toJSON(matrix) }}'
echo '--- inputs ---' ; echo '${{ toJSON(inputs) }}'Check the context is allowed where you used it
Contexts are not available everywhere. The same expression can be valid in a step if and invalid in a job if, which is why an expression that works in one workflow fails when moved.
| Where you wrote it | Contexts available there |
|---|---|
run-name | github, inputs, vars |
concurrency | github, inputs, vars |
Top-level env | github, secrets, inputs, vars |
jobs.<id>.if | github, needs, vars, inputs |
jobs.<id>.steps.if | github, needs, strategy, matrix, job, runner, env, vars, steps, inputs |
jobs.<id>.outputs | Full access, including secrets |
Reusable workflow outputs | github, jobs, vars, inputs |
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
- Pass ref: with the branch name to checkout, or check it out after.
- When pushing, target HEAD:branch explicitly.
- 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 }}Catch it before it reaches CI
Every failure in this cluster is statically detectable. actionlint parses workflow expressions, checks context availability against the same rules above, and validates needs references, so these bugs never need to cost you a run.
# one-off
docker run --rm -v "$(pwd):/repo" --workdir /repo rhysd/actionlint:latest -color
# as a job, before anything expensive runs
- uses: actions/checkout@v4
- run: |
bash <(curl -s https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
./actionlint -colorHow 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.