{"id":17093025,"url":"https://github.com/peter-murray/node-teamcity-api","last_synced_at":"2025-04-12T22:45:00.880Z","repository":{"id":42991074,"uuid":"44633133","full_name":"peter-murray/node-teamcity-api","owner":"peter-murray","description":"Node.js library wrapper for the TeamCity RESTful API","archived":false,"fork":false,"pushed_at":"2023-03-04T04:32:13.000Z","size":295,"stargazers_count":10,"open_issues_count":7,"forks_count":13,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-12T22:44:54.402Z","etag":null,"topics":["nodejs","teamcity"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/peter-murray.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-10-20T20:29:55.000Z","updated_at":"2024-05-03T03:58:01.000Z","dependencies_parsed_at":"2024-06-19T06:16:53.633Z","dependency_job_id":"8e7155ca-35e0-43a5-b2c2-336ccfad048c","html_url":"https://github.com/peter-murray/node-teamcity-api","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-murray%2Fnode-teamcity-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-murray%2Fnode-teamcity-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-murray%2Fnode-teamcity-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-murray%2Fnode-teamcity-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/peter-murray","download_url":"https://codeload.github.com/peter-murray/node-teamcity-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248643047,"owners_count":21138353,"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":["nodejs","teamcity"],"created_at":"2024-10-14T14:04:18.182Z","updated_at":"2025-04-12T22:45:00.846Z","avatar_url":"https://github.com/peter-murray.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Node.js TeamCity REST API Library\n\nA Node.js API wrapper around the TeamCity RESTful API to make it easy to use.\n\n## Installation\nTo use the library in Node.js, install it using npm:\n\n```npm install teamcity-rest-api```\n\n## API Style\nThis library has been writtne to support Node.js 4.x and native promises, \nthere are no callbacks from any of the functions.\n\n\n# Examples\n\n## Creating the Client\nYou can instantiate the API client using the `create()` function with a\n`URL` or `configuration` object.\n\nIf you use the `URL`, you will be connected to the `guest` RESTful API endpoints.\nThis will require that you have guest access turned on in the TeamCity Server\nthat you are connecting to. Note that not all endpoints are accessible\nvia the `guest` API.\n\n### Connecting Using a URL\n\n```js\nvar teamcity = require(\"teamcity-rest-api\");\n\nvar client = teamcity.create('http://localhost:8111')\n```\n\n### Connecting Using a Configuration Object\n\nYou must use the `configuration` object if you need to connect to the authenticated\nRESTful API endpoints. The `configuration` object allows you to pass in the\nusername and password values.\n\nThe `configuration` object can have a number of properties which consist of:\n\n * `url` The full URL for the TeamCity server, e.g. http://teamcity.domain.com:8111\n * `protocol` The protocol for the connection, e.g. http\n * `hostname` The hostname of the server, e.g. teamcity.domain.com\n * `port` The port for the TeamCity server, e.g. 8111\n * `username` The username if using authenticated endpoints\n * `password` The password for the user you are authenticating as\n\nYou can specify a full `url` or the combination of `protocol`, `hostname` \nand an optional `port` depending upon your needs. If you choose to provide a\n`url` along with any other parameters, the `url` will be used and the others\nignored.\n\nIf no authentication details are provided (`username` and `password`) the \nconnection to TeamCity will be performed as a guest. This will require\nguest access to be turned on in the TeamCity Server. If using guest access, \nsome API endpoints may be unavailable, based on the access settings of the TeamCity Server.\n\nUser authentication details can be provided using `user` or `username` for the \nusername to connect as and `password` or `pass` for the password for the user. Both a \nusername and password must be provided for the API to attempt to connect with the \nTeamCity server, otherwise it will fall back to using a guest connection.\n\nConnecting to the TeamCity server with a `url` parameter:\n```js\nvar teamcity = require(\"teamcity-rest-api\");\n\nvar client = teamcity.create({\n    url: \"http://localhost:8111\",\n    username: \"user\",\n    password: \"pass\"\n});\n```\n\nConnecting to the TeamCity server with a `protocol`, `hostname` and `port`:\n```js\nvar teamcity = require(\"teamcity-rest-api\");\n\nvar client = teamcity.create({\n    url: \"http://localhost:8111\",\n    username: \"user\",\n    password: \"pass\"\n});\n```\n\n## TeamCity Version Numbers\nThe TeamCity Server has two version numbers that it can report once connected. These are available as a guest or an\nauthenticated user.\n\nThe two version numbers are that of the TeamCity Server software and the other being that of the RESTful API version.\n\n### Getting the TeamCity Version\n\n```js\nvar teamcity = require(\"teamcity-rest-api\")\n  , client = teamcity.create(\"http://localhost:8111\")\n  ;\n\nclient.getVersion()\n  .then(function(version) {\n    console.log(\"TeamCity Server version: \" + version);\n  })\n  .catch(function(err) {\n    console.error(err.message);\n  });\n```\n\n### TeamCity API Version\nThe API version is a major.minor version number as a string that matches\nthe version of TeamCity, e.g. for 9.1.4 it is \"9.1\".\n\n```js\nvar teamcity = require(\"teamcity-rest-api\")\n  , client = teamcity.create(\"http://localhost:8111\")\n  ;\n\nclient.getApiVersion()\n  .then(function(version) {\n    console.log(\"TeamCity Server version: \" + version);\n  })\n  .catch(function(err) {\n    console.error(err.message);\n  });\n```\n\n## Projects\nThe API provides a `project` object for interacting with various Project\nrelated activities.\n\n### teamcity.projects.create - Create a Project\nTo create a project use the `client.projects.create()` function:\n\n```js\nvar teamcity = require(\"teamcity-rest-api\")\n  , client = teamcity.create({\n    url: \"http://localhost:8111\",\n    username: \"user\",\n    password: \"pass\"\n  })\n  ;\n\nclient.projects.create()\n  .then(function(project) {\n    console.log(JSON.stringify(project, null, 2));\n  })\n  .catch(function(err) {\n    console.error(err.message);\n  });\n```\n\n## Builds\nThe API provides a `builds` object to interact with Build Configurations.\n\n### teamcity.builds.get - Get a specific build\n```js\nclient.builds.get({id: 100})\n  .then(function(build) {\n    console.log(build.state)\n  });\n```\n\n### teamcity.builds.getByBuildTypeWithCount and getByProjectWithCount - Get a list of builds for a configuration\nThese methods provide different ways to get a list of builds of a specific build configuration.\nTo list builds by the name or ID of a build config, use `getByBuildTypeWithCount`.\nTo list builds for a particular project, use `getByProjectWithCount`.\nBoth of these methods do not apply default filtering from TeamCity, so you will get in-progress builds as well.\n\n```js\nclient.builds.getByBuildTypeWithCount({id: \"BuildConfigId\"}, {dimensions: {count:10}})\n  .then(function(buildList){\n    console.log(buildList.build[0]) //buildList.build is an array of builds, from most recent to the count parameter\n  });\n\nclient.builds.getByProjectWithCount({name: \"TestBuildProject\"}, {dimensions: {count:10}})\n  .then(function(buildList){\n    console.log(buildList.build[0].id) //build id can be passed to builds.get for more detailed info\n  });\n```\n\nThe TeamCity API documentation has more examples of dimensions that can be passed into these lookups.\n\n### teamcity.builds.startBuild - Run a build configuration.\nThis method allows you to start a build configuration; It'll return the build number of the running build.\n\n```js\nvar buildNodeObject = \"\u003cbuild\u003e \u003cbuildType id=\\\"TestConfigId\\\" /\u003e \u003c/build\u003e\"\nclient.builds.startBuild(buildNodeObject)\n  .then(function(buildStatus) {\n    console.log(buildStatus.id)\n  });\n```\n\nRefer to the TeamCity REST API documentation for more info on what can be passed as a buildNode.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeter-murray%2Fnode-teamcity-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeter-murray%2Fnode-teamcity-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeter-murray%2Fnode-teamcity-api/lists"}