failed to identify reference (tag/branch) for the checked-ou

Error message

failed to identify reference (tag/branch) for the checked-out revision '%s'

What it means

FindGitRef iterates all references in the repo and tries to map the checked-out revision's hash back to a tag or branch name. If neither a tag nor any branch points at that hash, no GITHUB_REF can be synthesized and this error returns. This is expected for a detached HEAD at a commit that no ref points to (e.g. a PR merge-commit sha checked out by a bot, or a commit whose branch was deleted).

Source

Thrown at pkg/common/git/git.go:160

			return storer.ErrStop
		}

		return nil
	})

	if err != nil {
		return "", err
	}

	// order matters here see above comment.
	if refTag != "" {
		return refTag, nil
	}
	if refBranch != "" {
		return refBranch, nil
	}

	return "", fmt.Errorf("failed to identify reference (tag/branch) for the checked-out revision '%s'", ref)
}

// FindGithubRepo get the repo
func FindGithubRepo(ctx context.Context, file, githubInstance, remoteName string) (string, error) {
	if remoteName == "" {
		remoteName = "origin"
	}

	url, err := findGitRemoteURL(ctx, file, remoteName)
	if err != nil {
		return "", err
	}
	_, slug, err := findGitSlug(url, githubInstance)
	return slug, err
}

func findGitRemoteURL(_ context.Context, file, remoteName string) (string, error) {
	repo, err := git.PlainOpenWithOptions(

View on GitHub (pinned to 4f41128141)

Solutions

Checkout a named ref instead of a bare sha: git checkout main (or the tag/branch the workflow targets)
If you must test a sha, create a temporary branch at it: git switch -c test-sha <sha>
Unshallow the clone (git fetch --unshallow or --tags) so refs are visible
Pass the ref explicitly to act via --GITHUBREF or equivalent flag if your act version supports overriding

Example fix

# before (detached, no ref points at sha)
git checkout 1a2b3c4 && act

# after
git switch -c tmp-test 1a2b3c4 && act

Defensive patterns

Strategy: validation

Validate before calling

// preflight: ensure the checked-out sha is referrable
out, err := exec.Command("git", "name-rev", "--name-only", "HEAD").Output()
name := strings.TrimSpace(string(out))
if err != nil || name == "undefined" {
    return fmt.Errorf("HEAD not on any branch/tag; create one: git switch -c ci-test")
}

Prevention

Run act from a named branch or tag, not a detached sha
Unshallow clones before act when refs are missing
Create a temp branch at the sha you need to test

When it happens

Trigger: Running act on a detached HEAD (git checkout <sha>, or a CI checkout of a merge commit) where the sha is not the tip of any branch or tag; also when .git metadata is partially present (shallow/sparse clones missing refs) so the iteration never matches.

Common situations: Checking out a PR merge sha locally then running act; worktrees created from commits ahead of their branches; shallow clones (depth=1) whose single fetched ref is HEAD itself; a branch deleted after the checkout.

Related errors

AI-assisted analysis of nektos/act@4f41128141 (2026-08-15). Data as JSON: /api/errors/b4f28df370c4e36b. Report an issue: GitHub.