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:
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 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 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 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 forus-east-1on Amazon S3, orautoelsewhere; R2 wantsauto. - 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
- R2:
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 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 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
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.