Deploy tracking API

Notify BugSnag about any new deploys or releases of your applications.

By sending the source revision or application version when you deploy a new version of your app, you’ll be able to see which deploy each error was introduced in.

API overview

If you are using a custom notifier, or your notifier does provide appropriate deploy tracking hooks, you can notify BugSnag of deploys of your application using the deploy tracking API described here. To notify BugSnag of deploys, simply make a HTTP POST to https://notify.bugsnag.com/deploy and BugSnag will save and process the deploy information.

The POST payload can either be normal form-encoded data, or a JSON object. If you choose to POST a JSON object, make sure you set the HTTP Content-Type header to be application/json.

You can post the following fields when notifying BugSnag of a deploy:

• apiKey

  The API Key associated with the project. Informs BugSnag which project has been deployed. This is the only required field.

• releaseStage

  The release stage (eg, production, staging) currently being deployed. (Optional, defaults to production.)

• repository

  The URL of the repository containing the source code being deployed. We can use this to link directly to your source code on GitHub, Bitbucket or GitLab from the BugSnag dashboard. (Required for source code integration.)

• provider

  The name of your source control provider. Required when repository is supplied and only for on-premise services (for cloud services the provider will be derived from the URL.)

  When supplied must be one of:

  • github-enterprise for GitHub Enterprise
  • bitbucket-server for Bitbucket Server (formerly Stash)
  • gitlab-onpremise for GitLab CE or GitLab Enterprise

• branch

  The source control branch from which you are deploying the code. (Optional, only relevant when repository is supplied.)

• revision

  The source control revision id for the code you are deploying. (Required when repository is supplied.)

• appVersion

  The app version of the code you are currently deploying. The version must be unique within your project. (Optional.)

Response codes

BugSnag doesn’t analyze requests synchronously, so we only use two response codes:

• 200 (OK)

  The request was accepted and will be processed asynchronously. This doesn’t imply that the payload or parameters were valid, just that it was enqueued to be processed.

• 400 (Bad Request)

  The payload was empty or there was an error reading it.

Source code integration

If repository details are provided we will link directly to your source code from:

• The error details view in the dashboard to show the code where an error occurred (for some platforms only)
• Deploy annotations on the timeline to show the code where an error might have been introduced, and a code diffs to the previous deploy.

GitHub

Send deploy tracking notifications with the following fields populated

• repository (The URL to your GitHub repo e.g. https://github.com/owner/repo or git@github.com:owner/repo.git)

• revision (The Git commit hash (short or long) e.g. 42ce59f)

GitHub Enterprise

Send deploy tracking notifications with the following fields populated

• repository (The URL to your GitHub repo e.g. https://my.github.server/owner/repo)

• provider (github-enterprise)

• revision (The Git commit hash (short or long) e.g. 42ce59f)

Bitbucket

Send deploy tracking notifications with the following fields populated, both Git and Mercurial repos are supported

• repository (The URL to your Bitbucket repo e.g. https://bitbucket.org/owner/repo or git@bitbucket.org:owner/repo.git)

• revision (The Git or Mercurial commit hash (short or long) e.g. 42ce59f)

Bitbucket Server (formerly Stash)

Send deploy tracking notifications with the following fields populated

• repository (The URL to your Bitbucket Server repo e.g. https://my.bitbucket.server/projects/project/repos/repo/browse)

• provider (bitbucket-server)

• revision (The Git commit hash (short or long) e.g. 42ce59f)

GitLab

Send deploy tracking notifications with the following fields populated

• repository (The URL to your GitLab project e.g. https://gitlab.com/owner/repo or git@gitlab.com:owner/repo.git)

• revision (The Git commit hash (short or long) e.g. 42ce59f)

GitLab Enterprise

Send deploy tracking notifications with the following fields populated

• repository (The URL to your GitHub repo e.g. https://my.gitlab.server/owner/repo)

• provider (gitlab-onpremise)

• revision (The Git commit hash (short or long) e.g. 42ce59f)

cURL example

Notify BugSnag of a deploy using curl:

curl -d "apiKey=YOUR_API_KEY_HERE&appVersion=1.5" https://notify.bugsnag.com/deploy

Note: To configure deploy tracking, replace the example text with your project’s API token, found on its project settings page.

Pre-configured integrations

• Bitbucket Pipelines
• Capistrano
• Rake