Sentry Fastlane Plugin

Getting Started

This project is a fastlane plugin. To get started with fastlane-plugin-sentry, you can either add it globally for all projects, or locally to an individual project.

Globally

If you install the gem globally, you can run it with any project that is setup for using fastlane.

gem install fastlane-plugin-sentry

Add the actions you want to use to your Fastfile file and call fastlane to run.

Locally

You can also add the plugin for individual projects. Navigate to your project where fastlane is already set up and run the following command:

bundle exec fastlane add_plugin sentry

Fastlane will guide you through the process. It will add a Pluginfile where the sentry plugin is listed and also update the Gemfile and Gemfile.lock to include it as a dependency.

# Autogenerated by fastlane
#
# Ensure this file is checked in to source control!

gem 'fastlane-plugin-sentry'

Add the actions you want to use to your Fastfile file and call bundle exec fastlane to run.

Sentry Actions

A subset of actions provided by the CLI: https://docs.sentry.io/learn/cli/

Authentication & Configuration

auth_token is the authentication method with Sentry. This can be obtained on https://sentry.io/api/. Also note that as of version 1.2.0 you no longer have to provide the required parameters, we will try to fallback to your .sentryclirc config file if possible.

The following environment variables may be used in place of parameters: SENTRY_AUTH_TOKEN, SENTRY_ORG_SLUG, and SENTRY_PROJECT_SLUG.

Uploading Debug Information Files

sentry_debug_files_upload(
  auth_token: '...',
  org_slug: '...',
  project_slug: '...',
  path: '/path/to/files', # Optional. Defaults to DSYM_OUTPUT_PATH from fastlane context if available, otherwise '.' (current directory). Path(s) can be a string, a comma-separated string, or an array of strings.
)

The SENTRY_DSYM_PATH environment variable may be used in place of the dsym_path parameter.

Further options:

• type: Optional. Only consider debug information files of the given type. By default, all types are considered. Valid options: 'bcsymbolmap', 'breakpad', 'dsym', 'elf', 'jvm', 'pdb', 'pe', 'portablepdb', 'sourcebundle', 'wasm'.
• no_unwind: Optional. Do not scan for stack unwinding information. Specify this flag for builds with disabled FPO, or when stackwalking occurs on the device. This usually excludes executables and dynamic libraries. They might still be uploaded, if they contain additional processable information (see other flags).
• no_debug: Optional. Do not scan for debugging information. This will usually exclude debug companion files. They might still be uploaded, if they contain additional processable information (see other flags).
• no_sources: Optional. Do not scan for source information. This will usually exclude source bundle files. They might still be uploaded, if they contain additional processable information (see other flags).
• id: Optional. Search for specific debug identifiers.
• require_all: Optional. Errors if not all identifiers specified with --id could be found.
• symbol_maps: Optional. Path to BCSymbolMap files which are used to resolve hidden symbols in dSYM files downloaded from iTunes Connect. This requires the dsymutil tool to be available.
• derived_data: Optional. Search for debug symbols in Xcode's derived data.
• no_zips: Optional. Do not search in ZIP files.
• no_upload: Optional. Disable the actual upload. This runs all steps for the processing but does not trigger the upload. This is useful if you just want to verify the setup or skip the upload in tests.
• include_sources: Optional. Include sources from the local file system and upload them as source bundles.
• wait: Optional. Wait for the server to fully process uploaded files. Errors can only be displayed if --wait or --wait-for is specified, but this will significantly slow down the upload process.
• wait_for: Optional. Wait for the server to fully process uploaded files, but at most for the given number of seconds. Errors can only be displayed if --wait or --wait-for is specified, but this will significantly slow down the upload process.
• il2cpp_mapping: Optional. Compute il2cpp line mappings and upload them along with sources.

Uploading Builds

Upload build files to Sentry for improved symbolication and source context. Supported formats:

• iOS: .xcarchive (build archive) or .ipa (app bundle)
• Android: .apk or .aab (App Bundle)

