Follow up on GitHub tag build documentation and ref classification

Author: arturcic

docs/input/docs/reference/build-servers/github-actions.md

@@ -17,3 +17,18 @@ without it, GitHub Actions might perform a shallow clone, which will cause GitVe
 :::
 
 More information can be found at [gittools/actions](https://github.com/GitTools/actions/blob/main/docs/examples/github/gitversion/index.md).
+
+## Branch and tag builds
+
+GitVersion uses the following [GitHub Actions default environment variables](https://docs.github.com/en/actions/reference/workflows-and-actions/variables#default-environment-variables) to identify the ref being built:
+
+| Variable | How GitVersion uses it |
+| --- | --- |
+| `GITHUB_REF_TYPE` | Distinguishes tag builds (`tag`) from branch builds (`branch`). |
+| `GITHUB_REF` | Supplies the full ref, such as `refs/heads/main`, `refs/pull/42/merge`, or `refs/tags/1.2.3`. |
+
+For a tag build, GitVersion treats `GITHUB_REF` as the selected tag rather than a branch name. This also applies when manually running a workflow with `workflow_dispatch` and selecting a tag.
+
+A historical tag can point to a commit that is no longer the tip of any branch. If normalization cannot attach HEAD to a local branch, it checks the selected local tag. When that tag resolves to the checked-out commit, GitVersion keeps HEAD detached and avoids an unnecessary remote lookup for pull-request refs. Existing branch selection takes precedence when a local branch identifies HEAD.
+
+The selected tag must exist locally and resolve to HEAD for this behavior to apply. Checking out a different ref from the one reported by `GITHUB_REF` does not make an unrelated local tag identify the build. Keep `fetch-depth: 0` as described above so GitVersion has the full history available for version calculation.

src/GitVersion.BuildAgents/Agents/GitHubActions.cs

@@ -1,5 +1,6 @@
 using System.IO.Abstractions;
 using GitVersion.Extensions;
+using GitVersion.Git;
 using GitVersion.OutputVariables;
 
 namespace GitVersion.Agents;
@@ -64,7 +65,7 @@ public override void WriteIntegration(Action<string?> writer, GitVersionVariable
         var reference = this.environment.GetEnvironmentVariable("GITHUB_REF");
         return string.Equals(refType, "tag", StringComparison.OrdinalIgnoreCase)
             && reference != null
-            && reference.StartsWith("refs/tags/", StringComparison.Ordinal)
+            && new ReferenceName(reference).IsTag
                 ? reference
                 : null;
     }