This repo is a simple Node.js utility, set of libraries, and GitHub action for uploading symbol files or source maps to BugSplat. This utility is designed to be used in your build process to upload symbols to BugSplat automatically for each production build. This package can be used as a library or a command line utility.
Use the symbol-upload
action in your GitHub Actions workflow by modifying the following snippet.
- name: Symbols 📦
uses: BugSplat-Git/symbol-upload@main
with:
clientId: "${{ secrets.SYMBOL_UPLOAD_CLIENT_ID }}"
clientSecret: "${{ secrets.SYMBOL_UPLOAD_CLIENT_SECRET }}"
database: "${{ secrets.BUGSPLAT_DATABASE }}"
application: "your-application"
version: "your-version"
files: "**/*.{pdb,exe,dll}"
directory: "your-build-directory"
node-version: "22"
dumpSyms: false
Be sure to use secrets so that you don't expose the values for clientId
, clientSecret
, and database
.
- Install this package globally
npm i -g @bugsplat/symbol-upload
- Run symbol-upload with
-h
to see the latest usage information and package version:
bobby@BugSplat % ~ % symbol-upload -h
@bugsplat/symbol-upload v10.1.0
symbol-upload contains a command line utility and a set of libraries to help
you upload symbol files to BugSplat.
Usage
-h, --help Print this usage guide.
-b, --database string Your BugSplat database name. The value of database must match the value used
to post crash reports. This value can also be provided via the
BUGSPLAT_DATABASE environment variable.
-a, --application string The name of your application. The value of application must match the value
used to post crash reports. If not provided symbol-upload will attempt to use
the value of the name field in package.json if it exists in the current
working directory.
-v, --version string Your application's version. The value of version must match the value used to
post crash reports. If not provided symbol-upload will attempt to use the
value of the version field in package.json if it exists in the current
working directory.
-u, --user string (optional) The email address used to log into your BugSplat account. If provided
--password must also be provided. This value can also be provided via the
SYMBOL_UPLOAD_USER environment variable.
-p, --password string (optional) The password for your BugSplat account. If provided --user must also be
provided. This value can also be provided via the SYMBOL_UPLOAD_PASSWORD
environment variable.
-i, --clientId string (optional) An OAuth2 Client Credentials Client ID for the specified database. If
provided --clientSecret must also be provided. This value can also be
provided via the SYMBOL_UPLOAD_CLIENT_ID environment variable.
-s, --clientSecret string (optional) An OAuth2 Client Credentials Client Secret for the specified database. If
provided --clientId must also be provided. This value can also be provided
via the SYMBOL_UPLOAD_CLIENT_SECRET environment variable.
-r, --remove Removes symbols for a specified database, application, and version. If this
option is provided no other actions are taken.
-f, --files string (optional) Glob pattern that specifies a set of files to upload. Defaults to '*.js.map'
-d, --directory string (optional) Path of the base directory used to search for symbol files. This value will
be combined with the --files glob. Defaults to '.'
-m, --dumpSyms boolean (optional) Use dump_syms to generate and upload sym files for specified binaries.
The -u and -p arguments are not required if you set the environment variables
SYMBOL_UPLOAD_USER and SYMBOL_UPLOAD_PASSWORD, or provide a clientId and
clientSecret.
The -i and -s arguments are not required if you set the environment variables
SYMBOL_UPLOAD_CLIENT_ID and SYMBOL_UPLOAD_CLIENT_SECRET, or provide a user
and password.
Example
symbol-upload -b your-bugsplat-database -a your-application-name -v your-
version [ -f "*.js.map" -d "/path/to/containing/dir" [ -u your-bugsplat-email
-p your-bugsplat-password ] OR [ -i your-client-id -s your-client-secret] ]
Links
🐛 https://bugsplat.com
💻 https://github.com/BugSplat-Git/symbol-upload
💌 support@bugsplat.com
- Run symbol-upload specifying a glob pattern for
-f
and a path with forward slashes for-d
. Multiple file types can be specified in curly brackets separated by a comma, and wildcards can be used to search directories recursively. For example,**/*.{pdb,exe,dll}
will search for all.pdb
,.exe
, and.dll
files in the current directory and all subdirectories. Optionally, you can specify the-m
flag to run dump_syms against the specified binaries and upload the resulting.sym
files.
- Install this package locally
npm i @bugsplat/symbol-upload
. - Import
BugSplatApiClient
andVersionsApiClient
from @bugsplat/symbol-upload. Alternatively, you can importOAuthClientCredentialsClient
if you'd prefer to authenticate with an OAuth2 Client Credentials Client ID and Client Secret.
import { BugSplatApiClient, OAuthClientCredentialsClient, uploadSymbolFiles } from '@bugsplat/symbol-upload';
- Create a new instance of
BugSplatApiClient
using thecreateAuthenticatedClientForNode
async factory function orOAuthClientCredentialsClient
using thecreateAuthenticatedClient
async factory function.
const bugsplat = await BugSplatApiClient.createAuthenticatedClientForNode(email, password);
const bugsplat = await OAuthClientCredentialsClient.createAuthenticatedClient(clientId, clientSecret);
- Upload your symbol files to bugsplat by calling the
uploadSymbolFiles
function.
const directory = '/path/to/symbols/dir';
const files = ['my-cool-app.exe', 'my-cool-app.pdb'];
await uploadSymbolFiles(bugsplat, database, application, version, directory, files);
If you've done everything correctly, your symbols should be shown by clicking the application link on the Versions page.
Thanks for using BugSplat!