Skip to content

Latest commit

 

History

History
88 lines (69 loc) · 3.62 KB

cloudbuild.md

File metadata and controls

88 lines (69 loc) · 3.62 KB
Raw

Cloud build support

Nerdbank.GitVersioning implicitly supports all cloud build services and CI server software because it simply uses git itself and integrates naturally in MSBuild, gulp and other build scripts.

Requirements

  1. Your CI build should be configured to actually clone the git repo rather than download sources (i.e. the '.git' folder is required).
  2. Do not enable any 'shallow clone' option on your CI build, as that erases git history that is required for accurate version calculation.

Optional features

By specifying certain cloudBuild options in your version.json file, you can activate features for some cloud build systems, as follows

Automatically match cloud build numbers to to your git version

Cloud builds tend to associate some calendar date or monotonically increasing build number to each build. These build numbers are not very informative, if at all. Instead, Nerdbank.GitVersioning can automatically set your cloud build's build number to equal the semver version calculated during your build.

Enable this feature by setting the cloudBuild.buildNumber.enabled field in your version.json file to true, as shown below:

{
  "version": "1.0",
  "cloudBuild": {
    "buildNumber": {
      "enabled": true
    }
  }
}

When any cloud build starts, a build number is initially generated by the CI server until the build itself overrides it as this option will cause it to do. If a build aborts before the build reassigns the build number, it will remain at the cloud assigned build number. This can show up in your build history with some failed builds having a different versioning scheme than passing or some other failed builds.

When you enable this feature, consider whether this will cause the generated build numbers to overlap with those generated by the cloud build previously or in the future. For example, AppVeyor defaults to assigning build numbers with a 1.0.x notation where x increases. If your version.json file sets your version to "1.0", the generated build numbers can overlap, making AppVeyor fail builds due to a non-unique number. To avoid this, make sure that your CI build creates initial build numbers that do not overlap with those produced by semantic versioning. For instance, you can set your appveyor build's version to 1.1000 or 50.0 so that your regular semantic version build numbers are in an entirely unique range.

Set special build variables for use in subsequent build steps

Build variable MSBuild property Sample value
GitAssemblyInformationalVersion AssemblyInformationalVersion 1.3.1+g15e1898f47
GitBuildVersion BuildVersion 1.3.1.57621
GitBuildVersionSimple BuildVersionSimple 1.3.1

This means you can use these variables in subsequent steps in your cloud build such as publishing artifacts, so that your richer version information can be expressed in the publish location or artifact name.

Enable this feature by setting the cloudBuild.setVersionVariables field in your version.json file to true, as shown below:

{
  "version": "1.0",
  "cloudBuild": {
    "setVersionVariables": true
  }
}

CI Server specific configurations

TeamCity

TeamCity does not expose the build branch by default as an environment variable. This can be exposed by adding an environment variable with the value of %teamcity.build.vcs.branch.<vcsid>% where <vcsid> is the root id described on the TeamCity VCS roots page. Details on this variable can be found on the TeamCity docs.