How to use GitVersion for semantic versioning with TeamCity and Octopus Deploy

ContinuousDeploymentWithGitVersionAndGitFlow.md

Setting up TeamCity and Octopus with GitVersion

Assumptions

• You are using GitFlow
• You want to deploy a new version of your software every time a commit is made to the develop branch
• You are using Octopack to package your application for deployment

Instructions

1. Install-Package GitVersion.CommandLine into your application

2. In your solution root run packages\GitVersion.CommandLine.3.3.0\tools\gitversion.exe init and run the getting started wizard. Indicate you are using GitFlow, and select to increment the SemVer every commit - this is referred to as continuous deployment mode

3. If you haven't been tagging any version numbers onto your commits, have a read on how to manually increment your version number and get this right locally before proceeding - the nice thing about GitVersion is you can run the executable locally and see what version it will generate for a given commit in your repository. Nice.

4. In TeamCity, add a configuration parameter to your build configuration's parent project named GitVersion.NuGetVersion (If you are wondering why GitVersion has NuGetVersion and NuGetVersionV2 output variables read here

5. Still in TeamCity, in your application's build configuration, set up a build step before your compilation step as described here under "Basic Usage" In this step, GitVersion will determine the appropriate version number for your app based on some rules, update your AssemblyInfo files so that the built assemblies are appropriately versioned, and update the %build.number% parameter for your Build Configuration to the full semantic version (not to be confused with the NuGetVersion, as nuget v2 doesn't support full SemVer). It will also update any parameters matching GitVersion.* in your build configuration or project - like the one we added in step 3!

6. Still in TeamCity, open your web application build step, and under Octopus Packaging, set OctoPack package version to %GitVersion.NuGetVersion%

7. Finally, go back to your build configuration's General Settings and set the Build number format to {0} - GitVersion sets this for us after it does it's thing, so we no longer need to specify it, it may as well reflect the build count until it is set.

Viola! You're application is now semantically versioned, and this version is reflected by TeamCity's build number, your built assemblies, and your generated nuget packages.

But wait, there's more! You now want to create a release in Octopus and deploy your packages!

This part is resonably easy. Just make sure in your "Create Octopus Release" build step, that you specify %dep.btxxx.GitVersion.NuGetVersion%in the Release number property of the build step, where btxxx is your Snapshot Dependency on the build configuration which built your app and produced the nuget packages to deploy.

You should also make sure to specify Additional command line arguments in the "Create Octopus Release" build step as --packageversion=%dep.btxxx.GitVersion.NuGetVersion% to ensure the correct package version is selected by Octopus, and not just the highest available version.

FAQ

Q: Why is the build number (full semver) different to the nuget version produced?

A: Nuget V2 doesn't support full SemVer (reference), which is what is used currently by Octopus / TeamCity internally - GitVersion creates a NugetVersion for us that reflects the SemVer. Nuget V3 does, but isn't used by the tooling (a little bird told me Octopus is moving to V3 soon)

Q: Why do we use the NugetVersion when creating the Octopus release instead of the build number?

A: While Octopus will happily create a release with a full SemVer version number, when it calls back to TeamCity for packages matching that number, TeamCity's nuget feed will get upset - it wants the NugetVersion, not the full SemVer.

@JulianGuppy, I am in the same position as you, were you able to get any more information on this?