Automate the sending of VSTS Release Summary emails

Posted on Posted in VSTS

Release Sum­ma­ry emails are a great way to share details about a release, includ­ing which envi­ron­ments with sta­tus, relat­ed work items, and relat­ed bugs. While view­ing a release's details, click on the Send Email but­ton to send out a Release Summary.

No option exists in VSTS (yet) to auto­mat­i­cal­ly send a Release Sum­ma­ry email, so we'll use a quick Pow­er­Shell script to make the same API call that the VSTS web app makes. After send­ing a Release Sum­ma­ry email that is close to what we need and cap­tur­ing the request body in Devel­op­er Tools, we use the fol­low­ing script to call the API.

$uri = $env:SYSTEM_TEAMFOUNDATIONSERVERURI + $env:SYSTEM_TEAMPROJECT + "/_apis/Release/sendmail/" + $env:RELEASE_RELEASEID
"Sending Release Email at " + $uri

$requestBody = "{""senderType"":1,""to"":{""tfsIds"":[""abcd1c6e-5a10-4d63-8a1f-abcd54c50704""],""emailAddresses"":[]},""subject"":""Automated Release Summary / Release-34 summary"",""cc"":{""tfsids"":[""efgh1c6e-5a10-4d63-8a1f-abcd54c50704""]},""sections"":[5,0,1,2,4]}"

$accessToken = $env:SYSTEM_ACCESSTOKEN
$auth = "Bearer $accessToken"
$accept = "*/*;api-version=3.2-preview.1;excludeUrls=true"
$headers = @{authorization=$auth;accept=$accept}

$contentType = "application/json"

Invoke-RestMethod -Uri $uri -Body $requestBody -Method Post -Headers $headers -ContentType $contentType

A few things to note

  • The script is mak­ing a web request and needs some way to authen­ti­cate with VSTS. We use the $env:SYSTEM_ACCESSTOKEN envi­ron­ment vari­able to get the OAuth token from Release Man­age­ment. We need to tell the build agent to pro­vide us with the OAuth token for this envi­ron­ment vari­able to be populated.
  • The request body requires valid VSTS users ref­er­enced by their tfsIds. You can eas­i­ly cap­ture the cor­rect pay­load by per­form­ing a Send Release Sum­ma­ry in VSTS while run­ning Devel­op­er Tools. While emailAd­dress­es is a prop­er­ty of to, it has been ignored in all of my tests and only tfsIds get picked up.
  • Because this script is being run dur­ing the release, the sum­ma­ry email will show the envi­ron­ment as IN PROGRESS even if it is run as the last step in the Release. I've yet to find a bet­ter solu­tion to this until VSTS offers the option to auto­mate the email.
  • This is brit­tle. I could find no doc­u­men­ta­tion of this API. We're using the 3.2-preview.1 API which could change or be removed. Do not be sur­prised if this breaks with a future update.

With this script plugged into a Pow­er­Shell build step task, we can now trig­ger Release Sum­ma­ry emails when­ev­er we desire.

Leave a Reply

Your email address will not be published. Required fields are marked *