Team Foundation Build (vNext) Setup
In Team Foundation Build (the web based build system) you can call GitVersion either using the Command Line build step or install an extension / custom build step. The custom build step requires a one-time setup to import the GitVersion task into your TFS or VSTS instance.
Using GitVersion with the MSBuild Task NuGet Package
- Add the GitVersionTask NuGet package to your projects.
See MSBuild Task for further instructions how to use the MS Build Task.
Using GitVersion with the Command Line build step
- Make sure to have GitVersion.exe under version control. There exists also a Chocolatey package for installing GitVersion.exe on build agents.
- Add a Command Line build step to your build definition. You'll probably want to drag the task to be at or near the top to ensure it executes before your other build steps.
- Set the Tool parameter to
- Set the Arguments parameter to
/output buildserver /nofetch.
- If you want the GitVersionTask to update AssemblyInfo files add
updateAssemblyInfo trueto the Arguments parameter.
- If you want to update the build number you need to send a logging command to TFS.
Using the custom GitVersion build step
Installing the extension
For Visual Studio Team Service or TFS 2015 Update 2 or higher it is recommonded to install the GitVersion extension:
- Install the GitVersion Extension.
Manually installing/updating the custom build step
If you run TFS 2015 RTM or Update 1 or don't want to install the GitVersion extension you can install the build task manually:
- Install the
tfxcommand line tool as shown here.
- For TFS 2015 On-Prem configure Basic Authentication in TFS as shown here.
- Download the GitVersion TFS build task from the latest release on the GitVersion releases page and unzip.
tfx loginas shown here.
- From the directory outside of where you unzipped the task, run
tfx build tasks upload --task-path .\GitVersionTfsTask --overwritewhere GitVersionTfsTask is the directory containing the files.
- It should successfully install.
Using the GitVersion custom build step
From a TFS build definition, select "Add a Step" and then in the Build category, choose GitVersion and click Add. You'll probably want to drag the task to be at or near the top to ensure it executes before your other build steps.
If you want the GitVersionTask to update AssemblyInfo files, check the box in the task configuration. For advanced usage, you can pass additional options to the GitVersion exe in the Additional arguments section.
The VSO build step can update your build number with GitVersion variables. See below for details.
Running inside TFS
Using the GitVersion Variables
GitVersion passes variables in the form of
GitVersion.Major) to TFS Build and also writes
GITVERSION.MAJOR) environment variables that are available for any subsequent build step.
To use these variables you can just refer to them using the standard variable syntax. For instance
$(GitVersion.NuGetVersion) in your nuget pack task to set the version number. Since update 1 there are no known limitations.
See Variables for an overview of available variables.
Using GitVersion variables in build name
To use GitVersion's variables in the build name, just add them in the form
$(GITVERSION_FullSemVer) into the Build definition's build number string. Then just ensure GitVersion is called with
/output buildserver and it will replace those variables with the calculated version.
The TFS GitVersion Build Step (above) handles this too, so if you're already using that, there's nothing extra to configure.
If GitVersion does not find any substitutions it will just default to using
IMPORTANT: If you currently use
$(rev:.r) in your build number, that won't work correctly if you
use GitVersion variables as well due to the delayed expansion of the GitVersion vars. Instead,
You might be able to use
$(GitVersion_BuildMetaData) to achieve a similar result.
See Variables for more info on the variables.
- If you are using on premises TFS, make sure you are using at least TFS 2015 Update 1, otherwise a few things will not work.
- Installing the extension on an on premise TFS requires at least TFS 2015 Update 2.
- You need to make sure that all tags are fetched for the Git repository, otherwise you may end with wrong versions (e.g.
1.2.0for tagged releases) Just checking the
Clean Repositorycheck box in the build definition settings might not be enough since this will run a
git clean -fdx/reset --hardwithout fetching all tags later. You can force deletion of the whole folder and a re-clone containing all tags by settings the variable
all. This will take more time during build but makes sure that all tags are fetched. In the future it is planned to allow using
git.exeinstead of current
libgit2sharpfor syncing the repos which might allow other possibilities to solve this issue. For details see this GitHub issue.
- If running a build for a certain commit (through passing the commit SHA while queueing the build) all tags from the repository will be fetched, even the ones newer than the commit. This can lead to different version numbers while re-running historical builds.