Incorrect tag normalization in some CI environments

[ChristopherMann]

When triggering a CI build for a tag, some CI environments (at least GitLab CI and Azure Pipelines) will incorrectly normalize the tag name
to a local branch name. Consequently, some prerelease labels are computed incorrectly and look like this: tags-v1-2-3-beta-1.

Current status

As mentioned by @HHobeck in #4291 (reply in thread), there is some "common deficit". The following list contains the status as far as I was able to determine:

• GitHub Action (fixed)
  • Tag name is passed in $GITHUB_REF
  • CI documentation: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#default-environment-variables
  • Code:

    GitVersion/src/GitVersion.BuildAgents/Agents/GitHubActions.cs

    Lines 49 to 57 in 81425de

    	public override string? GetCurrentBranch(bool usingDynamicRepos)
    	{
    	// https://docs.github.com/en/actions/learn-github-actions/environment-variables#default-environment-variables
    	// GITHUB_REF must be used only for "real" branches, not for tags.
    	// Bug fix for https://github.com/GitTools/GitVersion/issues/2838
    	var refType = Environment.GetEnvironmentVariable("GITHUB_REF_TYPE") ?? "";
    	return refType.Equals("tag", StringComparison.OrdinalIgnoreCase) ? null : Environment.GetEnvironmentVariable("GITHUB_REF");
    	}

  • Issue: [Bug] Tag checkout on GitHub Actions generates unexpected branch #2838
  • PR: Use GITHUB_REF only for CI builds on branches #3033
• BitBucket Pipelines (fixed)
  • Branch name in $BITBUCKET_BRANCH, tag name in $BITBUCKET_TAG
  • CI documentation: https://support.atlassian.com/bitbucket-cloud/docs/variables-and-secrets/
  • Code:

    GitVersion/src/GitVersion.BuildAgents/Agents/BitBucketPipelines.cs

    Lines 66 to 75 in 81425de

    	public override string? GetCurrentBranch(bool usingDynamicRepos)
    	{
    	var branchName = EvaluateEnvironmentVariable(BranchEnvironmentVariableName);
    	if (branchName?.StartsWith("refs/heads/") == true)
    	{
    	return branchName;
    	}
    	return null;
    	}

  • Issue: none (The initial implementation already contains check to allow only branch names)
  • PR: Add build agent for BitBucket Pipelines #3069
• Azure Pipelines (not fixed)
  • Tag name is passed in $BUILD_SOURCEBRANCH
  • CI documentation: https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml
  • Issue: [BUG]: GitVersion (in Azure Devops) calculating wrong version when building a tag #4015
  • PR: Fix tag normalization for Azure Pipelines #4400
• Gitlab CI (not fixed):
  • Tag name in $CI_COMMENT_REF_NAME
  • CI documentation: https://docs.gitlab.com/ee/ci/variables/predefined_variables.html
  • Issue: [ISSUE]: GitLab CI tag pipelines result in an incorrect version #4186
  • PR: Do not return the tag as branch name for GitLab CI #4187

I have not investigated any other CI environments.

What to do?

1. Specify that CI agents must not return tag names (IBuildAgent.GetCurrentBranch() must not return refs/tags/<tag>) and align all CI agents accordingly.
2. Block refs/tags/<tag> globally in GitPreparer.

Not sure if 1) or 2) is the better approach.

Some of the reported issues have been closed by pointing out #4212. Unfortunately, it is not very clear that we are chasing a normalization issue in other CI environments.

Workaround for Azure Pipelines

The following workaround can used in Azure Pipelines wit GitVersion 6.0.5:

variables:
  GIT_BRANCH: ${{ iif(startsWith(variables['Build.SourceBranch'], 'refs/tags/'), '', variables['Build.SourceBranch']) }}

$GIT_BRANCH takes precedence over $BUILD_SOURCEBRANCH. Hence, the repository normalization will see no branch name and behave like in GitHub Actions. The workaround is quite fragile and works only in Azure Pipelines. The higher precedence of $GIT_BRANCH is specific to Azure Pipelines.

[arturcic]

The higher precedence of $GIT_BRANCH is specific to Azure Pipelines.

Would be nice if we can define this for all the supported agents, and to have the first variable to be checked

[HHobeck]

