|
| 1 | +--- |
| 2 | +title: "Code Mappings" |
| 3 | +sidebar_order: 5 |
| 4 | +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." |
| 5 | +--- |
| 6 | + |
| 7 | +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/). |
| 8 | + |
| 9 | +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`. |
| 10 | + |
| 11 | +## Permissions |
| 12 | + |
| 13 | +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. |
| 14 | + |
| 15 | +## Upload Code Mappings |
| 16 | + |
| 17 | +<Alert> |
| 18 | + |
| 19 | +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). |
| 20 | + |
| 21 | +</Alert> |
| 22 | + |
| 23 | +```bash |
| 24 | +sentry-cli code-mappings upload ./mappings.json \ |
| 25 | + --org my-org \ |
| 26 | + --project my-project \ |
| 27 | + --repo owner/repo \ |
| 28 | + --default-branch main |
| 29 | +``` |
| 30 | + |
| 31 | +### Options |
| 32 | + |
| 33 | +| Option | Required | Description | |
| 34 | +|--------|----------|-------------| |
| 35 | +| `--org` | Required | The organization slug. Can also be set via `SENTRY_ORG` or in `.sentryclirc`. | |
| 36 | +| `--project` | Required | The project slug. Can also be set via `SENTRY_PROJECT` or in `.sentryclirc`. | |
| 37 | +| `--repo` | Optional | The repository name (e.g. `getsentry/sentry`). Defaults to the git remote origin. Required if not running from within a git repository. | |
| 38 | +| `--default-branch` | Optional | The default branch name. Defaults to the git remote HEAD or `main`. Required if not running from within a git repository. | |
| 39 | + |
| 40 | +### JSON File Format |
| 41 | + |
| 42 | +The input file should be a JSON array of mapping objects, each with a `stackRoot` and `sourceRoot`. |
| 43 | + |
| 44 | +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: |
| 45 | + |
| 46 | +```json {filename:mappings.json} |
| 47 | +[ |
| 48 | + { |
| 49 | + "stackRoot": "io/sentry/android/core", |
| 50 | + "sourceRoot": "sentry-android-core/src/main/java/io/sentry/android/core" |
| 51 | + }, |
| 52 | + { |
| 53 | + "stackRoot": "io/sentry/opentelemetry", |
| 54 | + "sourceRoot": "sentry-opentelemetry/sentry-opentelemetry-core/src/main/java/io/sentry/opentelemetry" |
| 55 | + }, |
| 56 | + { |
| 57 | + "stackRoot": "io/sentry/opentelemetry", |
| 58 | + "sourceRoot": "sentry-opentelemetry/sentry-opentelemetry-bootstrap/src/main/java/io/sentry/opentelemetry" |
| 59 | + }, |
| 60 | + { |
| 61 | + "stackRoot": "io/sentry", |
| 62 | + "sourceRoot": "sentry/src/main/java/io/sentry" |
| 63 | + } |
| 64 | +] |
| 65 | +``` |
| 66 | + |
| 67 | +- **stackRoot**: The path prefix as it appears in stack traces (e.g. `io/sentry/android/core` for Java, `src/` for Python/JS). |
| 68 | +- **sourceRoot**: The corresponding path in your repository where the source code lives. |
| 69 | + |
| 70 | +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. |
| 71 | + |
| 72 | +### Batching |
| 73 | + |
| 74 | +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. |
| 75 | + |
| 76 | +### Output |
| 77 | + |
| 78 | +The CLI reports the result of each batch: |
| 79 | + |
| 80 | +``` |
| 81 | +Uploading 47 code mapping(s)... |
| 82 | +Created: 42, Updated: 5, Errors: 0 |
| 83 | +``` |
| 84 | + |
| 85 | +- **Created**: New mappings that were added. |
| 86 | +- **Updated**: Existing mappings (matched by project, stack root, and source root) whose metadata was updated. |
| 87 | +- **Errors**: Mappings that failed to save. |
| 88 | + |
| 89 | +If any errors occur, the CLI exits with a non-zero exit code and prints a table showing which mappings failed. |
| 90 | + |
| 91 | +## Stack Trace Root and Source Code Root |
| 92 | + |
| 93 | +<Include name="common-imgs/code-mappings-stacktrace" /> |
| 94 | + |
| 95 | +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: |
| 96 | + |
| 97 | +- `stackRoot`: `src/` |
| 98 | +- `sourceRoot`: `backend/src/` |
| 99 | + |
| 100 | +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). |
| 101 | + |
| 102 | +## CI/CD Integration |
| 103 | + |
| 104 | +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: |
| 105 | + |
| 106 | +```bash |
| 107 | +sentry-cli code-mappings upload ./mappings.json \ |
| 108 | + --org $SENTRY_ORG \ |
| 109 | + --project $SENTRY_PROJECT \ |
| 110 | + --repo $GITHUB_REPOSITORY \ |
| 111 | + --default-branch $GITHUB_REF_NAME |
| 112 | +``` |
| 113 | + |
| 114 | +For authentication, set the `SENTRY_AUTH_TOKEN` environment variable. See [Configuration](/cli/configuration/) for details. |
0 commit comments