Centric connect.engage.succeed

Trigger a release in an external TFS farm or VSTS

Geschreven door Hans Oude Middendorp - 24 oktober 2017

Hans Oude Middendorp
I recently stumbled on a problem that required the ability to trigger a release outside the project and even outside our on-premises TFS farm. To tackle this, I created a custom build/release task that enables creating a release in another TFS project, project collection, farm or in VSTS.


The solution is based on the REST API that comes with TFS or is available in VSTS. This API is described here. We will use two methods:

  • get release definitions
  • create a release

We use a personal access token to authenticate the calls to the API. I explain how to create a personal access token in my blog post: Custom build/release management task to execute a SQL script.

Encode the personal access token:

$base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f "", $personalAccessToken)))

The URI definition for VSTS:

$uri = "https://$($vstsAccount).vsrm.visualstudio.com/DefaultCollection/$($projectName)/_apis/release/definitions?api-version=3.0-preview.2"

And for TFS:

$uri = "$($TFSUri)/$($projectName)/_apis/release/definitions?api-version=3.0-preview.2"

Invoke the REST call and capture result:
$result = Invoke-RestMethod -Uri $uri -Method Get -ContentType "application/json" -Headers @{Authorization=("Basic {0}" -f $base64AuthInfo)}

From the list of definitions, we will select the right one by filtering by name, which we ask for in the task setup. We store the ID in the variable $releaseID.

Once a release definition has been selected, we create a new release by using the second method, giving a body with no artifact description:

$body = '{
  "definitionId": ' + $releaseID + ',
  "description": "' + $releaseDescription + '"

The variable $releaseDescription comes from the task setup page.

To start the release we call another REST method. For VSTS:

$uri = "https://$($vstsAccount).vsrm.visualstudio.com/DefaultCollection/$($projectName)/_apis/release/releases?api-version=3.0-preview.2"
And for TFS:

$uri = "$($TFSUri)/$($projectName)/_apis/release/releases?api-version=3.0-preview.2"
The method is invoked like this:

$releaseresponse = Invoke-RestMethod -Method Post -ContentType application/json -Uri $uri -Headers @{Authorization=("Basic {0}" -f $base64authinfo)} -Body $body
Using the custom task

The task can be used in a build or release definition.

The task can be used in a build or release definition

If you select Visual Studio Team Services, you will need to enter a VSTS Account Name, i.e. the part between “https://” and “.visualstudio.com".

Screen Visual Studio Team Services

If Team Foundation Server is used, you will need to enter the full URI to the TFS instance, including protocol, port and project collection name. For example:




The Release Description field is used to enter a comment on the release.

You can find the complete sources of this solution on GitHub. To find out how to install this solution in your own environment, you can read my blog post Custom build/release management task to execute a SQL script.

About Hans

Craft Expert Hans Oude Middendorp is part of the ALM team within Craft, the development programme for IT professionals (powered by Centric). If you would like to follow his blog, sign up for Craft updates.

Want to know more about Craft, the development programme for IT professionals? Check out the Craft website!


Schrijf een reactie
  • Captcha image
  • Verzenden