Release Management
The sentry-cli
tool can be used for release management on Sentry. It allows you to create, edit and delete releases as well as upload release artifacts for them. Note that releases are global per organization. If you want the releases in different projects to be treated as separate entities, make the version name unique across the organization. For example, if you have projectA and projectB that share version numbers, you can name the releases projectA-1.0
and projectB-1.0
respectively.
Because releases work on projects you will need to specify the organization and project you are working with. For more information about this refer to Working with Projects.
Releases are created with the sentry-cli releases new
command. It takes at the very least a version identifier that uniquely identifies the releases. There are a few restrictions -- the release name cannot:
- contain newlines, tabulator characters, forward slashes(/), or back slashes(\)
- be (in their entirety) period (.), double period (..), or space ( )
- exceed 200 characters
The value can be arbitrary, but for certain platforms, recommendations exist:
- for mobile devices use
package-name@version-number
orpackage-name@version-number+build-number
. Do not useVERSION_NUMBER (BUILD_NUMBER)
as the parenthesis are used for display purposes (foo@1.0+2 becomes 1.0 (2)), so invoking them will cause an error. - if you use a DVCS we recommend using the identifying hash (eg: the commit SHA,
da39a3ee5e6b4b0d3255bfef95601890afd80709
). You can let sentry-cli automatically determine this hash for supported version control systems withsentry-cli releases propose-version
. - if you tag releases we recommend using the release tag prefixed with a product or package name (for example,
my-project-name@2.3.12
).
#!/bin/sh
sentry-cli releases new "$VERSION"
Releases can also be auto created by different systems. For instance upon uploading a source map a release is automatically created. Likewise releases are created by some clients when an event for a release comes in.
By default a release is created “unreleased”. Finalizing a release means that we populate a second timestamp on the release record, which is prioritized over date_created
when sorting releases in sentry.io. Release finalization (and the timestamp) also affects:
- What counts as "the next release" for resolving issues
- What release is used as the base for associating commits if you use
--auto
In addition, it creates an entry in the Activity stream.
You can change this by passing either --finalize
to the new
command, which will immediately finalize the release, or by separately calling sentry-cli releases finalize VERSION
later on, which is useful if you are managing releases as part of a build process. For example:
#!/bin/sh
sentry-cli releases new "$VERSION"
# do your build steps here
# once you are done, finalize
sentry-cli releases finalize "$VERSION"
You can also choose to finalize the release when you've made the release live (when you've deployed to your machines, enabled in the App store, etc.).
If you are using git you can ask Sentry to determine $VERSION
:
#!/bin/sh
VERSION=`sentry-cli releases propose-version`
If you have repositories configured within your Sentry organization, you can associate commits with your release automatically or manually. If you don't have a source code integration installed, you can still send Sentry commit information. See Alternatively: Without a Repository Integration to associate commits using the git tree of your local repo.
To integrate commits automatically, you need to deploy from a git repository that sentry-cli can discover from your current working directory and set commits with the --auto
flag:
sentry-cli releases set-commits "$VERSION" --auto
In case you are deploying without access to the git repository, you can manually specify the commits instead. To do this, pass the --commit
parameter to the set-commits
command in the format REPO_NAME@REVISION
. You can repeat this for as many repositories as you have:
sentry-cli releases set-commits "$VERSION" --commit "my-repo@deadbeef"
The repository name my-repo
should match the name you entered when linking the repo, and should be in the form owner-name/repo-name
.
To see which repos are available for the organization, you can run sentry-cli repos list
which will return a list of configured repositories.
Note that you need to refer to releases you need to use the actual full commit SHA. If you want to refer to tags or references (like HEAD), the repository needs to be checked out and reachable from the path where you invoke sentry-cli.
If you also want to set a previous commit instead of letting the server use the previous release as the base point you can do that by setting a commit range:
sentry-cli releases set-commits "$VERSION" --commit "my-repo@from..to"
You can still use the --auto
flag, and the CLI will automatically use the git tree of your local repo, and associate commits between the previous release's commit and the current head commit with the release. If this is the first release, Sentry will use the latest 20 commits. This behavior is configurable with the --initial-depth
flag.
You can use the --local
flag to enable this behavior by default.
sentry-cli releases set-commits "$VERSION" --local
If you receive an "Unable to Fetch Commits" email, take a look at our help center article.
There are scenarios in which your repositories may be missing commits previously used in the release. This can happen whenever you modify the commit in question by, for example, amending it, rebasing, or squashing multiple commits together. In this case, Sentry CLI will be unable to find it, and will throw an error that the commit cannot be found.
When this happens, you can pass an additional --ignore-missing
flag. This will allow the command to fall back to the default behavior, which is creating a release with a specified number of commits (see the section above).
sentry-cli releases set-commits "$VERSION" --auto --ignore-missing
When you are working with JavaScript and other platforms, you can upload release artifacts to Sentry which are then considered during processing. The most common release artifact are source maps for which sentry-cli
has specific support.
To manage release artifacts the sentry-cli releases files
command can be used which itself provides various sub commands.
The most common use case is to upload files. For the generic upload the sentry-cli releases files VERSION upload
command can be used. However since most release artifacts are JavaScript source map related we have a Upload Source Maps convenience method for that.
Files uploaded are typically named with a full (eg: http://example.com/foo.js
) or truncated URL (eg: ~/foo.js
).
Release artifacts are only considered at time of event processing. So while it’s possible to modify release artifacts after the fact they will only be considered for future events of that release.
The first argument to upload
is the path to the file, the second is an optional URL we should associate it with. Note that if you want to use an abbreviated URL (eg: ~/foo.js
) make sure to use single quotes to avoid the expansion by the shell to your home folder.
sentry-cli releases files "$VERSION" upload /path/to/file '~/file.js'
For source map upload, a separate command is provided which assists you in uploading and verifying source maps:
sentry-cli sourcemaps upload /path/to/sourcemaps
This command provides several options and attempts as much auto detection as possible. By default, it will scan the provided path for files and upload them named by their path with a ~/
prefix. It will also attempt to figure out references between minified files and source maps based on the filename. So if you have a file named foo.min.js
which is a minified JavaScript file and a source map named foo.min.map
for example, it will send a long a Sourcemap
header to associate them. This works for files the system can detect a relationship of.
By default, sentry-cli
rewrites source maps before upload:
- It flattens out indexed source maps. This has the advantage that it can compress source maps sometimes which might improve your processing times and can work with tools that embed local paths for source map references which would not work on the server. This is useful when working with source maps for development purposes in particular.
- Local file references in source maps for source contents are inlined. This works particularly well with React Native projects which might reference thousands of files you probably do not want to upload separately.
- It automatically validates source maps before upload very accurately which can spot errors you would not find otherwise until an event comes in. This is an improved version of what
--validate
does otherwise.
The following options exist to change the behavior of the upload command:
--dist
Sets the distribution identifier for uploaded files. This identifier is used to make a distinction between multiple files of the same name within a single release. dist
can be used to disambiguate build or deployment variants. For example, dist
can be the build number of an Xcode build or the version code of an Android build.
--no-sourcemap-reference
This prevents the automatic detection of source map references. It’s not recommended to use this option since the system falls back to not emitting a reference anyways. It is however useful if you are manually adding sourceMapURL
comments to the minified files and you know that they are more correct than the autodetection.
--no-rewrite
Disables rewriting of matching source maps. By default, the tool will rewrite sources, so that indexed maps are flattened and missing sources are inlined if possible. This fundamentally changes the upload process to be based on source maps and minified files exclusively and comes in handy for setups like react-native that generate source maps that would otherwise not work for Sentry.
--strip-prefix
/ --strip-common-prefix
Unless --no-rewrite
is specified, this will chop-off a prefix from all sources references inside uploaded source maps. For instance, you can use this to remove a path that is build machine specific. The common prefix version will attempt to automatically guess what the common prefix is and chop that one off automatically. This will not modify the uploaded sources paths. To do that, point the sourcemaps upload
command to a more precise directory instead.
--validate
This attempts source map validation before upload when rewriting is not enabled. It will spot a variety of issues with source maps and cancel the upload if any are found. This is not the default as this can cause false positives.
--url-prefix
This sets an URL prefix in front of all files. This defaults to ~/
but you might want to set this to the full URL. This is also useful if your files are stored in a sub folder. eg: --url-prefix '~/static/js'
--ext
Overrides the list of file extensions to upload. By default, the following file extensions are processed: js
, map
, jsbundle
and bundle
. The tool will automatically detect the type of the file by the file contents (eg: sources, minified sources, and source maps) and act appropriately. For multiple extensions you need to repeat the option, e.g.: --ext js --ext map
.
--ignore
Specifies one or more patterns of ignored files and folders. Overrides patterns specified in the ignore file. See --ignore-file
for more information. Note that unlike --ignore-file
, this argument is interpreted relative to the specified path argument.
--ignore-file
Specifies a file containing patterns of files and folders to ignore during the scan. Ignore patterns follow the gitignore rules and are evaluated relative to the location of the ignore file. The file is assumed in the current working directory or any of its parent directories.
--strict
Fail with a non-zero exit code if there are no sourcemaps to upload in the provided directory. Without this argument, the command succeeds if there are no sourcemaps to upload.
Some example usages:
# Rewrite and upload all sourcemaps in /path/to/sourcemaps
sentry-cli sourcemaps upload /path/to/sourcemaps
# Prefix all paths with ~/static/js to match where the sources are hosted online
sentry-cli sourcemaps upload /path/to/sourcemaps --url-prefix '~/static/js'
# Remove a common prefix if all source maps are located in a subdirectory
sentry-cli sourcemaps upload /path/to/sourcemaps --url-prefix '~/static/js' \
--strip-common-prefix
# Omit all files specified in .sentryignore
sentry-cli sourcemaps upload /path/to/sourcemaps --ignore-file .sentryignore
To list uploaded files, the following command can be used:
sentry-cli releases files "$VERSION" list
This will return a list of all uploaded files for that release.
You can also delete already uploaded files. Either by name or all files at once:
sentry-cli releases files "$VERSION" delete NAME_OF_FILE
sentry-cli releases files "$VERSION" delete --all
You can also associate deploys with releases. To create a deploy you first create a release and then a deploy for it. At the very least, you should supply the “environment” the deploy goes to (production, staging etc.). You can freely define this:
sentry-cli releases deploys "$VERSION" new -e ENVIRONMENT
Optionally, you can also define how long the deploy took:
start=$(date +%s)
...
now=$(date +%s)
sentry-cli releases deploys "$VERSION" new -e ENVIRONMENT -t $((now-start))
Deploys can be listed too (however they cannot be deleted):
sentry-cli releases deploys "$VERSION" list
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").