Identify multiple builds against same commit/tag/branch on Team Foundation Build (vNext)

[ralphhendriks]

Dear all,

I am trying to figure out the best practice to distinguish between multiple builds against the same commit/tag/branch. My current project is on TFS (on premise). TFS (as well VSTS) stores the build configuration separately from the source repository. Hence, multiple builds against the same commit/tag/branch could result in different artifacts. I would like the build metadata to reflect this.

Before using GitVersion we have solved this by using the revision counter from the TFS Build. The default mechanism of TFS determines the build number before any build task is invoked. There is a build number replacement token $(Rev:.r) that can be used to make the build number unique when nothing else changed (docs). We used to rely on the build number, and parse the SemVer and build metadata from it.

As explained in the docs, GitVersion doesn't play nice with the revision number replacement token on the build number because of delayed expansion in the GitVersion TFS task. That leaves the problem that multiple builds against the same commit/tag/branch will result in the same output of GitVersion.

I am wondering how others cope with this issue. I am willing to contribute to the docs if there is a clear consensus on how to handle this. If there isn't, then adding something to the GitVersion output that is sufficiently unique and sortable (i.e. a timestamp) might be a way forward.

I am interested in hearing you opinions.

[JakeGinnivan]

I think the ideal solution is to allow GitVersion to take some sort of build_number or revision parameter which can be used, surfaced in variables and in the build metadata. That way you can pass in an external variable into GitVersion and it will affect the build number.

Would love a PR for this :)

[JakeGinnivan]

The discussion at #648 raised a similar issue. Going to close it in favor of this. I am now more keen on the idea than I was then

[asbjornu]

Where would the build number be used? If it's in any of the Assembly*Version attributes, I think the route of adding support for environment variables and adding a -format version for the ones that currently only have -scheme variants in the configuration might be a good solution (as mentioned in #1145 (comment) and #1367 (comment)).

I'm envisioning something like this:

assembly-versioning-format: '{Major}.{Minor}.{Patch}.{env:BUILD_NUMBER}'
assembly-file-versioning-format: '{Major}.{Minor}.{Patch}'
assembly-informational-format: '{InformationalVersion}-{env:MY_ENV_VAR}'

The novel thing here is the {env:} syntax, which allows you to reference any environment variable available at build time in GitVersion.yml. Would this suffice?

PS: The discussion in #648 concludes that this is something we don't want to do. That conclusion doesn't hold up anymore, I think. This feature has been asked for consistently and frequently over the years and while I think it's a great feature of GitVersion to be able to produce the same version number wherever a commit is built, that might not be a requirement for everyone. See #1367 (comment) for the requirements on traceability in the medical industry, for instance.

[jbaehr]

Regarding the discussion in #648: I think the conclusion over there is still valid. But here we're taking about something else. As far as I understood, the decision was against the expansion of env-vars within the config.yml (buildMetadata: $ENV['BUILD_NUMBER'] || 1313). The current approach is the expansion of env vars in format strings (assembly-file-versioning-format: '{Major}.{Minor}.{Patch}.{$JENKINS_BUILD_NUMBER}'). That is something else and in my eyes a much better idea, indeed.

We need some fall-back though in case the env var is not set. In our case we want the build number from the CI-server as forth digit in the AssemblyFileVersion (and only there; to properly support Windows Installer's "Major Upgrades", see #1366). On a developer's machine I don't want to set dummy build server env vars. What do you think about the following?

mode: ContinuousDeployment
assembly-versioning-scheme: Major
assembly-file-versioning-format: '{Major}.{Minor}.{Patch}.{$JENKINS_BUILD_NUMBER??0}'
tag-prefix: '[vV]'
...

In a format string we could have either

• {GitVersionVariable} (e.g. {Major}),
• {$ENV_VAR}, every placeholder prefixed by $ is treated as environmental variable
• {$ENV_VAR??fall-back-string}. The syntax as well as the function is inspired by C#'s null-propagation operator.

[sanderaernouts]

@ruhullahshah can I use this {env:VARIABLE_NAME} notation as well for versioning the pre-release tag?

I'm currently pushing NuGet packages as part of my PR builds in Azure DevOps. But if I use git commit --amend and git push --force to keep my commits clean GitVersion will give the exact semantic version number, for example: 2.0.0-pr5566.10. What I would like to do to ensure my version is unique is to get something like 2.0.0-pr5566.10.684469. Where 684469 is the build id in azure DevOps. This is in an incrementing id that is always unique so that would make sure that my next build results in a higher SemVer 2 version number.

[ruhullahshah]

@sanderaernouts For the first part of your query, AFAIK you will have to add support for enabling {env:VARIABLE_NAME} notation to affect the PreReleaseTag in variables.

For the second part, you could achieve this without any changes by setting the assembly-file-versioning-format config. value (for more details, see configuration).

An example might help. In your GitVersion.yml, set:
assembly-file-versioning-format: {Major}.{Minor}.{Patch}.{PreReleaseTag}.{env:AZURE_BUILD_ID}. After running GitVersion.exe with this configuration value set, you could use the output of either AssemblySemVer or AssemblySemFileVer(i am a bit rusty on this part, please verify) to get a unique version number.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. After 30 days from now, it will be closed if no further activity occurs. Thank you for your contributions.

[asbjornu]

Support for environment variables in the GitVersion.yaml file was added in #1385.