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 differentreleaseStage
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 nearestpackage.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 thewhoami
command) -
autoAssignRelease: boolean
automatically associate this build with any new error events and sessions that are received for thereleaseStage
until a subsequent build notification is received. If this is set totrue
and noreleaseStage
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 toprocess.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 support@bugsnag.com
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.