When triggering a CI build for a tag, some CI environments (at least GitLab CI and Azure Pipelines) will incorrectly normalize the tag name to a local branch name. Consequently, some prerelease labels are computed incorrectly and look like this: tags-v1-2-3-beta-1.
...

What to do?

1. Specify that CI agents must not return tag names (IBuildAgent.GetCurrentBranch() must not return refs/tags/<tag>) and align all CI agents accordingly.
2. Block refs/tags/<tag> globally in GitPreparer.

I think we need to first agree on a concept what the result of the normalization process should be for all agents when building from e.g. a tag. I have outlined the user expectation/scenarios in post #4291 (reply in thread) and #4212 (comment) and the current detached head behavior in post #4212 (comment).

Please correct me if I'm wrong: When you set the current branch to null then GitVersion runs in one of the detached head scenario which might be not expected. Probably we need to first normalize to the format:

• refs/heads/<branch_name> for branches,
• refs/tags/<tag_name>for tags
• refs/pull/<pr_number>/merge for pull requests and
• ?? for commits ??

and change the configuration in the GitFlow/v1, GitHubFlow/v1 and TrunkBased/preview1 workflow by adding new branch configuration sections for each "CI-Build" scenario.

Does this make sense to you?

@asbjornu and @arturcic

[ChristopherMann]

Thank you for the additional pointers. I initially thought that the detached head is the intended state when triggering a build for a tag (in my case I trigger Azure Pipelines for the tag). I agree that the output of IBuildAgent.GetCurrentBranch() should be normalized instead.

When Azure Pipelines is triggered for a tag, the normalization currently does the following:

INFO [25-01-30 17:43:44:87] Branch from build environment: refs/tags/v0.2.0-beta.1
INFO [25-01-30 17:43:44:87] -< Begin: Normalizing git directory for branch 'refs/tags/v0.2.0-beta.1' >-
  INFO [25-01-30 17:43:44:90] One remote found (origin -> '******').
  INFO [25-01-30 17:43:44:90] Skipping fetching, if GitVersion does not calculate your version as expected you might need to allow fetching or use dynamic repositories
  INFO [25-01-30 17:43:44:91] Updating local branch tags/v0.2.0-beta.1 to match ref refs/tags/v0.2.0-beta.1
  INFO [25-01-30 17:43:44:94] Skipping update of 'refs/remotes/origin/main' as it already matches the remote ref.
  INFO [25-01-30 17:43:44:94] Skipping update of 'refs/remotes/origin/release/0.2.0' as it already matches the remote ref.
  INFO [25-01-30 17:43:44:94] HEAD points at branch 'refs/heads/tags/v0.2.0-beta.1'.
INFO [25-01-30 17:43:44:95] -< End: Normalizing git directory for branch 'refs/tags/v0.2.0-beta.1' (Took: 76.05ms) >-
INFO [25-01-30 17:43:44:95] Found configuration file at 'D:/a/1/s\GitVersion.yml'
INFO [25-01-30 17:43:45:12] Using latest commit on specified branch
INFO [25-01-30 17:43:45:14] Getting tagged semantic versions. TagPrefix: [vV]? and Format: Strict
INFO [25-01-30 17:43:45:22] Running against branch: tags/v0.2.0-beta.1 ('719d677' - Add trigger for release branches)

It looks like the tag v0.2.0-beta.1 has been normalized to the local branch tags/v0.2.0-beta.1. Is this the intended behavior? This creates a conflict with the actual branch tags/v0.2.0-beta.1 (refs/heads/tags/v0.2.0-beta.1). But I would hope that such a branch name is a corner case.

Anyway, I can come up with a branch configuration like this which would work for the specific case of the beta label:

branches:
  tags:
    mode: ManualDeployment
    label: '{BranchName}'
    regex: ^tags/[vV]?\d+\.\d+\.\d+-(?<BranchName>.+)\.\d+
    prevent-increment:
      when-current-commit-tagged: true

This regex will obviously not work for a lot of other cases. I am wondering if tags should be treated as special branches or separately. It might be hard to come up with a configuration which behaves correctly for all tags.

My naive expectation would be still that:

1. When I trigger a CI on a specific tag, it will use the version from the specified tag. For most CI systems, we know the name of the tag.
2. When I run on a detached head and that commit has exactly one tag, it will use the version from the tag.

I understand that the version should still be valid according to one of the applicable branch configurations. Maybe, the tag could be treated as a selector for the branch configuration?