Deployments API

Documentation - Deployment Tracking Using Raygun

Use Raygun’s deployment tracking capabilities to be alerted to issues caused by bad releases.

When new deployments are made, Raygun keeps a watchful eye on your application for issues that have been created. You’ll be able to see exactly when a problem was introduced, with all the information needed to fix things before they cause you bigger problems. When you’re shipping software your customers rely on, Raygun is your safety net, should things not go as expected.

deployment tracking

Tracking Deployments Alongside Errors

With Deployment Tracking enabled, Raygun lets you view your deployments alongside your exisitng Crash Reporting error chart. This allows you to quickly determine how particular deployments are performing, with respect to errors in your application.

Deployments API Endpoint

POST https://app.raygun.io/deployments

Data

The body of the message should be a JSON string with the following structure:

{
    apiKey: string,
    version: string,
    ownerName: string,
    emailAddress: string,
    comment: string,
    scmIdentifier: string,
    scmType: string,
    createdAt: ISO 8601 datetime
}

apiKey

The API Key of your Raygun Application

version

The version of your Application that this deployment is releasing. Should be the same as the version string you use in your Raygun error reports.

ownerName

Optional The name of the person who is creating this deployment. Ideally should be a Raygun User.

emailAddress

Optional The email address of the person who is creating this deployment. Ideally should be a Raygun User's email address.

comment

The deployment notes. This will be parsed as Markdown.

scmIdentifier

The commit that this deployment was built off. If this is a Git commit hash and you have a source control integration set up, we will attempt to gather information about the changes made since your last deployment.

scmType

The source control system you use, used to gather up changes since your last deployment.

Valid types

  • Github (defaults to Github)
  • GitLab
  • BitBucket

createdAt

Optional The date and time this deployment was released in ISO 8601 form. If this is omitted, we use the current time.

Authentication

This endpoint can be accessed via HTTP Basic Auth or Token Authentication.

For Basic Auth, use your normal Raygun user credentials (email address and password).

For Token Auth, generate an External Authentication Token on the Raygun User Settings Page and add an authToken query string parameter to the URL. For instance, if your API token is 123ABC, the URL would be https://app.raygun.io/deployments?authToken=123ABC.

Octopus Deploy

Documentation - Deployments in Raygun with Octopus Deploy

Registering Deployments with Octopus Deploy

Step 1

Generate an External Auth Token for your build server to use from your Raygun User Settings page

Step 2

Follow the instructions for setting up scripts to run directly on the Octopus Server. The rest of these instructions assume you chose to call your server role octopus-server.

Step 3

In Octopus, create a new "Run a PowerShell script" step in your deployment's Process. Give it a name, and choose the octopus-server role. This ensures your deployment is only registered once, instead of once per server your deployment runs on. Use the following powershell script in this step:

Write-Host "Adding deployment in Raygun"

$githubSha = ""
if ((Test-Path variable:\GithubToken) -And (Test-Path variable:\GithubRepo)) {
    try {
        $repo = "https://api.github.com/repos/" + $GithubRepo
        $tagName = "build-" + $OctopusParameters["Octopus.Action[DEPLOYMENT_STEP_NAME].Package.NuGetPackageVersion"]
        $githuburl = "$repo/git/refs/tags/"+ $tagName + "?access_token=" + $GithubToken
        $output = Invoke-RestMethod -Uri $githuburl
        $githubSha = $output.object.sha
    }
   catch {
        Write-Host "Couldn't find Git tag"
   }
}

$deploymentId = $OctopusParameters['Octopus.Release.Number']
$ownerName = $OctopusParameters['Octopus.Deployment.CreatedBy.DisplayName']
$emailAddress = $OctopusParameters['Octopus.Deployment.CreatedBy.EmailAddress']
$comment = $OctopusParameters['Octopus.Release.Notes'];

$command = ConvertTo-Json @{
    apiKey = $RaygunApiKey
    version = $deploymentId
    ownerName = $ownerName
    emailAddress = $emailAddress
    comment = $comment
    scmIdentifier = $githubSha
}

$url = "https://app.raygun.io/deployments?authToken=" + $RaygunAuthToken
try {
    Invoke-RestMethod -Uri $url -Body $command -Method Post -ContentType "application/json"
    Write-Host "Added deployment in Raygun"
} catch {
    Write-Host "Error received when adding deployment in Raygun: " $_
}

You need to replace DEPLOYMENT_STEP_NAME with the name of the step in your process which deploys your Nuget package. If you don't use Github, you could just remove that whole section, or replace it with your own code to get your Git commit hash.

Step 4

Add the following Variables to your deployment: RaygunApiKeyRaygunAuthTokenGithubToken, and GithubRepo.

