Capistrano

Report releases to BugSnag using Capistrano.

Use our Capistrano gem to:

  • Report information when you release your app to enable linking to code in your source control provider from the releases dashboard, timeline annotations, and stack traces.

Installation

Add the bugsnag-capistrano Ruby gem to your project:

bundle add bugsnag-capistrano

To stop the gem from being loaded automatically outside of your Capistrano environment, you can append require: false to the Gem in your Gemfile:

gem 'bugsnag-capistrano', require: false

Basic configuration

To track releases automatically require bugsnag-capistrano into your Capfile and configure your API key and app version by either:

Setting them in your Capfile:

require 'bugsnag-capistrano'

set :bugsnag_api_key, "your-api-key-here"
set :app_version, "1.3.2"

Or setting the BUGSNAG_API_KEY and BUGSNAG_APP_VERSION environment variables.

Notifying of releases

Release notifications will be sent whenever a release is made via Capistrano in the configured repository, or when manually sent using the bugsnag:release task with the appropriate Capistrano stage (such as production or beta) as your_cap_stage:

cap your_cap_stage bugsnag:release BUGSNAG_API_KEY='your_api_key_here' ...

Configuration options

All of the following configuration options can be set within the projects Capfile. Certain options may also be set using environment variables, as specified.

Variable Environment variable Description
:bugsnag_api_key BUGSNAG_API_KEY your BugSnag API key [required]
:app_version BUGSNAG_APP_VERSION the version of the application you are releasing [required] (this should match the appVersion configured in your notifier)
:bugsnag_auto_assign_release BUGSNAG_AUTO_ASSIGN_RELEASE automatically associate this build with any new error events and sessions that are received for the releaseStage until a subsequent build notification is received. If this is set to true and no releaseStage is provided the build will be applied to 'production'. You should only use this option if you aren’t able to set an appVersion in your notifier.
:bugsnag_builder BUGSNAG_BUILDER_NAME the name of the person/machine that created this build (defaults to the result of the whoami command)
:bugsnag_endpoint Defaults to https://build.bugsnag.com. If you are using BugSnag On-premise use your BugSnag Build API endpoint
:bugsnag_env BUGSNAG_RELEASE_STAGE 'production', 'staging' etc. (leave blank if this build can be released to different releaseStages)
:current_revision BUGSNAG_REVISION the unique identifier for the commit (e.g. git SHA)
:bugsnag_metadata an object containing any additional data to be attached to the release
:repo_url BUGSNAG_REPOSITORY a URL (git/ssh/https) pointing to the repository, or webpage representing the repository¹
:bugsnag_source_control_provider BUGSNAG_SOURCE_CONTROL_PROVIDER For on-premise git installations only, one of: github-enterprise, bitbucket-server, gitlab-onpremise

¹ BugSnag will attempt to convert SSH URLs to HTTPS in order to provide links to your repository from the dashboard. If this automatic conversion does not work, you can set :bugsnag_repo_url. For example:

set :repo_url, "git@bugsnag.com:org/repo.git"
set :bugsnag_repo_url, "https://bugsnag.com/org/repo.git"