{"id":15297102,"url":"https://github.com/nice-digital/teamcity-build-number","last_synced_at":"2025-07-11T05:39:19.103Z","repository":{"id":42363683,"uuid":"107122412","full_name":"nice-digital/teamcity-build-number","owner":"nice-digital","description":"TeamCity build step script for setting the build number based on the branch or pull request","archived":false,"fork":false,"pushed_at":"2022-04-08T22:03:40.000Z","size":119,"stargazers_count":3,"open_issues_count":4,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-07-02T11:14:41.007Z","etag":null,"topics":["build","build-automation","build-tools","nodejs","teamcity"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@nice-digital/teamcity-build-number","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nice-digital.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-10-16T12:10:41.000Z","updated_at":"2023-06-17T12:38:19.000Z","dependencies_parsed_at":"2022-08-31T20:00:50.533Z","dependency_job_id":null,"html_url":"https://github.com/nice-digital/teamcity-build-number","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nice-digital/teamcity-build-number","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nice-digital%2Fteamcity-build-number","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nice-digital%2Fteamcity-build-number/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nice-digital%2Fteamcity-build-number/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nice-digital%2Fteamcity-build-number/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nice-digital","download_url":"https://codeload.github.com/nice-digital/teamcity-build-number/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nice-digital%2Fteamcity-build-number/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263649258,"owners_count":23494007,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["build","build-automation","build-tools","nodejs","teamcity"],"created_at":"2024-09-30T19:15:10.074Z","updated_at":"2025-07-11T05:39:19.088Z","avatar_url":"https://github.com/nice-digital.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TeamCity build number\n\n\u003e Sets the TeamCity build number based on the branch or Pull Request.\n\n[![npm](https://img.shields.io/npm/v/@nice-digital/teamcity-build-number.svg)](https://www.npmjs.com/package/@nice-digital/teamcity-build-number)\n[![License](https://img.shields.io/github/license/nice-digital/teamcity-build-number.svg)](https://github.com/nice-digital/teamcity-build-number/blob/master/LICENSE)\n[![Dependencies](https://img.shields.io/david/nice-digital/teamcity-build-number.svg)](https://david-dm.org/nice-digital/teamcity-build-number)\n[![Dev dependencies](https://img.shields.io/david/dev/nice-digital/teamcity-build-number.svg)](https://david-dm.org/nice-digital/teamcity-build-number?type=dev)\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTable of contents\u003c/strong\u003e\u003c/summary\u003e\n\n- [TeamCity build number](#teamcity-build-number)\n\t- [What is it?](#what-is-it)\n\t- [Local development](#local-development)\n\t- [Build number format](#build-number-format)\n\t- [Usage](#usage)\n\t- [Options](#options)\n\t\t- [branch](#branch)\n\t\t- [usePackageJsonVersion](#usepackagejsonversion)\n\t\t- [gitHubToken](#githubtoken)\n\t\t- [gitHubRepo](#githubrepo)\n\t\t- [packageRelativePath](#packagerelativepath)\n\t\t- [enforceNamingConvention](#enforcenamingconvention)\n\t- [Debugging this module](#debugging-this-module)\n\t- [TeamCity config](#teamcity-config)\n\t\t- [Update npm](#update-npm)\n\t\t- [Branch specification](#branch-specification)\n\u003c/details\u003e\n\n\n## What is it?\n\nCommand line tool to set the build number based on the branch or pull request within TeamCity.\n\nDesigned 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](#options) below).\n\nThis can be used as a cross-platform replacement for the 'GitFlow' PowerShell build step.\n\n## Local development\n\nUse the _example_ folder for local development and testing.\n\n## Build number format\n\nWe 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 `+`\n\nAs an example the build number format is in the form:\n\n**Pre-release:**\n\nMajor.Minor.Patch.Counter-BranchName\n\n**Release:**\n\nMajor.Minor.Patch.Counter+rCommitHash\n\nNote: the following examples assume a version of *1.2.3*, a build counter of *99* and a commit hash of *a1b2c3d*:\n\n| Branch                     | Version              |\n| -------------------------- | -------------------- |\n| master                     | 1.2.3.99+ra1b2c3d    |\n| pull request (from branch) | 1.2.3.99-branch-name |\n| feature branch             | 1.2.3.99-branch-name |\n\n**Visual Studio 2015 and nuget packages**\n\nPlease 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\n\n**TeamCity and Nuget restore**\n\nSemver 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.\n\n## Usage\n\nWith npm\u003e=5.2, use the Command Line Interface via npx:\n\n```sh\nnpx @nice-digital/teamcity-build-number --branch=%teamcity.build.branch% --usePackageJsonVersion --gitHubToken=%GITHUB_TOKEN% --gitHubRepo=%system.GitHubOwnerRepo%\n```\n\n## Options\n\n### branch\n\n- Type: `String`\n- Required: `true`\n- CLI alias: `b`\n- Example: `--branch=%teamcity.build.branch%`\n\nThe branch to build from e.g. `%teamcity.build.branch%`\n\n### usePackageJsonVersion\n\n- Type: `Boolean`\n- Required: `false`\n- Default: `false`\n- Example: `--usePackageJsonVersion`\n\nWhether 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`.\n\nNote: in v0.x this option could be used like `--usePackageJsonVersion=true` but this is no longer the case.\n\nNote 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.\n\n### gitHubToken\n\n- Type: `String`\n- Required: `true` to build Pull Requests\n\nA GitHub authentication token. Used for getting details of a Pull Request from the GitHub API. Must have access to the repository set in `gitHubRepo`.\n\n### gitHubRepo\n\n- Type: `String`\n- Required: `true`\n- Example: `--gitHubRepo nice-digital/guidance-web`\n\nThe GitHub organisation (or username) and repository to check for status of Pull Requests etc.\n\n### packageRelativePath\n\n- Type: `String`\n- Required: `false`\n- Example: `--packageRelativePath src/client`\n\nIf no value is supplied the package.json file will be looked for in the root of the repository. \nIf a value is given such as \"src\", then it will look for said file in \"[repo root]\\src\\package.json\"\n\n### enforceNamingConvention\n\n- Type: `Boolean`\n- Required: `false`\n- Example: `--enforceNamingConvention`\n\nIf no value is supplied the naming conventions on the branch and pull request names are not enforced. \nIf present (which means `true`) then the naming conventions are enforced and the build will be cancelled with the reason logged.\n\nNote: in v0.x this option could be used like `--enforceNamingConvention=true` but this is no longer the case.\n\n## Debugging this module\n\nTo debug this module run a command like the following:\n\n```sh\nnode --inspect-brk bin/cli.js --branch mybranch --gitHubToken mytoken --gitHubRepo myrepo --usePackageJsonVersion\n```\n\nthen navigate chrome to:\n\n[chrome://inspect](chrome://inspect)\n\na \"Remote target\" should pop up. Just click 'inspect' and chrome dev tools will debug the script.\n\n## TeamCity config\n\n### Update npm\n\nIf you're using NVM or an npm version \u003c 5.2 then you might need to run the following command before setting the build number:\n\n```sh\nnpm install -g npm\n```\n\n\u003e Note: if you're using a build agent with Node.js \u003e= 8.2.0 this should have npm \u003e= 5.3 pre-installed so you might not need to update npm.\n\n### Branch specification\n\nWe recommend the following branch specification for your VCS root (\n Build Configuration Settings -\u003e Version Control Settings -\u003e VCS Roots -\u003e Branch specification). This automatically builds master.\n\n```sh\n+:refs/heads/(master)\n```\n\nDO 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.\n\nSee [Building GitHub pull requests with TeamCity](https://blog.jetbrains.com/teamcity/2019/08/building-github-pull-requests-with-teamcity/) on the JetBrains blog for more info.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnice-digital%2Fteamcity-build-number","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnice-digital%2Fteamcity-build-number","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnice-digital%2Fteamcity-build-number/lists"}