RaygunApiKey should be set your Raygun Application's ApiKey (the same one you use to set Raygun up within your app).

RaygunAuthToken should be set to the External Auth Token you generated in Step 1. You may want to set different RaygunApiKey values depending on the Environment being deployed to if you have separate Raygun Apps for your different Environments.

GithubToken should be set to a Personal Access Token from Github (generated here: https://github.com/settings/applications). The token just needs the repo scope.

GithubRepo should be the full name of your repo - somethink like MindscapeHQ/Raygun4Net.

Step 5

Deploy your application and watch the Deployments roll in!

Bash

Documentation - Deployments to Raygun from Bash

Registering Deployments from a Bash Script

Step 1

Generate an External Auth Token for your build server to use from your Raygun User Settings page

Step 2

Add this script somewhere your deployment process can use it:

#!/bin/bash
RAYGUN_AUTH_TOKEN=""
RAYGUN_API_KEY=""
DEPLOYMENT_VERSION=""
DEPLOYED_BY=""
EMAIL_ADDRESS=""
DEPLOYMENT_NOTES=""
GIT_HASH=""
HELP=0

while getopts "t:a:v:n:e:g:h" opt; do
	case $opt in
	t)
		RAYGUN_AUTH_TOKEN=$OPTARG
		;;
	a)
		RAYGUN_API_KEY=$OPTARG
		;;
	v)
		DEPLOYMENT_VERSION=$OPTARG
		;;
	n)
		DEPLOYED_BY=$OPTARG
		;;
	e)
		EMAIL_ADDRESS=$OPTARG
		;;
    g)
		GIT_HASH=$OPTARG
		;;
    h)
        HELP=1
        ;;
	esac
done

shift $((OPTIND-1))

if [ $HELP -eq 1 ]
then
cat << EOF
usage: deployment.sh [-h] -v VERSION -t TOKEN -a API_KEY 
                      -e EMAIL -n NAME [-g GIT_HASH] NOTES
  h:          show this help
  v VERSION:  version string for this deployment
  t TOKEN:    your Raygun External Auth Token
  a API_KEY:  the API Key for your Raygun Application
  n NAME:     the name of the person who created the deployment
  e EMAIL:    the email address of the person who created the deployment.
              Should be a Raygun users email
  g GIT_HASH: the git commit hash this deployment was built from
  NOTES:      the release notes for this deployment. 
              Will be formatted using a Markdown parser
EOF
exit
fi

[ "$1" = "--" ] && shift

if [ "$1" != "" ]
then
    DEPLOYMENT_NOTES=$1
    DEPLOYMENT_NOTES=`echo $DEPLOYMENT_NOTES | sed s/\"/\\\\\\\\\"/g`
fi


url="https://app.raygun.io/deployments?authToken=$RAYGUN_AUTH_TOKEN"

read -d '' deployment <<- EOF
{
    apiKey: \"$RAYGUN_API_KEY\",
    version: \"$DEPLOYMENT_VERSION\",
    ownerName: \"$DEPLOYED_BY\",
    emailAddress: \"$EMAIL_ADDRESS\",
    scmIdentifier: \"$GIT_HASH\",
    comment: \"$DEPLOYMENT_NOTES\" 
}
EOF

curl -H "Content-Type: application/json" -d "$deployment" $url

if [ "$?" -ne "0" ]; then
  echo "Could not send deployment details to Raygun"
  exit 1
fi

Step 3

Call the deployment script after your release process is finished. 

deployment.sh [-h] -v VERSION -t TOKEN -a API_KEY 
                     -e EMAIL -n NAME [-g GIT_HASH] NOTES
  
  h:          show this help
  v VERSION:  version string for this deployment
  t TOKEN:    your Raygun External Auth Token
  a API_KEY:  the API Key for your Raygun Application
  n NAME:     the name of the person who created the deployment
  e EMAIL:    the email address of the person who created the deployment.
              Should be a Raygun user's email
  g GIT_HASH: the git commit hash this deployment was built from
  NOTES:      the release notes for this deployment. 
              Will be formatted using a Markdown parser

Powershell

Documentation - Deployments to Raygun from Powershell

Registering Deployments from a Powershell v4 Script

Step 1

Generate an External Auth Token for your build server to use from your Raygun User Settings page

Step 2

Add this script somewhere your deployment process can use it:

[CmdletBinding()]
Param(
    [Parameter(Mandatory=$True)]
    [string] $raygunAuthToken,
    [Parameter(Mandatory=$True)]
    [string] $raygunApiKey,
    [Parameter(Mandatory=$True)]
    [string] $version,
    [Parameter(Mandatory=$True)]
    [string] $ownerName,
    [Parameter(Mandatory=$True)]
    [string] $emailAddress,
    [Parameter()]
    [string] $scmIdentifier,
    [Parameter()]
    [string] $releaseNotes
)

