How do I fix a detached HEAD state?
A detached HEAD state means Git has checked out a commit instead of a branch. Chromatic can still run, but if no branch name is available from CI or an override, it reports the branch as HEAD. The build won’t be associated with your intended branch. Chromatic can still find baselines through Git ancestry, but it won’t use the latest build on your intended branch to account for rebases.
Provide Git context in CI
Ephemeral merge commits or missing branch references can cause this in CI. Provide the Git context with environment variables. You must set all three Git variables.
GitHub
On a pull_request event, actions/checkout checks out a temporary merge commit by default. The Chromatic GitHub Action supplies the pull request’s source commit, branch, and repository automatically. If you run the CLI directly, provide those values using the Git environment variables.
Overriding Git variables changes the build’s Git metadata, not the checked-out code. To test only the source branch’s code, set the checkout step’s ref to github.event.pull_request.head.sha. Checking out a SHA still leaves Git detached, so Chromatic needs the source branch context. See GitHub’s pull request checkout behavior.
Local builds
If you run Chromatic locally while detached, it reports the branch as HEAD unless you provide a branch override. Run git status to check, then use git switch <branch-name> to return to your intended branch before running Chromatic.
If you made commits while detached, preserve them on a new branch with git switch -c <new-branch-name> before switching away.