Integrations Overview and API

Retrace provides a simple HTTP API for tracking deployments. We have created recipes or plug-ins for some of the most popular deployment tools.

Please view their specific examples to walkthrough how to configure them. If you do not see your deployment tool listed, you can probably adapt our example scripts below within your deployment tool.

• AppVeyor
• Atlassian Bamboo
• AWS CodePipeline
• CircleCI
• Jenkins
• Octopus Deploy
• TeamCity
• Visual Studio Team Services

You can also use our API directly via Bash or PowerShell as part of your deployment scripts. Examples are provided below.

API Basics

Our API exposes command endpoints that can start, complete, or cancel a deployment request.

https://api.stackify.net/api/v1/deployments/start

All API requests are matched up by the specified app name, environment, and version. These should be specified in every API call.

Available fields to send via the API:

• ApiKey - Required Stackify license key for your account so that we can identify and authenticate your account
• AppName - Important so that Retrace can match the request to your app*
• EnvironmentName - Important so that Retrace can update the proper environment. QA, Prod, etc*
• Name - Description, name, or version for the deployment
• Branch - The name of your branch
• Commit - The hash of the commit to track exactly what code was deployed
• Uri - A URL to the build or commit to easily reference
• Version - Specify a version number of your product

*AppName and EnvironmentName values sent via the API must match to a corresponding App / Environment name existing in the Retrace portal.

Authentication

Authentication is performed by setting the request authorization header in the following format, where ApiKey is the client's specific activation key.

Authorization: ApiKey {API_KEY}

Automating Deployments with Bash

Below are examples of how to use our API with Bash.

Starting a Deployment

curl -X POST 
    https://api.stackify.net/api/v1/deployments/start 
    -H 'authorization: ApiKey  ENTER_YOUR_LICENSE_KEY' 
    -H 'content-type: application/json' 
    -d '{
        "Name": "BourneAgain",
        "Uri": "localhost",
        "Branch": "master",
        "Commit": "rOapzPyAtzUR9s7yDJYlGz2vUYbcl0P6gMVglrygJ2",
        "Version": "v1.0",
        "AppName": "FooApp",
        "EnvironmentName": "Prod"
}'

Cancel a Deployment

curl -X POST 
    https://api.stackify.net/api/v1/deployments/cancel 
    -H 'authorization: ApiKey ENTER_YOUR_LICENSE_KEY' 
    -H 'content-type: application/json' 
    -d '{
        "Version": "v1.0",
        "AppName": "FooApp",
        "EnvironmentName": "Prod"
}'

Deployment Completed

curl -X POST 
    https://api.stackify.net/api/v1/deployments/complete 
    -H 'authorization: ApiKey ENTER_YOUR_LICENSE_KEY' 
    -H 'content-type: application/json' 
    -d '{
        "Version": "v1.0",
        "AppName": "FooApp",
        "EnvironmentName": "Prod"
}'

Automating Deployments with PowerShell

Below is a PowerShell script that we put together than can be easily reused for different scenarios. We would suggest downloading this next code snippet and saving it as stackify-deploy.ps1. Below we have some examples of how you would then use it.

Param(
        [Parameter(Mandatory=$True,Position=0)]
        [ValidateSet('complete','start','cancel')]
        [string]$action,
        [Parameter(Mandatory=$True)][string]$apiKey,
        [Parameter(Mandatory=$True)][string]$version,
        [Parameter(Mandatory=$True)][string]$app,
        [Parameter(Mandatory=$True)][string]$env,
        [Parameter(Mandatory=$False)][string]$uri,
        [Parameter(Mandatory=$False)][string]$name,
        [Parameter(Mandatory=$False)][string]$branch,
        [Parameter(Mandatory=$False)][string]$commit,
        [Parameter(Mandatory=$False)][string]$hostApi
)

# build the post url
if (!$hostApi) { $hostApi= 'https://api.stackify.net' }

$post = $hostApi.TrimEnd('/') + '/api/v1/deployments/' + $action

# build the authorization header
$headers = @{'authorization'='ApiKey ' + $apiKey}

# build the body of the post
if (!$name) { $name = $version }

$bodyObj = @{ Version=$version; AppName=$app; EnvironmentName=$env; }

if ($action -eq "start" -or $action -eq "complete"){
        $bodyObj.Name = $name
        if ($uri) { $bodyObj.Uri = $uri }
        if ($branch) { $bodyObj.Branch = $branch }
        if ($commit) { $bodyObj.Commit = $commit }
}

$body = ConvertTo-Json $bodyObj

# send the request
Invoke-WebRequest -Uri $post -Method POST -ContentType "application/json" -Headers $headers -Body $body

Starting a Deployment

ps > .\stackify-deploy.ps1 start -apiKey "ENTER_YOUR_LICENSE_KEY" -app "FooApp" -env "Prod" -version "v1.0" -name "BourneAgain" -branch "master" -commit "ca35857d2cc6050a2525491840922a6d5d359006" -uri "localhost"

ps > .\\stackify-deploy.ps1 complete -apiKey "ENTER_YOUR_LICENSE_KEY" -app "FooApp" -env "Prod" -version "v1.0"

Cancel a Deployment

ps > .\stackify-deploy.ps1 cancel -apiKey "ENTER_YOUR_LICENSE_KEY" -app "FooApp" -env "Prod" -version "v1.0"

Deployment Completed

ps > .\\stackify-deploy.ps1 complete -apiKey "ENTER_YOUR_LICENSE_KEY" -app "FooApp" -env "Prod" -version "v1.0" -name "BourneAgain" -branch "master" -commit "ca35857d2cc6050a2525491840922a6d5d359006" -uri "localhost"