Write-Debug "Adding deployment in Raygun"
$url = "https://app.raygun.io/deployments?authToken=" + $raygunAuthToken

$command = ConvertTo-Json @{ 
    apiKey = $raygunApiKey
    version = $version
    ownerName = $ownerName
    emailAddress = $emailAddress
    comment = $releaseNotes
	scmIdentifier = $scmIdentifier
}

$bytes = [System.Text.Encoding]::ASCII.GetBytes($command)
$web = [System.Net.WebRequest]::Create($url)
$web.Method = "POST"
$web.ContentLength = $bytes.Length
$web.ContentType = "application/json"
$stream = $web.GetRequestStream()
$stream.Write($bytes,0,$bytes.Length)
$stream.close()

$response = [System.Net.HttpWebResponse]$web.GetResponse()
if($response.StatusCode -eq [System.Net.HttpStatusCode]::OK) {
    Write-Debug "Added deployment in Raygun"
} else {
    Write-Host "Error received when adding deployment in Raygun: " $response.StatusCode " - " $response.StatusDescription
}

Step 3

Call the deployment script after your release process is finished.

-raygunAuthToken   Your External Auth Token
-raygunApiKey      Your Application's API Key
-version           The version of your application that you've just deployed
-ownerName         The name of the user who created this deployment
-scmIdentifier     The identifier of the commit that this release was built from.
-emailAddress      The email address of the user who created this deployment 
                   (should be a raygun user)
-releaseNotes      The release notes for this deployment. Will be formatted as Markdown.

Capistrano

Documentation - Deployments to Raygun from Capistrano

Registering Deployments with Capistrano

Step 1

Generate an External Auth Token for your build server to use from your Raygun User Settings page

Step 2

Install the capistrano-raygun-deployment gem

gem install capistrano-raygun-deployment

Or if you are using Bundler

echo "gem 'capistrano-raygun-deployment'" >> Gemfile
bundle install

Step 3

Add the following to your Capfile

require 'capistrano/raygun-deployment'

Step 4

Finally, add the following to your config.

set :raygun_api_key, "YOUR_APPLICATIONS_API_KEY"
set :raygun_auth_token, "YOUR_EXTERNAL_AUTH_TOKEN"
set :raygun_release_path, "releases/LATEST" #optional, defaults to RELEASE

This can either go in config/deploy.rb or in config/deploy/production.rb depending on whether you want it to run in every environment or not. We recommend having a separate Raygun Application per environment, so would suggest you put it in the environment specific config files.

Step 5

When you are ready to deploy, create a release file in RELEASE (or whatever release path you have chosen) with the following format:

version: 6.0.0.0
ownerName: Jamie Penney
emailAddress: jamie@example.com
notes: |
    # Testing out the rake plugin

    * More markdown formatting

    ### Jamie

Done

The next time you deploy, capistrano-raygun-deployment will register your deployment with Raygun!

Rake

Documentation - Deployments to Raygun from Rake

Registering Deployments with Rake

Step 1

Generate an External Auth Token for your build server to use from your Raygun User Settings page

Step 2

Install the rake-raygun-deployment gem

gem install rake-raygun-deployment

Or if you are using Bundler

echo "gem 'rake-raygun-deployment'" >> Gemfile
bundle install

Step 3

Add the following to your Rakefile

require 'rake-raygun-deployment'

Rake::RaygunDeployment.new(:raygun_deployment) do
    releasePath "RELEASE"
    authToken "YOUR_EXTERNAL_AUTH_TOKEN"
    apiKey "YOUR_APPLICATIONS_API_KEY"
end

Step 4

When you are ready to deploy, create a release file in RELEASE (or whatever release path you have chosen) with the following format:

version: 6.0.0.0
ownerName: Jamie Penney
emailAddress: jamie@example.com
notes: |
    # Testing out the rake plugin

    * More markdown formatting

    ### Jamie

Done

Run rake raygun_deployment to register your deployment with Raygun!

Grunt

Documentation - Deployments in Raygun with Grunt

Registering Deployments with Grunt

Step 1

Generate an External Auth Token to use from your Raygun User Settings page

Step 2

First, install the npm package:

npm install grunt-raygun-deployment --save-dev

Step 3

Then, add the following to Gruntfile.js:

grunt.initConfig({
    // Configuration to be run (and then tested).
    raygun_deployment: {
        options: {
            // You need to fill this in with your own data
            raygunApiKey: 'YOUR APPLICATIONS API KEY',
            raygunAuthToken: 'YOUR EXTERNAL AUTH TOKEN'
        }
    }
});

