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.

Installation

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

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.

Usage

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

# CLI
bugsnag-build-reporter <opts>

// JS API
const reportBuild = require('bugsnag-build-reporter')

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

If you are using the BugSnag for Enterprise instance, you will need to configure the endpoint to build.bugsnag.smartbear.com.

Examples

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.message))

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

report-build:
    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.

`BuildData`

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 `releaseStage`s)
`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

`Options`

An object that can alter the behavior 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`	if you are using On-premise then set this to the build endpoint of your server, or if you are on the BugSnag for Enterprise instance then use `https://build.bugsnag.smartbear.com/`. Defaults to `https://build.bugsnag.com/`.