Early access is open. Stagd is free during the beta. Sign up
Guides

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

For language models and agents: this page as Markdown, or every page through llms.txt.