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.
If you install the gem globally, you can run it with any project that is setup for using fastlane.
gem install fastlane-plugin-sentryAdd the actions you want to use to your Fastfile file and call fastlane to run.
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 sentryFastlane 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.
A subset of actions provided by the CLI: https://docs.sentry.io/learn/cli/
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.
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.
Upload iOS build archives (.xcarchive) to Sentry for improved symbolication and source context.
sentry_upload_build(
auth_token: '...',
org_slug: '...',
project_slug: '...',
xcarchive_path: './build/MyApp.xcarchive', # Path to your .xcarchive file
# 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)
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
)By default the SharedValue::XCODEBUILD_ARCHIVE sets the xcarchive_path parameter if set by a prior lane such as build_app.
This action is only supported on iOS platform.
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
)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
)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
)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)
)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`
)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.
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()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'.
For any other issues and feedback about this plugin, please submit it to this repository.
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:
sentry_debug_files_upload: Theidsparameter has been renamed toid(singular). Update your Fastfiles:# Before sentry_debug_files_upload(ids: 'abc123') # After sentry_debug_files_upload(id: 'abc123')
- All actions: The
api_keyparameter has been removed in favor ofauth_tokenwith the release of v2.0.0. All actions now requireauth_tokenfor 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: '...')
sentry_debug_files_upload: Thepathparameter default behavior has changed. Starting with v2.0.0-rc.1 it defaults toDSYM_OUTPUT_PATHfrom fastlane's lane context if available (set by actions likebuild_apporipa), otherwise falls back to'.'(current directory). This changes the default behavior whenDSYM_OUTPUT_PATHis set. If you were relying on the previous behavior of always searching from the current directory, explicitly specifypath: '.':# To maintain previous behavior (always search from current directory) sentry_debug_files_upload(path: '.')
The following parameters have been removed as they are no longer supported in sentry-cli v3:
sentry_debug_files_upload: Removeinfo_plist,no_reprocessing,upload_symbol_maps, andforce_foregroundparameters if you're using them. Theforce_foregroundparameter was deprecated as a no-op since v1.26.0 and has now been removed.sentry_upload_proguard: Removeandroid_manifest_pathparameter if you're using it (no longer needed).
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: Addedwait_for,no_upload,il2cpp_mappingoptions. Type validation now includesjvm,portablepdb, andwasm.sentry_upload_sourcemap: Addedurl_suffix,note,validate,decompress,wait,wait_for,no_sourcemap_reference,debug_id_reference,bundle,bundle_sourcemap,ext, andstrictoptions.sentry_upload_proguard: Addedno_upload,write_properties,require_one, anduuidoptions.sentry_upload_build: Addedrelease_notes,force_git_metadata, andno_git_metadataoptions.sentry_create_release: Addedrelease_urloption.sentry_finalize_release: Addedrelease_urlandreleasedoptions.sentry_set_commits: Addedlocalandinitial_depthoptions.
The following actions have been removed and replaced:
sentry_upload_file: Usesentry_upload_sourcemapfor source maps or other specialized upload actions.sentry_upload_dsym: Usesentry_debug_files_uploadwith appropriatepathparameter.sentry_upload_dif: Usesentry_debug_files_uploadwith appropriatepathparameter.
For more details on sentry-cli v3 changes, see the sentry-cli 3.0.0 release notes.
For some more detailed help with plugins problems, check out the Plugins Troubleshooting doc in the main fastlane repo.
For more information about how the fastlane plugin system works, check out the Plugins documentation in the main fastlane repo.
fastlane automates building, testing, and releasing your app for beta and app store distributions. To learn more about fastlane, check out fastlane.tools.