BugSplat
Crash and error reporting built for busy developers.
symbol-upload
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.
Action
Use the symbol-upload action in your GitHub Actions workflow by modifying the following snippet.
- name: Symbols 📦
uses: BugSplat-Git/symbol-upload@v11
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: "24"
dumpSyms: false
Be sure to use secrets so that you don't expose the values for clientId, clientSecret, and database.
Pin @v11 to track the latest 11.x release, or an exact tag like @v11.0.0. The action installs the @bugsplat/symbol-upload npm package version matching the pinned ref; SHA and branch refs install the version recorded in that commit's package.json. Set symbol-upload-version to override.
Command Line
Install this symbol-upload globally using npm.
npm i -g @bugsplat/symbol-upload
Alternatively, you can download a binary version using the terminal.
macos
curl -sL -O "https://app.bugsplat.com/download/symbol-upload-macos" && chmod +x symbol-upload-macos
windows
Invoke-WebRequest -Uri "https://app.bugsplat.com/download/symbol-upload-windows.exe" -OutFile "symbol-upload-windows.exe"
linux
curl -sL -O "https://app.bugsplat.com/download/symbol-upload-linux" && chmod +x symbol-upload-linux
Run symbol-upload with -h to see the latest usage information and package version:
bobby@BugSplat % ~ % symbol-upload -h
@bugsplat/symbol-upload v10.5.2
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. 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. 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.
-i, --clientId string 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 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. For example,
**/*.{pdb,exe,dll} will recursively
search for .pdb, .exe, and .dll files.
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.
-l, --localPath string (optional) Path to a directory to copy symbols to.
If provided, the files will be copied to
the provided path instead of being
uploaded to BugSplat. Useful for creating
a self-hosted symbol server.
The -i and -s arguments are not required if you set the environment variables
SYMBOL_UPLOAD_CLIENT_ID and SYMBOL_UPLOAD_CLIENT_SECRET.
Example
symbol-upload -b your-bugsplat-database -a your-application-name -v your-
version -i your-client-id -s your-client-secret [ -f "*.js.map" -d
"/path/to/containing/dir" ]
Links
🐛 https://bugsplat.com
💻 https://github.com/BugSplat-Git/symbol-upload
💌 [email protected]
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.
Self-Hosted Symbol Servers
The symbol-upload tool can be used to create a SymSrv directory structure for Windows symbols that is compatible with both BugSplat and Microsoft Visual Studio. Additionally, symbol-upload can also create a SymSrv directory structure for macOS and Crashpad symbols that is compatible with BugSplat.
To upload symbols to a local directory, provide the -l flag and a path where the symbols will be copied.
symbol-upload -f "**/*.{pdb,exe,dll}" -l "C:\path\to\output"
Next, use a sync tool to upload the directory to a cloud services provider. The following is an example that uses s3 sync via the AWS CLI.
aws s3 sync . s3://your-bucket-name-here
To connect BugSplat to your self-hosted symbol server please refer to our Symbol Server documentation.
API
Install this package locally
npm i @bugsplat/symbol-upload
Module Compatibility
This package supports both ES modules (ESM) and CommonJS (CJS) formats. You can use it in either environment:
ES Modules (ESM):
import { OAuthClientCredentialsClient, uploadSymbolFiles } from '@bugsplat/symbol-upload';
CommonJS (CJS):
const { OAuthClientCredentialsClient, uploadSymbolFiles } = require('@bugsplat/symbol-upload');
Import OAuthClientCredentialsClient from @bugsplat/symbol-upload and authenticate with an OAuth2 Client Credentials Client ID and Client Secret.
Create a new instance of OAuthClientCredentialsClient using the createAuthenticatedClient async factory function.
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 appear when you click the application link on the Versions page.
Thanks for using BugSplat!