Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/getsentry/sentry-fastlane-plugin

Official fastlane plugin for Sentry
https://github.com/getsentry/sentry-fastlane-plugin

crash-reporting dsym fastlane hacktoberfest sdk-adjacent sentry sourcemaps tag-production team-mobile

Last synced: 22 days ago
JSON representation

Official fastlane plugin for Sentry

Awesome Lists containing this project

README 

          


    

        

    




    
Sentry Fastlane Plugin



[![fastlane Plugin Badge](https://rawcdn.githack.com/fastlane/fastlane/master/fastlane/assets/plugin-badge.svg)](https://rubygems.org/gems/fastlane-plugin-sentry)

[![Tests](https://img.shields.io/github/workflow/status/getsentry/sentry-fastlane/test?label=Tests)](https://github.com/getsentry/sentry-fastlane/actions?query=workflow%3A"test")

[![Gem Version](https://badge.fury.io/rb/fastlane-plugin-sentry.svg)](https://badge.fury.io/rb/fastlane-plugin-sentry)



## Getting Started



This project is a [fastlane](https://github.com/fastlane/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`.



```bash

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:



```bash

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.



```ruby

# 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



```ruby

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).



```ruby

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



```ruby

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.



```ruby

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



```ruby

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.



```ruby

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.



```ruby

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.



```ruby

sentry_check_cli_installed()

```



### Logging



You can set the `sentry-cli` [configuration value](https://docs.sentry.io/product/cli/configuration/#configuration-values) `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:



  ```ruby

  # 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](https://github.com/getsentry/sentry-fastlane-plugin/releases/2.0.0-rc.1). All actions now require `auth_token` for authentication. Update your Fastfiles:



  ```ruby

  # 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](https://github.com/getsentry/sentry-fastlane-plugin/releases/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: '.'`:

  ```ruby

  # 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](https://github.com/getsentry/sentry-cli/releases/tag/3.0.0).



## Troubleshooting



For some more detailed help with plugins problems, check out the [Plugins Troubleshooting](https://github.com/fastlane/fastlane/blob/master/fastlane/docs/PluginsTroubleshooting.md) doc in the main `fastlane` repo.



## Using `fastlane` Plugins



For more information about how the `fastlane` plugin system works, check out the [Plugins documentation](https://docs.fastlane.tools/plugins/create-plugin/) 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](https://fastlane.tools).