diff --git a/README.md b/README.md
index a1f4770..5e022bc 100644
--- a/README.md
+++ b/README.md
@@ -61,6 +61,7 @@ public static class AppVersion
 | `SetPackageVersionFromBranch` | `true` | Automatically set NuGet package version from branch |
 | `IncludeCommitIdMetadata` | `true` | Include commit ID as build metadata in versions |
 | `GenerateVersionFile` | `false` | Generate `version.json` file during build |
+| `SimpleBranchVersioning_Branch` | (auto-detected) | Override branch name (useful for CI) |
 
 ### Custom Class Name and Namespace
 
@@ -74,15 +75,20 @@ public static class AppVersion
 
 ### GitHub Actions
 
-By default, GitHub Actions checks out PRs in detached HEAD state, which results in version `detached.<commit-id>`. To get the actual branch name, configure the checkout action:
+By default, GitHub Actions checks out PRs in detached HEAD state, which results in version `detached.<commit-id>`. To get the actual branch name while still testing the merged result, use the `SimpleBranchVersioning_Branch` property:
 
 ```yaml
-- uses: actions/checkout@v4
-  with:
-    ref: ${{ github.head_ref }}  # Checkout the actual branch, not the merge commit
+- uses: actions/checkout@v4  # Default checkout tests the merge result
+
+- name: Build
+  run: dotnet build -p:SimpleBranchVersioning_Branch=${{ github.head_ref }}
 ```
 
-For push events on branches, the default checkout works correctly.
+This approach:
+- Tests the actual merge result (catches integration issues)
+- Uses the correct branch name for versioning
+
+For push events on branches, the default checkout works correctly without any override.
 
 ### Version File
 
diff --git a/src/SimpleBranchVersioning/AppVersionGenerator.cs b/src/SimpleBranchVersioning/AppVersionGenerator.cs
index 4598a70..9b191e9 100644
--- a/src/SimpleBranchVersioning/AppVersionGenerator.cs
+++ b/src/SimpleBranchVersioning/AppVersionGenerator.cs
@@ -78,6 +78,7 @@ public void Initialize(IncrementalGeneratorInitializationContext context)
                 provider.GlobalOptions.TryGetValue("build_property.IncludeCommitIdMetadata", out string? includeMetadataStr);
                 provider.GlobalOptions.TryGetValue("build_property.GenerateVersionFile", out string? generateVersionFileStr);
                 provider.GlobalOptions.TryGetValue("build_property.SetPackageVersionFromBranch", out string? setPackageVersionStr);
+                provider.GlobalOptions.TryGetValue("build_property.SimpleBranchVersioning_Branch", out string? overrideBranch);
 
                 // Parse IncludeCommitIdMetadata (default: true)
                 bool includeCommitIdMetadata = !string.Equals(includeMetadataStr, "false", StringComparison.OrdinalIgnoreCase);
@@ -90,7 +91,7 @@ public void Initialize(IncrementalGeneratorInitializationContext context)
                 var (branch, commitId) = ParseGitInfo(gitInfo.HeadContent, gitInfo.GitDir)
                                        ?? ReadGitInfo(projectDir);
 
-                return new BuildProperties(rootNamespace, branch, commitId, includeCommitIdMetadata, generateVersionFile, setPackageVersionFromBranch);
+                return new BuildProperties(rootNamespace, branch, commitId, includeCommitIdMetadata, generateVersionFile, setPackageVersionFromBranch, overrideBranch);
             });
 
         // Look for AppVersionConfigAttribute in assembly attributes
@@ -120,7 +121,16 @@ public void Initialize(IncrementalGeneratorInitializationContext context)
         {
             var ((buildProps, config), hasTopLevelStatements) = input;
 
-            string branch = string.IsNullOrEmpty(buildProps.Branch) ? "unknown" : buildProps.Branch!;
+            // Use override branch if provided, otherwise use detected branch
+            string branch;
+            if (!string.IsNullOrEmpty(buildProps.OverrideBranch))
+            {
+                branch = buildProps.OverrideBranch!;
+            }
+            else
+            {
+                branch = string.IsNullOrEmpty(buildProps.Branch) ? "unknown" : buildProps.Branch!;
+            }
             string commitId = string.IsNullOrEmpty(buildProps.CommitId) ? "0000000" : buildProps.CommitId!;
 
             // Calculate all version formats
@@ -404,6 +414,6 @@ private static (string? branch, string? commitId) ReadGitInfo(string? projectDir
     }
 #pragma warning restore RS1035
 
-    private sealed record BuildProperties(string? RootNamespace, string? Branch, string? CommitId, bool IncludeCommitIdMetadata, bool GenerateVersionFile, bool SetPackageVersionFromBranch);
+    private sealed record BuildProperties(string? RootNamespace, string? Branch, string? CommitId, bool IncludeCommitIdMetadata, bool GenerateVersionFile, bool SetPackageVersionFromBranch, string? OverrideBranch);
     private sealed record AppVersionConfig(string? Namespace, string? ClassName);
 }
diff --git a/src/SimpleBranchVersioning/build/SimpleBranchVersioning.props b/src/SimpleBranchVersioning/build/SimpleBranchVersioning.props
index 5fca783..15467f5 100644
--- a/src/SimpleBranchVersioning/build/SimpleBranchVersioning.props
+++ b/src/SimpleBranchVersioning/build/SimpleBranchVersioning.props
@@ -4,6 +4,7 @@
         <SetPackageVersionFromBranch Condition="'$(SetPackageVersionFromBranch)' == ''">true</SetPackageVersionFromBranch>
         <!-- Default: include commit ID as build metadata in versions -->
         <IncludeCommitIdMetadata Condition="'$(IncludeCommitIdMetadata)' == ''">true</IncludeCommitIdMetadata>
+        <!-- SimpleBranchVersioning_Branch: optional override for branch name (useful for CI detached HEAD) -->
 
         <!-- Disable auto-generated assembly version attributes (source generator provides these) -->
         <GenerateAssemblyVersionAttribute>false</GenerateAssemblyVersionAttribute>
@@ -18,6 +19,7 @@
         <CompilerVisibleProperty Include="IncludeCommitIdMetadata" />
         <CompilerVisibleProperty Include="GenerateVersionFile" />
         <CompilerVisibleProperty Include="SetPackageVersionFromBranch" />
+        <CompilerVisibleProperty Include="SimpleBranchVersioning_Branch" />
     </ItemGroup>
 
     <!-- Find the .git directory by walking up from ProjectDir (using forward slashes for cross-platform) -->