Manage Finished Builds
In this article, we explore common use cases of managing finished builds via TeamCity REST API:
Operating build tags.
Pining and unpinning builds.
Retrieving artifacts and build parameters.
Labeling builds.
To get tags for a specific build, use:
GET/app/rest/builds/<buildLocator>/tags
where buildLocator
is a BuildLocator entity. The endpoint responds with a Tags entity.
To add new tags, use:
POST/app/rest/builds/<buildLocator>/tags
It accepts either Tags
:
<tags>
<tag name="tag1"/>
<tag name="tag2"/>
</tags>
{
"tag": [
{
"name": "tag1"
},
{
"name": "tag2"
}
]
}
or a text/plain
tag name as a body.
To replace existing tags, send Tags
entity via
PUT/app/rest/builds/<buildLocator>/tags
To check if the build is pinned, use:
GET/app/rest/builds/<buildLocator>/pin
To pin a build, use:
PUT/app/rest/builds/<buildLocator>/pin
Any text (text/plain
) sent with this request will be used as a comment.
To unpin a build, use:
DELETE/app/rest/builds/<buildLocator>/pin
Any text (text/plain
) sent with this request will be used as a comment.
To find all existing VCS labels of a build, use:
GET/app/rest/builds?locator=<buildLocator>&fields=build(id,vcsLabels:$long)
Or use a dedicated endpoint:
GET/app/rest/builds/<buildLocator>/vcsLabels?fields=status,text
To add a new VCS label, use:
POST/app/rest/builds/<buildLocator>/vcsLabels?locator=<vcsRootInstanceLocator>&fields=build(id,vcsLabels)
where vcsRootInstanceLocator
is typed as VcsRootInstanceLocator. The request accepts text/plain
.
To get a content of a specific artifact, use:
GET/app/rest/builds/<build_locator>/artifacts/content/<path>
where path
can be empty for the root of the build's artifacts or be a path within the build's artifacts. The path
can span into the archive content, for example, dir/path/archive.zip!/path_within_archive
.
Media-Type
of response is usually application/octet-stream
or a more specific type (determined by the artifact file extension).
To get the file metadata, use:
GET/app/rest/builds/<build_locator>/artifacts/metadata/<path>
To fetch all child items for a directory or archive, use:
GET/app/rest/builds/<build_locator>/artifacts/children/<path>
To download a certain archived subpath, use:
GET/app/rest/builds/<build_locator>/artifacts/archived/<path>?locator=pattern:<wildcard>
An optional locator's parameter is wildcard
that allows limiting files only to those matching the wildcard. artifact relative name
supports referencing files under archives using the !/
delimiter after the archive name.
Media-Type
of response is application/zip
.
Download all zip archives combined into a single .zip. Since the
path
is empty, artifacts are downloaded from the root artifact directory. The target build is the specific build with the "7703" ID.GET/app/rest/builds/7703/artifacts/archived/?locator=pattern:*.zip
Combine three specific files from the
bin/debug
folder into a single "production.zip" archive and download it. The artifacts are downloaded from the latest successful finished build.GET/app/rest/builds/buildType:MyProject_MyConfig,status:SUCCESS,state:finished/artifacts/archived/bin/debug?locator=pattern:(mylib.dll,setup.cfg,setup.log)&name=production.zip
Download a file stored inside the "subfolder1/subfolder2" directory of the "result.zip" archive.
GETapp/rest/builds/buildType:MyProject_MyConfig,status:SUCCESS,state:finished/artifacts/archived/result.zip!/subfolder1/subfolder2?locator=pattern:textfile1.txt
To get resulting build parameters of a specific finished build, use:
GET/app/rest/builds/id:<build_id>/resulting-properties
Thanks for your feedback!