Explicitly passed path parameters take precedence over SharedValues. For IPA uploads, use dsym_path to attach dSYM files for symbolication (IPAs typically don't embed symbols).

sentry_upload_build(
  auth_token: '...',
  org_slug: '...',
  project_slug: '...',
  # One of: xcarchive_path, ipa_path, apk_path, or aab_path (mutually exclusive)
  xcarchive_path: './build/MyApp.xcarchive', # or ipa_path, apk_path, aab_path
  dsym_path: './build/MyApp.app.dSYM.zip', # Optional. For IPA/xcarchive - path or array of dSYM paths. Defaults to DSYM_OUTPUT_PATH from lane context when not specified
  # Optional git context parameters (can also be set via environment variables)
  head_sha: 'abc123...', # The SHA of the head of the current branch (or SENTRY_HEAD_SHA)
  base_sha: 'def456...', # The SHA of the base branch (or SENTRY_BASE_SHA)
  vcs_provider: 'github', # Version control system provider (e.g., 'github', 'gitlab') (or SENTRY_VCS_PROVIDER)
  head_repo_name: 'owner/repo-name', # Name of the head repository (or SENTRY_HEAD_REPO_NAME)
  base_repo_name: 'owner/repo-name', # Name of the base repository (or SENTRY_BASE_REPO_NAME)
  head_ref: 'feature-branch', # Name of the head branch (or SENTRY_HEAD_REF)
  base_ref: 'main', # Name of the base branch (or SENTRY_BASE_REF)
  pr_number: '123', # Pull request number (or SENTRY_PR_NUMBER)
  build_configuration: 'Release', # Build configuration (e.g., 'Release', 'Debug') (or SENTRY_BUILD_CONFIGURATION)
  install_groups: ['beta', 'internal'], # Optional. Control update visibility between builds (or SENTRY_INSTALL_GROUPS)
  release_notes: 'Fixed critical bugs', # Optional. Release notes to use for the upload
  force_git_metadata: false, # Optional. Force collection and sending of git metadata
  no_git_metadata: false # Optional. Disable collection and sending of git metadata
)

Path parameters default to SharedValues when not explicitly passed: XCODEBUILD_ARCHIVE (xcarchive), IPA_OUTPUT_PATH (ipa), GRADLE_APK_OUTPUT_PATH (apk), GRADLE_AAB_OUTPUT_PATH (aab). Explicit parameters always take precedence.

This action is supported on iOS and Android platforms.

Creating & Finalizing Releases

sentry_create_release(
  auth_token: '...',
  org_slug: '...',
  project_slug: '...',
  version: '...', # release version to create
  app_identifier: '...', # pass in the bundle_identifer of your app
  finalize: true, # Whether to finalize the release. If not provided or false, the release can be finalized using the sentry_finalize_release action
  release_url: 'https://github.com/owner/repo/releases/tag/v1.0.0' # Optional. URL to the release for information purposes
)

Uploading Files & Sourcemaps

Useful for uploading build artifacts and JS sourcemaps for react-native apps built using fastlane.

sentry_upload_sourcemap(
  auth_token: '...',
  org_slug: '...',
  project_slug: '...',
  version: '...',
  app_identifier: '...', # pass in the bundle_identifer of your app
  build: '...', # Optionally pass in the build number of your app
  dist: '...', # optional distribution of the release usually the buildnumber
  sourcemap: ['main.jsbundle', 'main.jsbundle.map'], # Sourcemap(s) to upload. Path(s) can be a comma-separated string or an array of strings.
  rewrite: true, # Rewrite the sourcemaps before upload (default: false)
  url_prefix: '~/', # Optional. Sets a URL prefix in front of all files
  url_suffix: '.map', # Optional. Sets a URL suffix to append to all filenames
  note: 'Build from CI', # Optional. Adds a note to the uploaded artifact bundle
  validate: true, # Optional. Enable basic sourcemap validation
  decompress: true, # Optional. Enable files gzip decompression prior to upload
  wait: true, # Optional. Wait for the server to fully process uploaded files
  wait_for: 60, # Optional. Wait for the server to fully process uploaded files, but at most for the given number of seconds
  strict: true # Optional. Fail with a non-zero exit code if the specified source map file cannot be uploaded
)

Uploading Proguard Mapping File

sentry_upload_proguard(
  auth_token: '...',
  org_slug: '...',
  project_slug: '...',
  mapping_path: 'path to mapping.txt to upload',
  no_upload: false, # Optional. Disable the actual upload (useful for verification)
  write_properties: 'path/to/properties/file', # Optional. Write UUIDs for processed mapping files into properties file
  require_one: true, # Optional. Require at least one file to upload or the command will error
  uuid: 'custom-uuid' # Optional. Explicitly override the UUID of the mapping file
)

Associating commits

Useful for telling Sentry which commits are associated with a release.

sentry_set_commits(
  version: '...',
  app_identifier: '...', # pass in the bundle_identifer of your app
  build: '...', # Optionally pass in the build number of your app
  auto: false, # enable completely automated commit management
  clear: false, # clear all current commits from the release
  commit: '...', # commit spec, see `sentry-cli releases help set-commits` for more information
  ignore_missing: false, # Optional boolean value: When the flag is set and the previous release commit was not found in the repository, will create a release with the default commits count (or the one specified with `--initial-depth`) instead of failing the command.
  local: false, # Optional. Set commits of a release from local git
  initial_depth: 20 # Optional. Set the number of commits of the initial release (default: 20)
)

Create deploy

Creates a new release deployment for a project on Sentry.

sentry_create_deploy(
  auth_token: '...',
  org_slug: '...',
  project_slug: '...',
  version: '...',
  app_identifier: '...', # pass in the bundle_identifer of your app
  build: '...', # Optionally pass in the build number of your app
  env: 'staging', # The environment for this deploy. Required.
  name: '...', # Optional human readable name
  deploy_url: '...', # Optional URL that points to the deployment
  started: 1622630647, # Optional unix timestamp when the deployment started
  finished: 1622630700, # Optional unix timestamp when the deployment finished
  time: 180 # Optional deployment duration in seconds. This can be specified alternatively to `started` and `finished`
)

Specify custom sentry-cli path

Starting with version 1.13.0, the plugin bundles both macOS and Windows 64 bit executables of sentry-cli. You can also specify a custom sentry-cli path by adding sentry_cli_path to any action.

Checking the sentry-cli is installed

Useful for checking that the sentry-cli is installed and meets the minimum version requirements before starting to build your app in your lane.

sentry_check_cli_installed()

Logging

You can set the sentry-cli configuration value SENTRY_LOG_LEVEL by adding log_level to any action. Supported values are 'trace', 'debug', 'info', 'warn' and 'error'.

Issues and Feedback

For any other issues and feedback about this plugin, please submit it to this repository.

Migration Guide

Migrating from sentry-fastlane-plugin v1 to v2

When upgrading to the latest version of this plugin (which uses sentry-cli v3), you may need to update your Fastfiles. Here are the key changes:

Parameter Name Changes

• sentry_debug_files_upload: The ids parameter has been renamed to id (singular). Update your Fastfiles:

  # Before
  sentry_debug_files_upload(ids: 'abc123')
  
  # After
  sentry_debug_files_upload(id: 'abc123')
  

Authentication Changes

• All actions: The api_key parameter has been removed in favor of auth_token with the release of v2.0.0. All actions now require auth_token for authentication. Update your Fastfiles:

  # Before v2.0.0-rc.1
  sentry_debug_files_upload(api_key: '...')
  
  # After v2.0.0-rc.1
  sentry_debug_files_upload(auth_token: '...')
  

Parameter Behavior Changes

• sentry_debug_files_upload: The path parameter default behavior has changed. Starting with v2.0.0-rc.1 it defaults to DSYM_OUTPUT_PATH from fastlane's lane context if available (set by actions like build_app or ipa), otherwise falls back to '.' (current directory). This changes the default behavior when DSYM_OUTPUT_PATH is set. If you were relying on the previous behavior of always searching from the current directory, explicitly specify path: '.':

  # To maintain previous behavior (always search from current directory)
  sentry_debug_files_upload(path: '.')
  

Removed Parameters

The following parameters have been removed as they are no longer supported in sentry-cli v3:

• sentry_debug_files_upload: Remove info_plist, no_reprocessing, upload_symbol_maps, and force_foreground parameters if you're using them. The force_foreground parameter was deprecated as a no-op since v1.26.0 and has now been removed.
• sentry_upload_proguard: Remove android_manifest_path parameter if you're using it (no longer needed).

New Available Options

Many new options have been added to match sentry-cli v3 capabilities. See the action documentation above for all available options. Some notable additions:

• sentry_debug_files_upload: Added wait_for, no_upload, il2cpp_mapping options. Type validation now includes jvm, portablepdb, and wasm.
• sentry_upload_sourcemap: Added url_suffix, note, validate, decompress, wait, wait_for, no_sourcemap_reference, debug_id_reference, bundle, bundle_sourcemap, ext, and strict options.
• sentry_upload_proguard: Added no_upload, write_properties, require_one, and uuid options.
• sentry_upload_build: Added release_notes, force_git_metadata, and no_git_metadata options.
• sentry_create_release: Added release_url option.
• sentry_finalize_release: Added release_url and released options.
• sentry_set_commits: Added local and initial_depth options.

Removed Actions

The following actions have been removed and replaced:

• sentry_upload_file: Use sentry_upload_sourcemap for source maps or other specialized upload actions.
• sentry_upload_dsym: Use sentry_debug_files_upload with appropriate path parameter.
• sentry_upload_dif: Use sentry_debug_files_upload with appropriate path parameter.

For more details on sentry-cli v3 changes, see the sentry-cli 3.0.0 release notes.

Troubleshooting

For some more detailed help with plugins problems, check out the Plugins Troubleshooting doc in the main fastlane repo.

Using fastlane Plugins

For more information about how the fastlane plugin system works, check out the Plugins documentation in the main fastlane repo.

About fastlane

fastlane automates building, testing, and releasing your app for beta and app store distributions. To learn more about fastlane, check out fastlane.tools.