bugsnag-build-reporter

A tool for reporting your application's builds to Bugsnag. It can auto detect source control from .git, .hg and package.json. If you are using any of the following tools in your build, you may find the following modules (that use this one under the hood) more convenient:

Tool	Module	Version
Webpack	webpack-bugsnag-plugins
Gulp	gulp-bugsnag
Grunt	grunt-bugsnag

bugsnag-build-reporter should be used directly if your application is built by:

• some arbitrary Node-based environment (e.g. a build tool not listed above or something custom)
• a command based tool (e.g. npm scripts, make)

Usage

This module can be used in a Node environment via the JS API or as a CLI.

JS API

To use the JS API, install this module as a development dependency of your project:

npm i --save-dev bugsnag-build-reporter

Then use 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))

reportBuild(build: object, opts: object) => Promise

• build describes the build you are reporting to Bugsnag
  • apiKey: string your Bugsnag API key [required]
  • appVersion: string the version of the application you are building [required]
  • 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)
    • provider: string can be one of: 'github', 'github-enterprise', 'gitlab', 'gitlab-onpremise', 'bitbucket', 'bitbucket-server'
    • repository: string a URL (git/ssh/https) pointing to the repository, or webpage representing the repository
    • 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'.
  • 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
• opts
  • logLevel: string the minimum severity of log to output ('debug', 'info', 'warn', 'error')
  • 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 post the build payload to a URL other than the default (https://build.bugsnag.com)

CLI

To use the CLI, install it from npm:

# locally
npm i --save-dev bugsnag-build-reporter
# or globally
npm i --global bugsnag-build-reporter

If installed locally, recent versions of npm come with a tool called npx which will help run it without typing burdensome paths.

$ bugsnag-build-reporter <flags> <metadata>

Options
  --api-key, -k  Set your notifier API key [required]
  --app-version, -v  Set the app version [required]
  --release-stage, -s Set the release stage

  --source-control-provider, -p  Set the repo provider
  --source-control-repository, -r  Set the repo URL
  --source-control-revision, -e  Set the source control revision id (e.g commit SHA)

  --builder-name, -n  Set the name of the entity that triggered the build
  --auto-assign-release, -a  Assign any subsequent error reports received to this release
  --endpoint, -u Specify an alternative endpoint

  --app-version-code, -c  Set the version code (Android only)
  --app-bundle-version, -b  Set the bundle version (iOS/macOS/tvOS only)

  metadata
  Arbitrary "key=value" pairs will be passed to the build API as metadata
  e.g. foo=bar

Examples

  bugsnag-build-reporter \
  --api-key cc814aead128d38d0767094327b4784a \
  --app-version 1.3.5

  bugsnag-build-reporter \
  -k cc814aead128d38d0767094327b4784a \
  -v 1.3.5

Examples

Here are some examples of using bugsnag-build-reporter:

JS API

const reportBuild = require('bugsnag-build-reporter')
reportBuild({
  apiKey: 'YOUR_API_KEY',
  appVersion: '1.2.3',
  builderName: 'Katherine Johnson'
}).then(() => {
  /* success */
}, err => {
  /* error */
})

npm scripts

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

make

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

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

Support

• Search open and closed issues issues for similar problems
• Report a bug or request a feature
• Email [e-mail]

Contributing

All contributors are welcome! See our contributing guide.

License

This module is free software released under the MIT License. See LICENSE.txt for details.