# Connect integrations

> Connect the services previews use besides compute: a Neon branch per preview, and the storage your seeds are kept in (Azure Blob Storage, S3, Google Cloud Storage).

Integrations are the services your previews use besides compute:

- **Neon** gives each preview its own branch of your database.
- **Azure Blob Storage, S3 and Google Cloud Storage** hold your seeds: the database dumps a preview's database starts from. A preview can also fork an Azure container or an S3 bucket.

Admins connect them under **Settings → Integrations**, or with the CLI:

```sh
stagd integrations kinds
stagd integrations connect azure-blob --name seeds
```

Stagd checks the values with the service and saves them only if they work. Secrets are stored encrypted. Previews never see your credentials; they get their seed through Stagd. [Seed data without personal data](https://stagd.dev/docs/guides/seed-data.md) makes a seed to keep there.

Where a service lets it, Stagd can **sign in as Stagd** instead of keeping a key. Your cloud trusts Stagd for your workspace, so there's no secret to store, and nothing that expires or needs rotating. To cut Stagd off, remove the trust. [Sign in as Stagd](https://stagd.dev/docs/guides/sign-in-as-stagd.md) sets it up.

| Integration | Sign in with |
|---|---|
| Neon | An API key |
| Azure Blob Storage | A SAS token, or Stagd |
| S3 and compatible | An access key, or Stagd through an IAM role (Amazon S3 only) |
| Google Cloud Storage | Stagd |

## Neon

Stagd needs an **organization API key**, so it can reach every project: Neon → Organization settings → API keys.

By default a preview may fork any branch its `stagd.yaml` names, production's too. Anyone who can open a pull request can change `stagd.yaml`, so you can limit which branches may be forked: turn on **Only some branches may be forked** and list them, one per line (or comma-separated), as `<project>/<branch>`. A branch is named by id or by name, as `stagd.yaml` names it, for example `billowing-sound-61277569/br-broad-heart-a2qzljrk`. Stagd refuses any other.

## Azure Blob Storage

Give the storage account's name (for example `stacmeseeds`) and the container your dumps are in (for example `seeds`). Then choose how Stagd signs in.

Stagd reaches the account from Cloudflare's network, so the account's networking has to allow public access.

### With a SAS token

Make a SAS for the container that allows **Read and List** and nothing else, expiring a year from now: Azure Portal → the container → Shared access tokens. Paste it with or without its leading `?`.

Stagd keeps the token encrypted, reads its expiry, and adds a task to Home 30 days before it ends. A preview that forks the container gets the token, for blobfork to read with. The app in the preview never does.

### As Stagd

Stagd signs in through an app registration that trusts it for your workspace, with Storage Blob Data Reader on the container. Nothing secret is stored and nothing expires. [Sign in as Stagd](https://stagd.dev/docs/guides/sign-in-as-stagd.md#azure) sets it up step by step; in Stagd you then give the **tenant id** and **client id**.

A preview can't fork the container this way yet. Forks still need a SAS token.

## S3 and compatible

One kind covers Amazon S3, Cloudflare R2, Google Cloud Storage with an HMAC key, MinIO, Hetzner and DigitalOcean Spaces. Give:

- **Bucket:** for example `acme-seeds`.
- **Region:** for example `eu-north-1`. Leave it empty for `us-east-1` on Amazon S3, or `auto` elsewhere; R2 wants `auto`.
- **Endpoint:** only for stores other than Amazon S3:
  - R2: `https://<account id>.r2.cloudflarestorage.com`
  - Google Cloud Storage: `https://storage.googleapis.com`
  - MinIO: your server's address

### With an access key

Make a key that may list the bucket and read its objects (`s3:ListBucket`, `s3:GetObject`) and nothing else. Stagd keeps it encrypted. A preview that forks the bucket gets it, for blobfork to read with. The app in the preview never does.

### As Stagd, through an IAM role

On Amazon S3 only, Stagd can assume an IAM role that trusts it for your workspace, with no key stored. [Sign in as Stagd](https://stagd.dev/docs/guides/sign-in-as-stagd.md#aws) sets it up step by step; in Stagd you then give the **role ARN** and leave the endpoint empty.

A preview can't fork the bucket this way yet. Forks still need an access key.

## Google Cloud Storage

Stagd reads the bucket as itself, through workload identity federation, so you need no service account and no key. [Sign in as Stagd](https://stagd.dev/docs/guides/sign-in-as-stagd.md#google-cloud) sets it up step by step. In Stagd you then give the bucket, the **project number** (the number, not the id), the pool and the provider.

To read Google Cloud Storage with an HMAC key instead, use the S3 kind with the endpoint `https://storage.googleapis.com`.

## Check and remove

```sh
stagd integrations list
stagd integrations test seeds
stagd integrations delete seeds
```

An integration can't be deleted while a preview still has something from it, such as a Neon branch.
