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.
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:ManageErrorsBindingon the app anderrors:UpdateProjecton the project. To rebuild at once, alsodeploy:DeployAppon the app. - In the console, on the app's Environment tab: also
deploy:DescribeAppon the app to open it (without it the app is not found),deploy:ManageEnvon the app (without it the tab shows the variables read-only, without the Error Tracking section), anderrors:ListProjectson 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:ListProjectson the project to open it, anddeploy:DescribeAppon the service to list the apps. Connect & rebuild there always rebuilds, so it needsdeploy:DeployApptoo.
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:
- Open the app, then its Environment tab.
- Under Error Tracking, for Project, choose the project.
- (Optional) Under Variable names and environment, choose the Browser DSN variable, and
for Environment, enter the value of
SENTRY_ENVIRONMENT. - Choose Connect & rebuild to rebuild the live commit now, or Connect to wait for the next build.
Or from the project:
- Open the project, then the Setup tab.
- 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.
- 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.
dcloud deploy errors connect app-id --project-id project-id --redeployPUT /deploy/api/apps/app-id/errors
{ "projectId": "0b7f1f6c-9a4e-4d0e-8a51-6f0c2a7d3e11", "redeploy": true }The answer is 201 with the connection: the variable names, the effective environment, the DSN
and the Secrets entry, and redeploy, the rebuild's deployment or why it could not start.
resource "dcloud_app_errors_binding" "web" {
app_id = dcloud_app.web.id
project_id = dcloud_errors_project.web.id
}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 buildWithout 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".409when 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.