Connect an app

Connect an app deployed on the platform to a project, so every build and rollout gets the DSN, the environment and the release, and every build a source-map upload token of its own.

Last updated 18 November 2026View as Markdown

Nothing is copied or pasted: the app reads SENTRY_DSN the way the Sentry SDK expects, and the build uploads source maps with a token that is revoked when the build ends. Replace app-id with the app's id and project-id with the project's id.

Prerequisites

  • Permission for deploy:ManageErrorsBinding on the app and errors:UpdateProject on the project. To rebuild at once, also deploy:DeployApp on the app.
  • In the console, on the app's Environment tab: also deploy:DescribeApp on the app to open it (without it the app is not found), deploy:ManageEnv on the app (without it the tab shows the variables read-only, without the Error Tracking section), and errors:ListProjects on the service, rn:ews:de1:<organization id>:errors:*, to list the projects to choose from.
  • In the console, on the project's Setup tab: also errors:ListProjects on the project to open it, and deploy:DescribeApp on the service to list the apps. Connect & rebuild there always rebuilds, so it needs deploy:DeployApp too.

What the app gets

Variable When Value
SENTRY_DSN build and run time The DSN of the project's managed key
NEXT_PUBLIC_SENTRY_DSN build and run time The same DSN, for the browser bundle. Can be VITE_SENTRY_DSN, PUBLIC_SENTRY_DSN or none
SENTRY_ENVIRONMENT build and run time The environment you set, else the app's secrets environment, else production
SENTRY_RELEASE build and run time The deployment's commit; for an app from an image, its digest
NEXT_PUBLIC_SENTRY_ENVIRONMENT, NEXT_PUBLIC_SENTRY_RELEASE build The same environment and release
SENTRY_ORG, SENTRY_PROJECT, SENTRY_URL build What withSentryConfig and sentry-cli need
SENTRY_AUTH_TOKEN build, as a secret A token that may upload source maps to this project only, valid 30 minutes and revoked when the build ends, whatever its outcome

A variable the app defines itself always wins, so an app that still sends to another Sentry keeps its own settings. When the app defines its own SENTRY_AUTH_TOKEN, no token is minted for its builds. The build log says which token a build got, and afterwards whether source maps arrived.

The first connection to a project sets it up: a DSN key labelled Managed (connected apps and CI), an entry for its DSN in Secrets (ERRORS_<SLUG>_DSN, in the group managed/error-tracking, read-only there), and a service account that may only upload source maps to the project. Rotating the managed key never touches a DSN you pasted somewhere by hand.

Connect the app

From the app:

  1. Open the app, then its Environment tab.
  2. Under Error Tracking, for Project, choose the project.
  3. (Optional) Under Variable names and environment, choose the Browser DSN variable, and for Environment, enter the value of SENTRY_ENVIRONMENT.
  4. Choose Connect & rebuild to rebuild the live commit now, or Connect to wait for the next build.

Or from the project:

  1. Open the project, then the Setup tab.
  2. Under Connect an app, for App, choose the app. An app connected to another project shows "Now connected to" that project; connecting it here moves it.
  3. Choose Connect & rebuild.

Without deploy:DeployApp on the app, the app is connected all the same and nothing rebuilds: the console says "Connected. Saved, not rolled out: redeploying needs deploy:DeployApp on this app", and the next build and rollout get the variables.

With a Dockerfile

Builds pass the variables as build arguments and the token as a BuildKit secret, never a build argument, so it cannot end up in the image. Declare the arguments the browser bundle needs and mount the secret in the build step:

ARG NEXT_PUBLIC_SENTRY_DSN
ARG NEXT_PUBLIC_SENTRY_ENVIRONMENT
ARG SENTRY_RELEASE
ARG SENTRY_ORG
ARG SENTRY_PROJECT
ARG SENTRY_URL
RUN --mount=type=secret,id=SENTRY_AUTH_TOKEN,env=SENTRY_AUTH_TOKEN npm run build

Without the mount the build succeeds and uploads nothing; the build log then says "Error Tracking: no source maps were uploaded by this build".

Result

The app is listed under Connect an app on the project's Setup tab. An app that runs an image or a compose file built elsewhere gets the DSN at run time, but its browser bundle keeps what it was built with; the list marks it "Image built elsewhere: rebuild it yourself after a rotation".

When connecting is refused

  • 404 "Error Tracking project not found" when the project does not exist; 404 "App not found" when the app does not exist.
  • 400 "Two of the variables have the same name" when two variable names you chose are equal.
  • 409 "The app is being deleted".
  • 409 when the project's managed DSN entry cannot be filed in Secrets, with the reason, for example "No free Secrets name for …'s DSN".

Disconnect

On the app's Environment tab, under Error Tracking, choose Disconnect, or run dcloud deploy errors disconnect app-id. The project, its key and the Secrets entry stay; the next rollout no longer gets the variables.

Did this page help you?