# 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: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

**Console**
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.

**CLI**
```sh
dcloud deploy errors connect app-id --project-id project-id --redeploy
```

**API**
```http
PUT /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.

**Terraform**
```hcl
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:

```dockerfile
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.

## Related

- [Rotate the managed key](rotate-the-managed-key.md)
- [Connect a CI environment](connect-a-ci-environment.md)
- [Set environment variables](/docs/deploy/guide/set-environment-variables)
