Reporting builds

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


bugsnag-build-reporter provides a CLI and a JavaScript library that can be used to report builds to Bugsanag.

Install it globally on your system:

npm install --global bugsnag-build-reporter
# or
yarn global add bugsnag-build-reporter

Or locally inside your project:

npm install --save-dev bugsnag-build-reporter
# or
yarn add bugsnag-build-reporter

The library reports your application’s build to BugSnag including all of the build metadata you include. It automatically detects source control from Git/Mercurial repos and from projects with a package.json.


The library can be used via the command line or as a JavaScript API.

bugsnag-build-reporter <opts>
const reportBuild = require('bugsnag-build-reporter')

async function reportBuild (build: BuildData, opts: Options): Promise<void>


If your application builds in a Node environment, you can import the JS API and use it like so:

const reportBuild = require('bugsnag-build-reporter')
reportBuild({ apiKey: 'YOUR_API_KEY', appVersion: '1.2.3' }, { /* opts */ })
  .then(() => console.log('success!'))
  .catch(err => console.log('fail', err.messsage))

You can use the CLI directly from a script specified in your package.json

scripts: {
  "report-build": "bugsnag-build-reporter -k YOUR_API_KEY -v '1.2.3' -n 'Katherine Johnson'"

You can shell out to the CLI from a Makefile

PATH := node_modules/.bin:$(PATH)
SHELL := /bin/bash

    bugsnag-build-reporter -k YOUR_API_KEY -v "1.2.3" -n "Katherine Johnson"

Option reference

The full set of options for bugsnag-build-reporter.


An object describing the build payload to be reported to BugSnag.

Property Type Description
apiKey string your BugSnag API key [required]
appVersion string the version of the application you are building [required] (this should match the appVersion configured in your notifier)
releaseStage string 'production', 'staging' etc. (leave blank if this build can be released to different releaseStages)
sourceControl object an object describing the source control of the build (if not specified, the module will attempt to detect source control information from .git, .hg and the nearest package.json)
sourceControl.provider string can be one of: 'github', 'github-enterprise', 'gitlab', 'gitlab-onpremise', 'bitbucket', 'bitbucket-server'
sourceControl.repository string a URL (git/ssh/https) pointing to the repository, or webpage representing the repository
sourceControl.revision string the unique identifier for the commit (e.g. git SHA)
builderName string the name of the person/machine that created this build (defaults to the result of the whoami command)
autoAssignRelease boolean 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.
appVersionCode string if you’re using this module to report Android app builds, set this option
appBundleVersion string if you’re using this module to report iOS/macOS/AppleTV app builds, set this option


An object that can alter the behaviour of the module.

Property Type Description
logLevel string the minimum severity of log to output ('debug', 'info', 'warn', 'error'), default 'warn'
logger object provide a different logger object { debug, info, warn, error }
path string the path to search for source control info, defaults to process.cwd()
endpoint string Defaults to If you are using BugSnag On-premise use your BugSnag Build API endpoint