grunt.loadNpmTasks('grunt-contrib-uglify');

You'll need the Raygun API Key for your application, plus an External Auth Token which you can generate here.

If you don't want to check your ApiKey or AuthToken into source control, you can pass them to grunt as environment variables instead like this:

RAYGUN_APIKEY="YOUR APPLICATIONS API KEY" RAYGUN_AUTHTOKEN="YOUR EXTERNAL AUTH TOKEN" grunt raygun_deployment

Step 4

Finally, create a release file. We default to checking Release.yml, but you can set this path with therelease option.

This is an example release file:

version: 6.0.0.0
ownerName: Jamie Penney
emailAddress: jamie@example.com
notes: |
    # Testing out the rake plugin

    * More markdown formatting

    ### Jamie

Once you've written this to Releases.yml, run grunt raygun_deployment and your deployment will be sent to Raygun!

Atlassian Bamboo

Documentation - Deployments in Raygun with Atlassian Bamboo

 

Registering Deployments with Atlassian Bamboo

Step 1

Generate an External Auth Token for your build server to use from your Raygun User Settings page

Step 2 - Linux Hosts

In your Bamboo Deployment project, create a new Script task. Give it a description and use the following inline shell script as the script body:

# Run the script in bash rather than sh
if [ "$(ps -p "$$" -o comm=)" != "bash" ]; then
    bash "$0" "$@"
    exit "$?"
fi

url="https://app.raygun.io/deployments?authToken=${bamboo.raygun.authToken}"

read -d '' deployment <<- EOF
{
    apiKey: \"${bamboo.raygun.apiKey}\",
    version: \"${bamboo.deploy.version}\",
    ownerName: \"${bamboo.ManualBuildTriggerReason.userName}\",
    comment: \"${bamboo.resultsUrl}\"
}
EOF

echo "$deployment"

curl -H "Content-Type: application/json" -d "$deployment" $url

if [ "$?" -ne "0" ]; then
    echo "Could not send deployment details to Raygun"
    exit 1
fi

Step 2 - Windows Hosts

In your Bamboo Deployment project, create a new Script task. Give it a description, then tick the 'Run as Powershell script' option. Use the following inline Powershell script as the script body:

Write-Host "Adding deployment in Raygun"

$ownerName = '${bamboo.jira.username}'
if($ownerName -eq '${bamboo.jira.username}')
{
    ownerName = 'Build Server'
}

$command = ConvertTo-Json @{
    apiKey = '${bamboo.raygun.apiKey}'
    version = '${bamboo.deploy.version}'
    ownerName = $ownerName
    comment =' ${bamboo.resultsUrl}'
    scmIdentifier = '${bamboo.repository.revision.number}'
}

$url = "https://app.raygun.io/deployments?authToken=" + '${bamboo.raygun.authToken}'
try {
    Invoke-RestMethod -Uri $url -Body $command -Method Post -ContentType "application/json"
    Write-Host "Added deployment in Raygun"
} catch {
    Write-Host "Error received when adding deployment in Raygun: " $_
}

Step 3

Add the following Variables to your Deployment Configuration: raygun.apiKey, and raygun.authToken.

raygun.apiKey should be set your Raygun Application's ApiKey (the same one you use to set Raygun up within your app).

raygun.authToken should be set to the External Auth Token you generated in Step 1.

Step 4

Deploy your application and watch the Deployments roll in!

FAKE - F# Make

Documentation - Deployments in Raygun with FAKE

Registering Deployments with FAKE

FAKE includes a Raygun deployment target with it as of version 3.35, written by Vidarls on GitHub and contributed to the FAKE project. You can find the documentation here http://fsharp.github.io/FAKE/apidocs/fake-raygunhelper.html, and an example of its use here: https://gist.github.com/Vidarls/596bbdce0414e14e629b.

As with all Deployment client libraries, you'll need to generate an External Auth Token from your Raygun User Settings page.

Heroku

Documentation - Heroku

Registering deploys with Heroku

Once you've setup your Heroku application, adding a webhook is easy.

Step 1

Generate an External Auth Token for your build server to use from your Raygun User Settings page

Step 2

Jump into your terminal/command line and navigate to your Heroku application and enter

heroku addons:create deployhooks:http --url=https://app.raygun.io/deployments/APPID/heroku?authToken=EXTERNALAUTHTOKEN

Replace APPID with the token from your Raygun Crash Reporting URL (https://app.raygun.io/crashreporting/12345) and replace EXTERNALAUTHTOKEN with your external auth token.

Done

Next time you push to Heroku, Raygun will be notifed about your change.

Documentation missing?

If we don't have documentation about your desired topic, send us a message and we'll create it for you.