# Connect a CI environment

Connect an environment of a repository's CI to a project, so a job running in it exchanges its OIDC token for the DSN, the release and a source-map upload token, with no stored secret.

This is for workflows that run on Deutsche Cloud CI. For workflows on GitHub's own runners, see
[Upload source maps](upload-source-maps.md). Replace _project-id_ with the project's id,
_repository-id_ with the repository's id and _binding-id_ with the connection's id.

## Prerequisites

- Permission for `ci:PutEnvironment` on the repository and `errors:UpdateProject` on the project.
- In the console, also `errors:ListProjects` on the project to open it, and
  `ci:ListEnvironments` to list the repositories. The **Connect a CI environment** form appears
  only with `errors:UpdateProject` on the project and `ci:PutEnvironment`.

## Connect the environment

A repository's environment is connected to one project. Connecting it again, to this or another
project, replaces its connection. An environment that does not exist yet is created.

**Console**
1. Open the project, then the **Setup** tab.
2. Under **Connect a CI environment**, for **Repository**, choose the repository.
3. For **Environment**, enter the environment its jobs run in. The console proposes
   `production`.
4. Choose **Connect**.

The section then shows the workflow below with your values under **Workflow**.

**CLI**
```sh
dcloud errors connections connect-ci project-id --repository-id repository-id --environment production
```

`--sentry-environment` sets `SENTRY_ENVIRONMENT`; without it, the job gets the name of the
environment it runs in.

**API**
```http
POST /errors/api/projects/project-id/ci-bindings
{ "repositoryId": "3d1c2b7a-5e0f-4a8b-9c6d-2f4e1a0b7c95", "environment": "production" }
```

The answer is `201` with the connection and `audience`, the audience the job's OIDC token must
name.

- `400` "Not a valid environment name" when CI does not accept the name.
- `404` "Repository not found" when the repository does not exist; `404` "Error Tracking project
  not found" when the project does not exist.
- `409` when the project's managed DSN entry cannot be filed in Secrets, with the reason.

## Use it in a workflow

The job must run in the connected environment and may request an OIDC token:

```yaml
permissions:
  id-token: write
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - name: Error Tracking upload token (no stored secret)
        run: |
          AUD=$(jq -rn --arg a 'https://errors.example.com' '$a|@uri')
          OIDC_TOKEN=$(curl -sS --fail-with-body \
            -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
            "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=$AUD" | jq -r .value)
          OUT=$(curl -sS --fail-with-body -X POST 'https://console.example.com/errors/api/upload-token/exchange' \
            -H 'content-type: application/json' \
            -d "$(jq -n --arg t "$OIDC_TOKEN" '{webIdentityToken: $t}')")
          TOKEN=$(jq -r .data.token <<<"$OUT")
          echo "::add-mask::$TOKEN"
          {
            echo "SENTRY_AUTH_TOKEN=$TOKEN"
            echo "SENTRY_DSN=$(jq -r .data.dsn <<<"$OUT")"
            echo "NEXT_PUBLIC_SENTRY_DSN=$(jq -r .data.dsn <<<"$OUT")"
            echo "SENTRY_ENVIRONMENT=$(jq -r .data.environment <<<"$OUT")"
            echo "SENTRY_RELEASE=$(jq -r .data.release <<<"$OUT")"
          } >> "$GITHUB_ENV"
      - run: npm ci && npm run build
```

The audience is the Error Tracking URL (the **Sentry URL (sentry-cli)** on the **Setup** tab), not
the console's: a token requested for the console's STS is refused here. The exchange answers the
upload token, the DSN of the project's managed key, the environment and the release (the run's
commit). The upload token may upload source maps to the project only, lasts an hour, and is revoked
when the run ends.

## When the exchange is refused

- `403` "AccessDenied: pull-request runs get no upload token" for runs of `pull_request` and
  `pull_request_target`.
- `403` "AccessDenied: the job runs in no environment; give it `environment:` and connect that environment".
- `403` "AccessDenied: environment … of this repository is not connected to Error Tracking".
- `403` "AccessDenied: this run already holds 20 upload tokens".
- `403` "AccessDenied: the connected project is gone" when the project was deleted.
- `400` "InvalidIdentityToken: …" for a token that is expired, has another audience, or was not
  issued by Deutsche Cloud CI.
- `429` "Too many requests" after 60 exchanges a minute from one address.

## Disconnect

Through the CLI or the API, disconnecting needs only `ci:PutEnvironment` on the repository. The
console shows **Disconnect** only to those who may connect: `errors:UpdateProject` on the project
as well. Upload tokens already handed out stay valid until they expire.

**Console**
1. Open the project, then the **Setup** tab.
2. Under **Connect a CI environment**, on the repository's row, choose **Disconnect**.

**CLI**
```sh
dcloud errors connections disconnect-ci project-id binding-id
```

**API**
```http
DELETE /errors/api/projects/project-id/ci-bindings/binding-id
```

## Related

- [Connect an app](connect-an-app.md)
- [Rotate the managed key](rotate-the-managed-key.md)
- `errors.connections.connect-ci` · `dcloud errors connections connect-ci`
