Fastlane

Upload dSYMs and report builds to Bugsnag using Fastlane.

Use our Fastlane plugin to:

  • Upload dSYMs to symbolicate stack traces and get human-readable function names, file paths, and line numbers.
  • Report information when you build your app to enable linking to code in your source control provider from the releases dashboard, timeline annotations, and stack traces.

This documentation is for the v2 Bugsnag Fastlane plugin. Please use fastlane update_plugins to update to the latest plugin.

Installation

To install the Bugsnag plugin run:

$ fastlane add_plugin bugsnag

Basic configuration

The Bugsnag Fastlane plugin has two actions:

  • upload_symbols_to_bugsnag (iOS only)
  • send_build_to_bugsnag (iOS and Android)

Add these actions to a lane in your Fastfile to use them. The plugin will automatically detect some parameters for you, or will provide a default. The order of precedence for each parameter is:

  1. An input given in your Fastfile
  2. An environment variable (upload_symbols_to_bugsnag only)
  3. A configuration file value
  4. A default value

For iOS

By default, the Bugsnag Fastlane plugin will read your API key, and release stage from your application’s Info.plist file. You should ensure that you have a dict-type key named bugsnag which contains two sub string-typed keys which are your Bugsnag API key, and release stage.

<key>bugsnag</key>
<dict>
  <key>apiKey</key>
  <string>YOUR_API_KEY_HERE</string>
  <key>releaseStage</key>
  <string>YOUR_RELEASE_STAGE_HERE</string>
</dict>

Older versions of bugsnag-cocoa (v5 and older) will use an Info.plist that has the following structure. We’ll use this as a fallback if a new format Info.plist is not found:

<key>BugsnagAPIKey</key>
<string>YOUR_API_KEY_HERE</string>

You can find your API key when creating a project in your Bugsnag dashboard, or later from your project settings page.

For Android

By default, the Bugsnag Fastlane plugin will read your API key from the metadata of your application’s AndroidManifest.xml:

<application>
    <meta-data android:name="com.bugsnag.android.API_KEY"
               android:value="YOUR-API-KEY-HERE"/>
</application>

You can find your API key when creating a project in your Bugsnag dashboard, or later from your project settings page.

Verbose mode

To get a verbose output from the Fastlane Bugsnag plugin actions, append the --verbose flag to your fastlane command, e.g.:

$ fastlane ios release --verbose

Uploading dSYMs (iOS only)

Bugsnag can replace the raw memory addresses which appear in iOS stacktraces with human-readable function names, file paths, and line numbers. This process, known as symbolication, requires the contents of your debug symbol (dSYM) files, which are generated when compiling your app.

With Bitcode

If you have Bitcode enabled in your application’s project settings, dSYM files are generated by the App Store when your app is recompiled after upload and will need to be downloaded by Fastlane.

Create a lane in your Fastfile to download your dSYM files and upload them to Bugsnag:

lane :refresh_dsyms do
  download_dsyms(version: "1.4.2.1")     # Download dSYM files from App Store Connect
  upload_symbols_to_bugsnag              # Upload them to Bugsnag
  clean_build_artifacts                  # Delete the local dSYM files
end

Once your lane is configured, run your lane to download and upload your dSYM files:

$ fastlane refresh_dsyms

If your dSYM files are not yet available for your app version, retry later once your app has been recompiled by the App Store.

Without Bitcode

Add the upload_symbols_to_bugsnag action to any lane in your Fastfile that you use when releasing your app, for example :beta and :release:

lane :release do
  # ...
  upload_symbols_to_bugsnag(
    config_file: "/example/path/to/config/Info.plist"
    # other options ...
  )
end

Automatic configuration

The action automatically detects:

  • The location of your Info.plist
  • API key based on the value of bugsnag.apiKey in Info.plist
  • Release stage based on the value of bugsnag.releaseStage in Info.plist
  • The location of the dSYM directory or files based on the lane context or default dSYM location
  • The root path of the project from the current working directory of the process

To see all options and default values, call:

$ fastlane action upload_symbols_to_bugsnag

Additional configuration

Setting any of these options will override automatically detected parameters.

Option Description Environment Variable
config_file The path to the project’s Info.plist. Set this value if your configuration file is not automatically detected BUGSNAG_CONFIG_FILE
api_key Bugsnag API key of the project the dSYMs are applied to BUGSNAG_API_KEY
dsym_path Path to the DSYM directory, file, or zip to upload BUGSNAG_DSYM_PATH
upload_url Defaults to https://upload.bugsnag.com. If you are using Bugsnag On-premise use your Bugsnag Upload API endpoint BUGSNAG_UPLOAD_URL
symbol_maps_path Path to the BCSymbolMaps directory to build complete dSYM files BUGSNAG_SYMBOL_MAPS_PATH
project_root Root path of the project BUGSNAG_PROJECT_ROOT

Reporting builds (iOS and Android)

Add the send_build_to_bugsnag action to any lane in your Fastfile that you use when releasing your app, for example :beta and :release:

lane :release do
  # ...
  send_build_to_bugsnag(
    config_file: "/example/path/to/config/Info.plist"
    # other options ...
  )
end

Automatic configuration

The action automatically detects:

  • The person making the release based on the value of the whoami command
  • The source control repository remote URL and current revision if a git repository can be detected

In addition, on iOS, the action automatically detects:

  • API key based on the value of bugsnag.apiKey in Info.plist
  • Release stage based on the value of bugsnag.releaseStage in Info.plist
  • Bundle version and app version from the values of CFBundleVersion and CFBundleShortVersionString in Info.plist respectively

And on Android, the action automatically detects:

  • API key based on the meta-data value of com.bugsnag.android.API_KEY in AndroidManifest.xml
  • App version and version code based on the values for versionName and versionCode in the module-level build.gradle file

To see all options and default values, call:

$ fastlane action send_build_to_bugsnag

Additional configuration

Setting any of these options will override automatically detected parameters.

Option Description
config_file The path to the project’s Info.plist or AndroidManifest.xml. Set this value if your configuration file is not automatically detected
api_key The Bugsnag API key used to send requests
app_version The version of the application
android_version_code The version code of the Android application
ios_bundle_version The bundle version of the iOS application
release_stage The current stage of build being deployed, such as “production” or “beta” or “staging”
builder The entity building and releasing the application, such as the name of the current user
repository The source control repository being deployed
revision The source control revision being deployed
provider The name of the source control provider, from: github, github-enterprise, gitlab, gitlab-onpremise, bitbucket, or bitbucket-server
endpoint Defaults to https://build.bugsnag.com. If you are using Bugsnag On-premise use your Bugsnag Build API endpoint