Home / deployment / Using the Pivotal Tracker API to automatically deliver stories

Using the Pivotal Tracker API to automatically deliver stories

Like many agile shops, our company uses PivotalTracker as our project management system. Our QA deployment process is nearly completely automated, but we still had to manually log in to Pivotal to “deliver” the stories after everything was successfully pushed to QA. Not a difficult task to be sure, but the build server typically works after hours, and QA is offshore on the other side of the world, so there was always a disconnect between what was marked as delivered in Pivotal and what was actually delivered to the QA environments.

Fortunately the Pivotal has an API that is very easy to work with. To get an API key simply log in to Pivotal, go to your profile page and scroll down. This token should be included in the header of each request. For my integration, I chose to develop a simple PowerShell script since we use PowerShell extensively on the build server already:

# call the Pivotal API to search for all finished stories, labeled with the tag for this release 
$webClient = new-object System.Net.WebClient 
$webClient.headers.Add('X-TrackerToken', $pivotalToken) 
$url = "http://www.pivotaltracker.com/services/v3/projects/{0}/stories?filter=label%3A%22{1}%22%20state%3Afinished" -f $pivotalProjectId, $tag 
$data = $webClient.DownloadString($url)
# parse the XML
[xml]$storiesXml = [xml]($data)
# read all of the stories, and save their ids into an array
 $finishedStories = @()
 foreach ($story in $storiesXml.stories.story)
     $storyId = $story.selectSingleNode('id').get_innerXml()
     $finishedStories += $storyId;
# prepare to PUT XML
 foreach ($storyId in $finishedStories)
     $url = "http://www.pivotaltracker.com/services/v3/projects/{0}/stories/{1}" -f $pivotalProjectId, $storyId
     $webClient.headers.Add('Content-type', 'application/xml')
     $webClient.UploadString($url, 'PUT', "delivered")

Any scripting language or a simple console app would do. Pivotal also has an API method to deliver all stories that are marked as finished, but we needed to only deliver stories matching a certain tag, hence the initial search and looping through those stories.

You can read more about the Pivotal API from their web site: