Triggering a release using a build tag in VSTS

For most cases triggering a release based on finished builds on a specific branch from your repo is sufficient. But what if you'd like to have a little more control over what is released depending on some specific conditions? Well you could create different build definitions, specify different triggers on so on. In this post I'll present you a little feature, which you could find helpful in some specific scenarios.

Build tags

Each finished build in VSTS can be marked with a custom tag, which will help to categorize it. You can even think about building a "tag pipe" like this:

  • #compilation_finished
  • #packages_downloaded
  • #artifacts1_copied
  • #...

which would help you to decided what to do depending on at which step your build failed.


Finished build with a "Tag_ToBuild" tag attached. 

There's one issue with tags however - you have to add them manually. What if you'd like to automate things?

Adding a build tag

Some time ago the team responsible for VSTS introduced a new command, which can be used to add a build tag directly from a build. To use it you can do following:

  • add a new Powershell build step to your build definition
  • paste following command:  Write-Host "##vso[build.addbuildtag]your_tag"

With this simple script each finished build will have your_tag attached to it. At first glance it doesn't look very impressively, but when you consider passing a variable or using output from the previous steps, it becomes much more powerful.

Triggering a release

So far so good - we now how to automate tags so it's possible to incorporate them in our releases. To do so go to your release definition and then click on the "Triggers" tab.

"Triggers" tab with a tag added to constrain CD a little 

Along with artifact source and branch triggers triggers you have an option to add tags, which will be used to check whether a release should be triggered. Now each time a build finishes, a release won't triggered unless specific tag was provided.


Connect a release to a build in VSTS

For some reason there's no easy way to connect a release to a build when using REST API provided by VSTS. Something which should be fairly trivial seems like a task, which is impossible to finish. However there's a "dirty" way of finding a build identifier, which is related to a release we're interested in.

Digging into release data

Let's consider following request:


When called it'll returns a detailed information about a release including approvals, deployment steps, workflow and many more. When you dig deeper into a response, you'll find one section, which may help us here:

"artifacts": [{
	"sourceId": "{sourceId}",
	"type": "Build",
	"alias": "some_alias",
	"definitionReference": {
		"artifactSourceDefinitionUrl": {
			"id": "https://{account}",
			"name": ""
		"definition": {
			"id": "{definitionId}",
			"name": "Name"
		"project": {
			"id": "{projectId}",
			"name": "Name"
		"version": {
			"id": "5854",
			"name": "2017.97"
		"artifactSourceVersionUrl": {
			"id": "https://{account}",
			"name": ""
		"defaultVersionType": {
			"id": "selectDuringReleaseCreationType",
			"name": "Specify at the time of release creation"
		"branch": {
			"id": "refs/heads/develop",
			"name": "refs/heads/develop"
	"isPrimary": true

Of course I obscured it a little, but you should be able to get the picture. In the artifactSourceVersionUrl property you can see a URL, which itself isn't helping much. What we're interested in is the very end of it - it the query string it contains a buildId key, which directly points to the build used for this release. The only thing you have to do is to parse the JSON and extract identifier, which can be used further to query for a build.


Although REST API provided by VSTS is really helpful in most cases, this time I was really confused. Fortunately even indirect solutions are still solutions so as long as there's no other API version, this workaround seems valid uncomplicated.