TeamCity build step script for setting the build number based on the branch or pull request
MIT License
Sets the TeamCity build number based on the branch or Pull Request.
Command line tool to set the build number based on the branch or pull request within TeamCity.
Designed to be run as a build step within a TeamCity pipeline. It accesses system properties via env.TEAMCITY_BUILD_PROPERTIES_FILE
but needs others passed in as arguments (see options below).
This can be used as a cross-platform replacement for the 'GitFlow' PowerShell build step.
Use the example folder for local development and testing.
We are using the semver 2.0 convention: https://semver.org/ this means that all pre-release packages are distinguied by a -
and all release packages by +
As an example the build number format is in the form:
Pre-release:
Major.Minor.Patch.Counter-BranchName
Release:
Major.Minor.Patch.Counter+rCommitHash
Note: the following examples assume a version of 1.2.3, a build counter of 99 and a commit hash of a1b2c3d:
Branch | Version |
---|---|
master | 1.2.3.99+ra1b2c3d |
pull request (from branch) | 1.2.3.99-branch-name |
feature branch | 1.2.3.99-branch-name |
Visual Studio 2015 and nuget packages
Please note the nuget package manager in some older versions of VS may not show the release packages because it doesn't support semver 2.0 conventions, therefore please ensure you are using the latest nuget package manager at least VSIX 3.6.0
TeamCity and Nuget restore
Semver 2.0 is only fully supported in Nuget Clients 4.5+ so please ensure you have this otherwise you may not be able to restore packages.
With npm>=5.2, use the Command Line Interface via npx:
npx @nice-digital/teamcity-build-number --branch=%teamcity.build.branch% --usePackageJsonVersion --gitHubToken=%GITHUB_TOKEN% --gitHubRepo=%system.GitHubOwnerRepo%
String
true
b
--branch=%teamcity.build.branch%
The branch to build from e.g. %teamcity.build.branch%
Boolean
false
false
--usePackageJsonVersion
Whether to use the package.json version as the build number. Only needed if you are using package.json version, and it doesn't require a value e.g. just --usePackageJsonVersion
.
Note: in v0.x this option could be used like --usePackageJsonVersion=true
but this is no longer the case.
Note 2: If you use this you need to add system.build.counter and point it to %build.counter% in the System Properties in the Parameters of the Build Configuration.
String
true
to build Pull RequestsA GitHub authentication token. Used for getting details of a Pull Request from the GitHub API. Must have access to the repository set in gitHubRepo
.
String
true
--gitHubRepo nice-digital/guidance-web
The GitHub organisation (or username) and repository to check for status of Pull Requests etc.
String
false
--packageRelativePath src/client
If no value is supplied the package.json file will be looked for in the root of the repository. If a value is given such as "src", then it will look for said file in "[repo root]\src\package.json"
Boolean
false
--enforceNamingConvention
If no value is supplied the naming conventions on the branch and pull request names are not enforced.
If present (which means true
) then the naming conventions are enforced and the build will be cancelled with the reason logged.
Note: in v0.x this option could be used like --enforceNamingConvention=true
but this is no longer the case.
To debug this module run a command like the following:
node --inspect-brk bin/cli.js --branch mybranch --gitHubToken mytoken --gitHubRepo myrepo --usePackageJsonVersion
then navigate chrome to:
a "Remote target" should pop up. Just click 'inspect' and chrome dev tools will debug the script.
If you're using NVM or an npm version < 5.2 then you might need to run the following command before setting the build number:
npm install -g npm
Note: if you're using a build agent with Node.js >= 8.2.0 this should have npm >= 5.3 pre-installed so you might not need to update npm.
We recommend the following branch specification for your VCS root ( Build Configuration Settings -> Version Control Settings -> VCS Roots -> Branch specification). This automatically builds master.
+:refs/heads/(master)
DO NOT specify +:refs/pull/(*/merge)
in the branch specification this will allow for unauthorised pull requests to run in TC. If you want to build pull requests use the build feature "Pull requests" this will allow you to limit pull requests from members and collaborators.
See Building GitHub pull requests with TeamCity on the JetBrains blog for more info.