From 6d06adb11ea60d85f497852d041993fe4ae9ef5a Mon Sep 17 00:00:00 2001 From: Roman Zavarnitsyn Date: Tue, 31 Mar 2026 17:54:17 +0200 Subject: [PATCH 1/4] docs(cli): Add code mappings documentation page Add a new CLI docs page for code mappings with upload command usage, JSON format, options, batching, and CI/CD integration. Also add backlinks from suspect commits, Java source context, and GitHub integration pages. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/cli/code-mappings.mdx | 114 ++++++++++++++++++ docs/cli/index.mdx | 2 +- .../source-code-mgmt/github/index.mdx | 2 +- .../java/common/source-context/index.mdx | 2 +- docs/product/issues/suspect-commits/index.mdx | 2 + 5 files changed, 119 insertions(+), 3 deletions(-) create mode 100644 docs/cli/code-mappings.mdx diff --git a/docs/cli/code-mappings.mdx b/docs/cli/code-mappings.mdx new file mode 100644 index 0000000000000..8f3f368a1a6a1 --- /dev/null +++ b/docs/cli/code-mappings.mdx @@ -0,0 +1,114 @@ +--- +title: "Code Mappings" +sidebar_order: 5 +description: "Upload code mappings to Sentry via the CLI. Code mappings link stack trace paths to source code paths in your repository, enabling source context, suspect commits, and code owners." +--- + +Code mappings link stack trace paths to source code paths in your repository. They enable features like [source context](/platforms/java/source-context/), [suspect commits](/product/issues/suspect-commits/), [stack trace linking](/organization/integrations/source-code-mgmt/github/#stack-trace-linking), and [code owners](/product/issues/ownership-rules/). + +You can manage code mappings through the Sentry web UI (see [Setting Up Code Mappings](/product/issues/suspect-commits/#set-up-code-mappings)), or upload them in bulk using `sentry-cli`. + +## Permissions + +The `sentry-cli` requires an [Organization Token](https://sentry.io/orgredirect/organizations/:orgslug/settings/auth-tokens/) with the `org:ci` scope to upload code mappings. + +## Upload Code Mappings + + + +You need to specify the organization and project you are working with because code mappings work on projects. For more information about this refer to [Working with Projects](/cli/configuration/#sentry-cli-working-with-projects). + + + +```bash +sentry-cli code-mappings upload ./mappings.json \ + --org my-org \ + --project my-project \ + --repo owner/repo \ + --default-branch main +``` + +### Options + +| Option | Required | Description | +|--------|----------|-------------| +| `--org` | Required | The organization slug. Can also be set via `SENTRY_ORG` or in `.sentryclirc`. | +| `--project` | Required | The project slug. Can also be set via `SENTRY_PROJECT` or in `.sentryclirc`. | +| `--repo` | Optional | The repository name (e.g. `getsentry/sentry`). Defaults to the git remote origin. Required if not running from within a git repository. | +| `--default-branch` | Optional | The default branch name. Defaults to the git remote HEAD or `main`. Required if not running from within a git repository. | + +### JSON File Format + +The input file should be a JSON array of mapping objects, each with a `stackRoot` and `sourceRoot`. + +The following example is based on the [getsentry/sentry-java](https://github.com/getsentry/sentry-java) monorepo, which has multiple modules sharing the `io/sentry` package prefix: + +```json {filename:mappings.json} +[ + { + "stackRoot": "io/sentry/android/core", + "sourceRoot": "sentry-android-core/src/main/java/io/sentry/android/core" + }, + { + "stackRoot": "io/sentry/opentelemetry", + "sourceRoot": "sentry-opentelemetry/sentry-opentelemetry-core/src/main/java/io/sentry/opentelemetry" + }, + { + "stackRoot": "io/sentry/opentelemetry", + "sourceRoot": "sentry-opentelemetry/sentry-opentelemetry-bootstrap/src/main/java/io/sentry/opentelemetry" + }, + { + "stackRoot": "io/sentry", + "sourceRoot": "sentry/src/main/java/io/sentry" + } +] +``` + +- **stackRoot**: The path prefix as it appears in stack traces (e.g. `io/sentry/android/core` for Java, `src/` for Python/JS). +- **sourceRoot**: The corresponding path in your repository where the source code lives. + +Multiple mappings can share the same `stackRoot` if they point to different `sourceRoot` paths. In the example above, `io/sentry/opentelemetry` maps to two different modules. Sentry evaluates mappings from most specific to least specific, using the first one that resolves to a real file in the repository. + +### Batching + +Mappings are uploaded in batches of up to 300 per request. If your file contains more than 300 mappings, the CLI will automatically split them into multiple batches. + +### Output + +The CLI reports the result of each batch: + +``` +Uploading 47 code mapping(s)... +Created: 42, Updated: 5, Errors: 0 +``` + +- **Created**: New mappings that were added. +- **Updated**: Existing mappings (matched by project, stack root, and source root) whose metadata was updated. +- **Errors**: Mappings that failed to save. + +If any errors occur, the CLI exits with a non-zero exit code and prints a table showing which mappings failed. + +## Stack Trace Root and Source Code Root + + + +For platforms that use file paths in stack traces (Python, JavaScript, etc.), the `stackRoot` and `sourceRoot` are typically file path prefixes. For example, if your stack traces show `src/app/utils.py` and the file lives at `backend/src/app/utils.py` in your repo: + +- `stackRoot`: `src/` +- `sourceRoot`: `backend/src/` + +For Java and other JVM languages, stack traces use package names (e.g. `com.example.app.MyClass`), which are converted to paths (`com/example/app`). The `sourceRoot` is the path in the repository to the corresponding source directory. Read more in the [Java source context docs](/platforms/java/source-context/#setting-up-code-mappings). + +## CI/CD Integration + +You can run `sentry-cli code-mappings upload` as part of your CI/CD pipeline to keep code mappings in sync with your repository structure: + +```bash +sentry-cli code-mappings upload ./mappings.json \ + --org $SENTRY_ORG \ + --project $SENTRY_PROJECT \ + --repo $GITHUB_REPOSITORY \ + --default-branch $GITHUB_REF_NAME +``` + +For authentication, set the `SENTRY_AUTH_TOKEN` environment variable. See [Configuration](/cli/configuration/) for details. diff --git a/docs/cli/index.mdx b/docs/cli/index.mdx index 01055f3370136..332c998bb2c97 100644 --- a/docs/cli/index.mdx +++ b/docs/cli/index.mdx @@ -18,6 +18,6 @@ These docs cover `sentry-cli`, used in CI/CD pipelines and build processes. If y -For certain actions, you can use the `sentry-cli` command line executable. It can connect to the Sentry API and manage some data for your projects. It’s primarily used for managing debug information files for iOS, Android as well as release and source maps management for other platforms. +For certain actions, you can use the `sentry-cli` command line executable. It can connect to the Sentry API and manage some data for your projects. It’s primarily used for managing debug information files for iOS, Android, release and source maps management, as well as [code mappings](/cli/code-mappings/) for other platforms. diff --git a/docs/organization/integrations/source-code-mgmt/github/index.mdx b/docs/organization/integrations/source-code-mgmt/github/index.mdx index 18a9486460a75..525a5ea6db919 100644 --- a/docs/organization/integrations/source-code-mgmt/github/index.mdx +++ b/docs/organization/integrations/source-code-mgmt/github/index.mdx @@ -377,7 +377,7 @@ By default, this feature is automatically enabled once your GitHub integration h -Sentry will automatically try to set up code mappings on JavaScript, Python, Java, PHP, Ruby, Go, C#, and Kotlin for organizations with the GitHub integration installed. If your project uses a different SDK, you can add code mappings manually. +Sentry will automatically try to set up code mappings on JavaScript, Python, Java, PHP, Ruby, Go, C#, and Kotlin for organizations with the GitHub integration installed. If your project uses a different SDK, you can add code mappings manually. You can also [upload code mappings in bulk via the CLI](/cli/code-mappings/). diff --git a/docs/platforms/java/common/source-context/index.mdx b/docs/platforms/java/common/source-context/index.mdx index fa33aaeb874dd..6546090778b54 100644 --- a/docs/platforms/java/common/source-context/index.mdx +++ b/docs/platforms/java/common/source-context/index.mdx @@ -10,7 +10,7 @@ og_image: /og-images/platforms-java-common-source-context.png ## Setting Up Code Mappings -To use suspect commits and stack trace linking, you'll need to set up a code mapping. This is a mapping between the source code in your repository and the source code in your stack traces. You can find information on how to set up code mappings in our [Set Up Code Mappings](/product/issues/suspect-commits/#2-set-up-code-mappings) docs. +To use suspect commits and stack trace linking, you'll need to set up a code mapping. This is a mapping between the source code in your repository and the source code in your stack traces. You can find information on how to set up code mappings in our [Set Up Code Mappings](/product/issues/suspect-commits/#2-set-up-code-mappings) docs. For projects with many modules, you can also [upload code mappings in bulk via the CLI](/cli/code-mappings/). Use the following steps to determine the correct **Stack Trace Root** **Source Code Root** while setting up your code mapping: diff --git a/docs/product/issues/suspect-commits/index.mdx b/docs/product/issues/suspect-commits/index.mdx index e0bd8a27a7204..0ca9dcbb27f0a 100644 --- a/docs/product/issues/suspect-commits/index.mdx +++ b/docs/product/issues/suspect-commits/index.mdx @@ -45,6 +45,8 @@ In [sentry.io](https://sentry.io): Sentry will automatically try to set up code mappings on JavaScript, Python, Java, PHP, Ruby, Go, C#, and Kotlin projects for organizations with the GitHub integration installed. However, you can still manually add code mappings if you choose to do so. Support for other languages and other source code integrations are planned. +You can also upload code mappings in bulk using the [Sentry CLI](/cli/code-mappings/). + 1. Go to **Settings > Integrations > [Integration] > Configurations**. From df548ee9867be7ef069b4283ddd65eeb20995b07 Mon Sep 17 00:00:00 2001 From: Roman Zavarnitsyn Date: Wed, 1 Apr 2026 15:31:56 +0200 Subject: [PATCH 2/4] docs(cli): Address review feedback on code mappings page - Simplify command example to minimal invocation - Remove options table, point to --help instead - Remove batching, output, CI/CD, and stack trace root sections - Reorder JSON format (description first, then example) - Mention CI usage at the top instead of separate section - Keep code mappings mention in CLI index without link - Fix broken link in Java source context page Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/cli/code-mappings.mdx | 82 ++++++-------------------------------- docs/cli/index.mdx | 2 +- 2 files changed, 14 insertions(+), 70 deletions(-) diff --git a/docs/cli/code-mappings.mdx b/docs/cli/code-mappings.mdx index 8f3f368a1a6a1..a2545ef734549 100644 --- a/docs/cli/code-mappings.mdx +++ b/docs/cli/code-mappings.mdx @@ -6,40 +6,32 @@ description: "Upload code mappings to Sentry via the CLI. Code mappings link sta Code mappings link stack trace paths to source code paths in your repository. They enable features like [source context](/platforms/java/source-context/), [suspect commits](/product/issues/suspect-commits/), [stack trace linking](/organization/integrations/source-code-mgmt/github/#stack-trace-linking), and [code owners](/product/issues/ownership-rules/). -You can manage code mappings through the Sentry web UI (see [Setting Up Code Mappings](/product/issues/suspect-commits/#set-up-code-mappings)), or upload them in bulk using `sentry-cli`. +You can [manage code mappings through the Sentry web UI](/product/issues/suspect-commits/#set-up-code-mappings), or upload them in bulk using Sentry CLI. It is also possible to upload code mappings automatically in your CI process to keep them in sync with your repository structure. ## Permissions -The `sentry-cli` requires an [Organization Token](https://sentry.io/orgredirect/organizations/:orgslug/settings/auth-tokens/) with the `org:ci` scope to upload code mappings. +Sentry CLI requires an [Organization Token](https://sentry.io/orgredirect/organizations/:orgslug/settings/auth-tokens/) with the `org:ci` scope to upload code mappings. ## Upload Code Mappings - - -You need to specify the organization and project you are working with because code mappings work on projects. For more information about this refer to [Working with Projects](/cli/configuration/#sentry-cli-working-with-projects). - - +Use the `sentry-cli code-mappings upload` command to upload code mappings: ```bash -sentry-cli code-mappings upload ./mappings.json \ - --org my-org \ - --project my-project \ - --repo owner/repo \ - --default-branch main +sentry-cli code-mappings upload ./mappings.json ``` -### Options - -| Option | Required | Description | -|--------|----------|-------------| -| `--org` | Required | The organization slug. Can also be set via `SENTRY_ORG` or in `.sentryclirc`. | -| `--project` | Required | The project slug. Can also be set via `SENTRY_PROJECT` or in `.sentryclirc`. | -| `--repo` | Optional | The repository name (e.g. `getsentry/sentry`). Defaults to the git remote origin. Required if not running from within a git repository. | -| `--default-branch` | Optional | The default branch name. Defaults to the git remote HEAD or `main`. Required if not running from within a git repository. | +Run `sentry-cli code-mappings upload --help` to see all available options. ### JSON File Format -The input file should be a JSON array of mapping objects, each with a `stackRoot` and `sourceRoot`. +The input file should be a JSON array of mapping objects, each with a `stackRoot` and `sourceRoot`: + +- **stackRoot**: The path prefix as it appears in stack traces (e.g. `io/sentry/android/core` for Java, `src/` for Python/JS). +- **sourceRoot**: The corresponding path in your repository where the source code lives. + +Multiple mappings can share the same `stackRoot` if they point to different `sourceRoot` paths. This is useful for monorepos where the same package prefix exists in multiple modules. Sentry evaluates mappings from most specific to least specific, using the first one that resolves to a real file in the repository. + +#### Example The following example is based on the [getsentry/sentry-java](https://github.com/getsentry/sentry-java) monorepo, which has multiple modules sharing the `io/sentry` package prefix: @@ -64,51 +56,3 @@ The following example is based on the [getsentry/sentry-java](https://github.com ] ``` -- **stackRoot**: The path prefix as it appears in stack traces (e.g. `io/sentry/android/core` for Java, `src/` for Python/JS). -- **sourceRoot**: The corresponding path in your repository where the source code lives. - -Multiple mappings can share the same `stackRoot` if they point to different `sourceRoot` paths. In the example above, `io/sentry/opentelemetry` maps to two different modules. Sentry evaluates mappings from most specific to least specific, using the first one that resolves to a real file in the repository. - -### Batching - -Mappings are uploaded in batches of up to 300 per request. If your file contains more than 300 mappings, the CLI will automatically split them into multiple batches. - -### Output - -The CLI reports the result of each batch: - -``` -Uploading 47 code mapping(s)... -Created: 42, Updated: 5, Errors: 0 -``` - -- **Created**: New mappings that were added. -- **Updated**: Existing mappings (matched by project, stack root, and source root) whose metadata was updated. -- **Errors**: Mappings that failed to save. - -If any errors occur, the CLI exits with a non-zero exit code and prints a table showing which mappings failed. - -## Stack Trace Root and Source Code Root - - - -For platforms that use file paths in stack traces (Python, JavaScript, etc.), the `stackRoot` and `sourceRoot` are typically file path prefixes. For example, if your stack traces show `src/app/utils.py` and the file lives at `backend/src/app/utils.py` in your repo: - -- `stackRoot`: `src/` -- `sourceRoot`: `backend/src/` - -For Java and other JVM languages, stack traces use package names (e.g. `com.example.app.MyClass`), which are converted to paths (`com/example/app`). The `sourceRoot` is the path in the repository to the corresponding source directory. Read more in the [Java source context docs](/platforms/java/source-context/#setting-up-code-mappings). - -## CI/CD Integration - -You can run `sentry-cli code-mappings upload` as part of your CI/CD pipeline to keep code mappings in sync with your repository structure: - -```bash -sentry-cli code-mappings upload ./mappings.json \ - --org $SENTRY_ORG \ - --project $SENTRY_PROJECT \ - --repo $GITHUB_REPOSITORY \ - --default-branch $GITHUB_REF_NAME -``` - -For authentication, set the `SENTRY_AUTH_TOKEN` environment variable. See [Configuration](/cli/configuration/) for details. diff --git a/docs/cli/index.mdx b/docs/cli/index.mdx index 332c998bb2c97..9b56d5d463c9e 100644 --- a/docs/cli/index.mdx +++ b/docs/cli/index.mdx @@ -18,6 +18,6 @@ These docs cover `sentry-cli`, used in CI/CD pipelines and build processes. If y -For certain actions, you can use the `sentry-cli` command line executable. It can connect to the Sentry API and manage some data for your projects. It’s primarily used for managing debug information files for iOS, Android, release and source maps management, as well as [code mappings](/cli/code-mappings/) for other platforms. +For certain actions, you can use the `sentry-cli` command line executable. It can connect to the Sentry API and manage some data for your projects. It’s primarily used for managing debug information files for iOS, Android, release and source maps management, as well as code mappings for other platforms. From 6dc17edb341054e0c7e31d5195485621202877a9 Mon Sep 17 00:00:00 2001 From: Roman Zavarnitsyn Date: Wed, 1 Apr 2026 15:44:53 +0200 Subject: [PATCH 3/4] Apply suggestion from @romtsn --- docs/platforms/java/common/source-context/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/java/common/source-context/index.mdx b/docs/platforms/java/common/source-context/index.mdx index 6546090778b54..b7a06bb36decd 100644 --- a/docs/platforms/java/common/source-context/index.mdx +++ b/docs/platforms/java/common/source-context/index.mdx @@ -10,7 +10,7 @@ og_image: /og-images/platforms-java-common-source-context.png ## Setting Up Code Mappings -To use suspect commits and stack trace linking, you'll need to set up a code mapping. This is a mapping between the source code in your repository and the source code in your stack traces. You can find information on how to set up code mappings in our [Set Up Code Mappings](/product/issues/suspect-commits/#2-set-up-code-mappings) docs. For projects with many modules, you can also [upload code mappings in bulk via the CLI](/cli/code-mappings/). +To use suspect commits and stack trace linking, you'll need to set up a code mapping. This is a mapping between the source code in your repository and the source code in your stack traces. You can [set up code mappings manually in the Sentry UI](/product/issues/suspect-commits/#set-up-code-mappings) or [upload code mappings in bulk via Sentry CLI](/cli/code-mappings/). We recommend using the CLI if your project has many modules. Use the following steps to determine the correct **Stack Trace Root** **Source Code Root** while setting up your code mapping: From 486f541c72aa17fe34b21212585f1a374fb21d0d Mon Sep 17 00:00:00 2001 From: Roman Zavarnitsyn Date: Tue, 7 Apr 2026 13:40:42 +0200 Subject: [PATCH 4/4] Update docs/cli/code-mappings.mdx --- docs/cli/code-mappings.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/cli/code-mappings.mdx b/docs/cli/code-mappings.mdx index a2545ef734549..079dce24e2882 100644 --- a/docs/cli/code-mappings.mdx +++ b/docs/cli/code-mappings.mdx @@ -3,6 +3,7 @@ title: "Code Mappings" sidebar_order: 5 description: "Upload code mappings to Sentry via the CLI. Code mappings link stack trace paths to source code paths in your repository, enabling source context, suspect commits, and code owners." --- +_Available in version 3.3.4 of Sentry CLI_ Code mappings link stack trace paths to source code paths in your repository. They enable features like [source context](/platforms/java/source-context/), [suspect commits](/product/issues/suspect-commits/), [stack trace linking](/organization/integrations/source-code-mgmt/github/#stack-trace-linking), and [code owners](/product/issues/ownership-rules/).