Supported providers

• First-class ops: the plan format. Recipes: Recipes.
• What is covered and what is not, and why: Provider coverage.
• A provider that is missing: add a recipe (one YAML file; its detect block makes sponson init find it), see CONTRIBUTING.md.

​

Deploy targets and their environment variables

​

Vercel

• Ops: vercel.env, vercel.deploy
• Credential: VERCEL_TOKEN
• Token: create it: A token whose Scope is the team that owns the project, with an expiration. sponson init --setup checks it with one read-only request.
• Detected by sponson init from: vercel, @vercel/*, vercel.json, .vercel/project.json, VERCEL_*

# from examples/clerk-preview-callbacks.plan.yaml
providers:
  vercel: { project: prj_acme_web }
changes:
  - id: env
    adapter: vercel
    op: env
    target: preview
    values:
      DATABASE_URL: { from: db.connection_string }
      CLERK_SECRET_KEY: { secret: env://CLERK_PREVIEW_SECRET_KEY }
    environments: [preview]

​

Netlify

• Ops: netlify.env
• Credential: NETLIFY_AUTH_TOKEN
• Token: create it: A personal access token (Netlify tokens have no scopes) with an expiration; allow access to a SAML-protected team if yours enforces SSO. sponson init --setup checks it with one read-only request.
• Detected by sponson init from: @netlify/*, netlify-cli, netlify.toml, .netlify/state.json, NETLIFY_*

# from examples/netlify-neon-preview.plan.yaml
providers:
  netlify: { site: 3f1c2a9e-0b7d-4e55-9c1a-acme00000001 }
changes:
  - id: env
    adapter: netlify
    op: env
    values:
      DATABASE_URL: { from: db.connection_string }
    environments: [preview]

​

Cloudflare Pages / Workers

• Ops: cloudflare.pages_env
• Credential: CLOUDFLARE_API_TOKEN
• Token: create it: A custom token with Account > Cloudflare Pages > Edit, limited to the one account. sponson init --setup checks it with one read-only request.
• Detected by sponson init from: wrangler, @cloudflare/next-on-pages, wrangler.json, wrangler.jsonc, wrangler.toml, CLOUDFLARE_*

# from examples/cloudflare-pages-vars.plan.yaml
providers:
  cloudflare: { account: 0123456789abcdef0123456789abcdef, project: acme-web }
changes:
  - id: pages-preview
    adapter: cloudflare
    op: pages_env
    vars: { PUBLIC_API_URL: https://api.staging.acme.dev, PUBLIC_STAGE: preview }
    secrets:
      STRIPE_SECRET_KEY: { secret: env://STRIPE_TEST_SECRET_KEY }
    environments: [preview]

​

Render

• Ops: recipe render.env_var
• Credential: RENDER_API_KEY (bearer)
• Token: create it: An API key; Render keys have no scopes and reach every workspace of the user who creates them. sponson init --setup checks it with GET /owners.
• Detected by sponson init from: render.yaml, RENDER_*

# under changes: (no provider block needed)
- id: env_var
  adapter: http
  op: resource
  recipe: render.env_var
  service_id: srv-d0a1b2c3d4e5f6g7h8i9
  key: API_URL
  value: https://api-${ctx.scope}.example.com

​

Railway

• Ops: recipe railway.variable
• Credential: RAILWAY_API_TOKEN (bearer)
• Token: create it: A workspace token for the workspace that holds the project. sponson init --setup cannot check it (no read-only request every such credential may send).
• Detected by sponson init from: railway.json, railway.toml, RAILWAY_*

# under changes: (no provider block needed)
- id: variable
  adapter: http
  op: resource
  recipe: railway.variable
  project_id: prj-railway-demo
  environment_id: env-pr-42
  service_id: svc-web
  name: API_URL
  value: https://api-${ctx.scope}.example.app

​

Fly.io

• Ops: recipe fly_machines.app, recipe fly.secret
• Credential: FLY_API_TOKEN (bearer)
• Token: create it: An org token (fly tokens create org): it creates and deletes apps in the organization. sponson init --setup cannot check it (no read-only request every such credential may send).
• Token: create it: A deploy token for the one app (fly tokens create deploy -a <app>), or an org token (fly tokens create org) for an app per PR. sponson init --setup cannot check it (no read-only request every such credential may send).
• Detected by sponson init from: fly.toml, FLY_*

# under changes: (no provider block needed)
- id: app
  adapter: http
  op: resource
  recipe: fly_machines.app
  app_name: demo-${ctx.scope}
  org_slug: acme

​

Heroku

• Ops: recipe heroku.config_var
• Credential: HEROKU_API_KEY (bearer)
• Token: create it: A long-lived authorization from heroku authorizations:create -s write-protected: the narrowest scope that reads and writes config vars. sponson init --setup cannot check it (no read-only request every such credential may send).
• Detected by sponson init from: heroku.yml, HEROKU_*

# under changes: (no provider block needed)
- id: config_var
  adapter: http
  op: list_item
  recipe: heroku.config_var
  app: myapp-${ctx.scope}
  key: API_URL
  value: https://api-${ctx.scope}.example.com

​

AWS Amplify

• Ops: recipe amplify.branch, recipe amplify.branch_variable
• Credential: AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (AWS SigV4, amplify in us-east-1)
• Token: create it: An IAM user’s access key whose policy allows amplify:ListApps, amplify:GetBranch, amplify:CreateBranch, amplify:UpdateBranch and amplify:DeleteBranch on the app. sponson init --setup checks it with GET /apps.
• Detected by sponson init from: amplify.yml

# under changes: (no provider block needed)
- id: branch
  adapter: http
  op: resource
  recipe: amplify.branch
  app_id: d1demo
  branch_name: ${ctx.scope}
  stage: PULL_REQUEST
  description: Preview of ${ctx.scope}

​

Google Cloud Run

• Ops: cloud_run.revision
• Credential: the token gcloud auth print-access-token prints (bearer)
• Token: set up access: Sign in with gcloud auth login as an identity holding Cloud Run Developer (roles/run.developer) and Service Account User on the service’s runtime service account. sponson init --setup shows this; there is no token to store.
• Detected by sponson init from: @google-cloud/run, CLOUD_RUN_*, K_SERVICE

# from examples/cloud-run-neon-preview.plan.yaml
providers:
  cloud_run: { project: acme-web-prod, region: europe-west1 }
changes:
  - id: preview
    adapter: cloud_run
    op: revision
    service: web
    image: europe-west1-docker.pkg.dev/acme-web-prod/web/app:${ctx.git.sha}
    env:
      DATABASE_URL: { from: db.connection_string }
      SESSION_SECRET: { secret: env://PREVIEW_SESSION_SECRET }
      APP_ENV: preview
    environments: [preview]

​

Azure Static Web Apps

• Ops: recipe azure_swa.build_app_setting
• Credential: the token az account get-access-token --query accessToken -o tsv prints (bearer)
• Token: set up access: Sign in with az login as an identity holding Contributor on the static web app (or a custom role with Microsoft.Web/staticSites/*). sponson init --setup shows this; there is no token to store.
• Detected by sponson init from: staticwebapp.config.json, AZURE_STATIC_WEB_APPS_*

# under changes: (no provider block needed)
- id: build_app_setting
  adapter: http
  op: list_item
  recipe: azure_swa.build_app_setting
  subscription_id: 00000000-0000-0000-0000-000000000000
  resource_group: rg-web
  site: web
  environment: "42"
  name: API_URL
  value: https://api-${ctx.scope}.example.app

​

DigitalOcean App Platform

• Ops: digitalocean.app
• Credential: DIGITALOCEAN_ACCESS_TOKEN
• Token: create it: A personal access token with Custom Scopes: app:read and app:update. sponson init --setup checks it with one read-only request.
• Detected by sponson init from: .do/app.yaml, .do/deploy.template.yaml, DIGITALOCEAN_*

# from scenarios/adapters/digitalocean.yaml
changes:
  - id: web
    adapter: digitalocean
    op: app
    spec:
      name: web-${ctx.scope}
      services:
        - name: web
          github: { repo: acme/web, branch: "${ctx.git.branch}" }
      envs:
        - key: API_URL
          value: https://api-${ctx.scope}.example.com
          scope: RUN_AND_BUILD_TIME
        - key: DATABASE_URL
          value: { secret: env://DO_SCENARIO_DB_URL }
          type: SECRET
    environments: [preview]

​

Firebase Hosting

• Ops: recipe firebase_hosting.channel
• Credential: the token gcloud auth print-access-token prints (bearer)
• Token: set up access: Sign in with gcloud auth login (or activate a service account) as an identity holding Firebase Hosting Admin (roles/firebasehosting.admin) on the project. sponson init --setup shows this; there is no token to store.
• Detected by sponson init from: .github/workflows/firebase-hosting-pull-request.yml

# under changes: (no provider block needed)
- id: channel
  adapter: http
  op: resource
  recipe: firebase_hosting.channel
  site: demo-project
  channel_id: ${ctx.scope}

​

Databases with branching or per-PR instances

​

Neon

• Ops: neon.branch
• Credential: NEON_API_KEY
• Token: create it: A project-scoped API key for the one project (an organization admin creates it); otherwise a personal API key. sponson init --setup checks it with one read-only request.
• Detected by sponson init from: @neondatabase/*, @prisma/adapter-neon, neonctl, .neon, NEON_*, database URL on *.neon.tech

# from examples/adopting-an-existing-project.plan.yaml
providers:
  neon: { project: proj_acme_db }
changes:
  - id: db-staging
    adapter: neon
    op: branch
    name: staging
    environments: [preview]

​

Supabase

• Ops: supabase.branch
• Credential: SUPABASE_ACCESS_TOKEN
• Token: create it: A personal access token limited to the project, with Development Branches, Auth Config and Project Settings set to Read-write. sponson init --setup checks it with one read-only request.
• Detected by sponson init from: @supabase/*, supabase/config.toml, supabase/.temp/project-ref, SUPABASE_*, database URL on *.supabase.co, database URL on *.supabase.com

# from examples/nextjs-supabase-preview.plan.yaml
providers:
  supabase: { project: acmewebprojectrefxyz }
changes:
  - id: db
    adapter: supabase
    op: branch
    environments: [preview]

​

PlanetScale

• Ops: planetscale.branch, planetscale.password
• Credential: PLANETSCALE_SERVICE_TOKEN_ID + PLANETSCALE_SERVICE_TOKEN
• Token: create it: A service token with create_branch, delete_branch, read_branch and connect_branch (and delete_branch_password) on the one database. sponson init --setup checks it with one read-only request.
• Detected by sponson init from: @planetscale/*, PLANETSCALE_*, database URL on *.psdb.cloud

# from examples/nextjs-planetscale-preview.plan.yaml
providers:
  planetscale: { organization: acme, database: acme-db }
changes:
  - id: db
    adapter: planetscale
    op: branch
    parent: main
    environments: [preview]

​

Turso

• Ops: recipe turso.database_branch
• Credential: TURSO_API_TOKEN (bearer)
• Token: create it: A platform API token for the organization (turso auth api-tokens mint <name> --org <org>). sponson init --setup checks it with GET /auth/validate.
• Detected by sponson init from: @libsql/client, @tursodatabase/*, TURSO_*, database URL on *.turso.io

# under changes: (no provider block needed)
- id: database_branch
  adapter: http
  op: resource
  recipe: turso.database_branch
  organization: acme
  name: app-${ctx.scope}
  parent: app

​

Xata

• Ops: xata.branch
• Credential: XATA_API_KEY
• Token: create it: An API key limited to the project, with Branch: Read and Write. sponson init --setup checks it with one read-only request.
• Detected by sponson init from: @xata.io/*, .xatarc, XATA_*

# from scenarios/adapters/xata.yaml
providers:
  xata: { organization: acme, project: app }
changes:
  - id: db
    adapter: xata
    op: branch
    name: ${ctx.scope}
    parent_id: br_main
    environments: [preview]

​

MongoDB Atlas

• Ops: recipe mongodb_atlas.database_user
• Credential: MONGODB_ATLAS_PUBLIC_API_KEY / MONGODB_ATLAS_PRIVATE_API_KEY (HTTP Digest)
• Token: create it: A project API key with Project Network Access Manager (access list) or Project Database Access Admin (database users), and an API access list entry. sponson init --setup checks it with GET /groups.
• Detected by sponson init from: MONGODB_ATLAS_*, database URL on *.mongodb.net

# under changes: (no provider block needed)
- id: database_user
  adapter: http
  op: resource
  recipe: mongodb_atlas.database_user
  group_id: 32b6e34b3d91647abb20e7b8
  username: app-${ctx.scope}
  password:
    secret: env://PREVIEW_DB_PASSWORD
  roles:
    - databaseName: app_${ctx.scope}
      roleName: readWrite

​

CockroachDB Cloud

• Ops: recipe cockroachdb.database, recipe cockroachdb.sql_user
• Credential: COCKROACH_API_KEY (bearer)
• Token: create it: A service account (Access Management > Service Accounts) with the Cluster Admin role on the cluster, then Create API Key. sponson init --setup checks it with GET /clusters.
• Detected by sponson init from: COCKROACH_*, database URL on *.cockroachlabs.cloud

# under changes: (no provider block needed)
- id: database
  adapter: http
  op: resource
  recipe: cockroachdb.database
  cluster_id: 9e3f1a52-63d1-4a4c-9b8f-2c8b7a0e5d11
  name: app_${ctx.scope}

​

Prisma Postgres

• Ops: recipe prisma.database, recipe prisma.database_copy
• Credential: PRISMA_SERVICE_TOKEN (bearer)
• Token: create it: A workspace service token (Workspace Settings > Service Tokens); it covers the whole workspace, with no finer scopes. sponson init --setup checks it with GET /projects.
• Detected by sponson init from: @prisma/ppg, database URL on *.prisma.io, database URL on *.prisma-data.net

# under changes: (no provider block needed)
- id: database
  adapter: http
  op: resource
  recipe: prisma.database
  project_id: proj_cm1a2b3c4d5e6f7g8h9
  name: app-${ctx.scope}

​

Auth callback and redirect allow-lists

​

Clerk

• Ops: clerk.redirect_allow
• Credential: CLERK_SECRET_KEY
• Token: create it: The Secret Key of the instance whose redirect URLs the plan manages (sk_test_ for development); Clerk secret keys have no scopes. sponson init --setup checks it with one read-only request.
• Detected by sponson init from: @clerk/*, CLERK_*

# from examples/clerk-preview-callbacks.plan.yaml
changes:
  - id: callback
    adapter: clerk
    op: redirect_allow
    url: { from: env.preview_url }
    environments: [preview]

​

Auth0

• Ops: recipe auth0.callback_url, recipe auth0.logout_url, recipe auth0.web_origin, recipe auth0.allowed_origin
• Credential: AUTH0_CLIENT_ID / AUTH0_CLIENT_SECRET (OAuth2 client credentials)
• Token: create it: A Machine to Machine application authorized for the Auth0 Management API with only the read:clients and update:clients scopes. sponson init --setup checks it with GET /clients.
• Detected by sponson init from: auth0, @auth0/*, AUTH0_*

providers:
  http:
    auth0:
      recipe: auth0
      base_url: https://acme.eu.auth0.com/api/v2
changes:
  - id: callback_url
    adapter: http
    op: list_item
    recipe: auth0.callback_url
    client_id: AbC123dEf456GhI789jKl012MnO345pQ
    url: https://${ctx.scope}.preview.example.app/callback

​

Supabase Auth

• Ops: supabase.auth_redirect
• Credential: SUPABASE_ACCESS_TOKEN
• Token: create it: A personal access token limited to the project, with Development Branches, Auth Config and Project Settings set to Read-write. sponson init --setup checks it with one read-only request.
• Detected by sponson init from: @supabase/*, supabase/config.toml, supabase/.temp/project-ref, SUPABASE_*, database URL on *.supabase.co, database URL on *.supabase.com

# from examples/nextjs-supabase-preview.plan.yaml
providers:
  supabase: { project: acmewebprojectrefxyz }
changes:
  - id: auth_callback
    adapter: supabase
    op: auth_redirect
    project: { from: db.project_ref }
    url: { from: env.preview_url }
    environments: [preview]

​

Firebase Auth

• Ops: recipe firebase.authorized_domain
• Credential: the token gcloud auth print-access-token prints (bearer)
• Token: set up access: Sign in with gcloud auth login as an identity holding Firebase Authentication Admin (roles/firebaseauth.admin) on the project. sponson init --setup shows this; there is no token to store.
• Detected by sponson init from: firebase, firebase-admin, firebase.json, .firebaserc, FIREBASE_*

# under changes: (no provider block needed)
- id: authorized_domain
  adapter: http
  op: list_item
  recipe: firebase.authorized_domain
  project: demo-project
  domain: ${ctx.scope}.preview.example.app

​

WorkOS

• Ops: recipe workos.redirect_uri
• Credential: WORKOS_API_KEY (bearer)
• Token: create it: The secret API key of the environment (staging for previews); WorkOS keys have no finer permissions. sponson init --setup checks it with GET /organizations.
• Detected by sponson init from: @workos-inc/*, WORKOS_*

# under changes: (no provider block needed)
- id: redirect_uri
  adapter: http
  op: resource
  recipe: workos.redirect_uri
  uri: https://${ctx.scope}.preview.example.com/callback

​

Stytch

• Ops: recipe stytch.redirect_url
• Credential: STYTCH_WORKSPACE_KEY_ID / STYTCH_WORKSPACE_KEY_SECRET (basic)
• Token: create it: A Workspace Management API key (Workspace settings > Management API); its key ID and secret, no finer scopes. sponson init --setup checks it with GET /pwa/v3/projects.
• Detected by sponson init from: stytch, @stytch/*, STYTCH_*

# under changes: (no provider block needed)
- id: redirect_url
  adapter: http
  op: resource
  recipe: stytch.redirect_url
  project_slug: my-app
  environment_slug: test
  url: https://${ctx.scope}.preview.example.com/authenticate

​

Okta

• Ops: recipe okta.redirect_uri, recipe okta.post_logout_redirect_uri, recipe okta.trusted_origin
• Credential: OKTA_API_TOKEN (header Authorization, after SSWS)
• Token: create it: An API token (Security > API > Tokens) created by an admin whose role can edit the app (it acts with that admin’s permissions). sponson init --setup checks it with GET /users/me.
• Detected by sponson init from: @okta/*, OKTA_*

providers:
  http:
    okta:
      recipe: okta
      base_url: https://acme.okta.com/api/v1
changes:
  - id: redirect_uri
    adapter: http
    op: list_item
    recipe: okta.redirect_uri
    app_id: 0oa1gjh63g214q0Hq0g4
    url: https://${ctx.scope}.preview.example.app/login/callback

​

Kinde

• Ops: recipe kinde.callback_url, recipe kinde.logout_url
• Credential: KINDE_MANAGEMENT_CLIENT_ID / KINDE_MANAGEMENT_CLIENT_SECRET (OAuth2 client credentials)
• Token: create it: A Machine to Machine application authorized for the Kinde Management API with only the application redirect and logout URI scopes. sponson init --setup cannot check it (no read-only request every such credential may send).
• Detected by sponson init from: @kinde-oss/*, KINDE_*

providers:
  http:
    kinde:
      recipe: kinde
      base_url: https://acme.kinde.com/api/v1
changes:
  - id: callback_url
    adapter: http
    op: list_item
    recipe: kinde.callback_url
    app_id: 3b0b5c6c8fcc464fab397f4969b5f482
    url: https://${ctx.scope}.preview.example.app/api/auth/kinde_callback

​

Google OAuth clients

• Ops: manual.step
• Credential: none (a person does it)
• Detected by sponson init from: not detected (write the line yourself)

# from examples/google-oauth-manual-step.plan.yaml
changes:
  - id: google-redirect
    adapter: manual
    op: step
    title: Allow ${ctx.scope}'s OAuth callback on the Google OAuth client acme-web
    vars:
      url: { from: env.preview_url }
    instructions: |
      Google offers no API for a web client's redirect URIs, so this is done by hand.

      1. Open https://console.cloud.google.com/apis/credentials (project `acme-web`).
      2. Open the OAuth 2.0 client **acme-web**.
      3. Under **Authorized redirect URIs**, add `{url}/api/auth/callback/google`.
      4. Save. Google may take a few minutes to accept the new URI.
    undo: |
      In the same client, remove `{url}/api/auth/callback/google` from **Authorized redirect URIs**, and save.
    environments: [preview]

​

Feature flags and targeting

​

LaunchDarkly

• Ops: launchdarkly.flag_target
• Credential: LAUNCHDARKLY_ACCESS_TOKEN
• Token: create it: An access token whose custom role allows updateTargets on the environment’s flags and viewProject (without custom roles: the Writer role). sponson init --setup checks it with one read-only request.
• Detected by sponson init from: @launchdarkly/*, launchdarkly-node-server-sdk, launchdarkly-js-client-sdk, launchdarkly-react-client-sdk, LAUNCHDARKLY_*

# from examples/launchdarkly-preview-flags.plan.yaml
providers:
  launchdarkly: { project: acme-web, environment: preview }
changes:
  - id: checkout
    adapter: launchdarkly
    op: flag_target
    flag: new-checkout
    context_kind: url
    key: { from: env.preview_url }
    variation: true
    environments: [preview]

​

PostHog

• Ops: recipe posthog.release_condition
• Credential: POSTHOG_PERSONAL_API_KEY (bearer)
• Token: create it: A personal API key with only the feature_flag:read and feature_flag:write scopes, limited to the project (EU: eu.posthog.com). sponson init --setup cannot check it (no read-only request every such credential may send).
• Detected by sponson init from: posthog-js, posthog-node, posthog-react-native, POSTHOG_*

# under changes: (no provider block needed)
- id: release_condition
  adapter: http
  op: list_item
  recipe: posthog.release_condition
  project_id: "12345"
  flag_id: "678"
  property: $host
  value: ${ctx.scope}.preview.example.com

​

Statsig

• Ops: recipe statsig.gate_rule
• Credential: STATSIG_CONSOLE_API_KEY (header STATSIG-API-KEY)
• Token: create it: A Console API key (Project Settings > API Keys) that can edit gates. sponson init --setup checks it with GET /gates.
• Detected by sponson init from: statsig-js, statsig-node, statsig-react, @statsig/*, STATSIG_*

# under changes: (no provider block needed)
- id: gate_rule
  adapter: http
  op: resource
  recipe: statsig.gate_rule
  gate_id: new_checkout
  name: preview ${ctx.scope}
  field: preview
  values:
    - ${ctx.scope}

​

GrowthBook

• Ops: recipe growthbook.force_rule
• Credential: GROWTHBOOK_API_KEY (bearer)
• Token: create it: A Secret API key (Settings > API Keys) with a role that can edit features, limited to the project. sponson init --setup checks it with GET /v1/features.
• Detected by sponson init from: @growthbook/*, GROWTHBOOK_*

# under changes: (no provider block needed)
- id: force_rule
  adapter: http
  op: list_item
  recipe: growthbook.force_rule
  feature_id: new-checkout
  environment: staging
  description: Sponson preview ${ctx.scope}
  condition: '{"preview": "${ctx.scope}"}'
  value: "true"

​

Unleash

• Ops: recipe unleash.flag_strategy
• Credential: UNLEASH_AUTH_TOKEN (header Authorization)
• Token: create it: A personal access token (or an Enterprise service account token) whose role edits flags and strategies in the project; not a client or frontend token. sponson init --setup checks it with GET /api/admin/projects.
• Detected by sponson init from: unleash-client, unleash-proxy-client, @unleash/*, UNLEASH_*

providers:
  http:
    unleash:
      recipe: unleash
      base_url: https://unleash.example.com
changes:
  - id: flag_strategy
    adapter: http
    op: resource
    recipe: unleash.flag_strategy
    feature: new-checkout
    environment: development
    title: preview ${ctx.scope}
    context_name: preview
    values:
      - ${ctx.scope}

​

Flagsmith

• Ops: recipe flagsmith.environment
• Credential: FLAGSMITH_MASTER_API_KEY (header Authorization, after Api-Key)
• Token: create it: An Organisation API key (Organisation Settings > API Keys); with role-based access, give it a role limited to the project. sponson init --setup checks it with GET /organisations/.
• Detected by sponson init from: flagsmith, flagsmith-nodejs, react-native-flagsmith, FLAGSMITH_*

# under changes: (no provider block needed)
- id: environment
  adapter: http
  op: resource
  recipe: flagsmith.environment
  project_id: "1234"
  name: preview-${ctx.scope}

​

ConfigCat

• Ops: recipe configcat.targeting_rule
• Credential: CONFIGCAT_BASIC_AUTH_USERNAME / CONFIGCAT_BASIC_AUTH_PASSWORD (basic)
• Token: create it: Public Management API credentials; they act with your user’s product permissions, so use a member limited to the product. sponson init --setup checks it with GET /v1/me.
• Detected by sponson init from: configcat-js, configcat-js-ssr, configcat-js-full, configcat-node, configcat-react, CONFIGCAT_*

# under changes: (no provider block needed)
- id: targeting_rule
  adapter: http
  op: list_item
  recipe: configcat.targeting_rule
  environment_id: 08d8becf-d4d9-4c66-8b48-6ac74cd95fba
  setting_id: "12345"
  attribute: Preview
  match: ${ctx.scope}

​

Split (Harness FME)

• Ops: recipe split.targeting_rule
• Credential: SPLIT_ADMIN_API_KEY (bearer)
• Token: create it: An Admin API key (Admin settings > API keys), restricted to the environments the lines change. sponson init --setup checks it with GET /workspaces.
• Detected by sponson init from: @splitsoftware/*, SPLIT_*

# under changes: (no provider block needed)
- id: targeting_rule
  adapter: http
  op: list_item
  recipe: split.targeting_rule
  workspace_id: a3b6f5d0-0e8f-11ee-9b0f-0242ac120002
  flag: new_checkout
  environment: Staging
  attribute: preview
  match: ${ctx.scope}
  treatment: on

​

Webhooks registered per environment

​

Stripe

• Ops: recipe stripe.webhook_endpoint
• Credential: STRIPE_SECRET_KEY (bearer)
• Token: create it: A test-mode restricted key (Create restricted key) with Webhook Endpoints set to Write and everything else None. sponson init --setup checks it with GET /webhook_endpoints.
• Detected by sponson init from: stripe, @stripe/*, STRIPE_*

# under changes: (no provider block needed)
- id: webhook_endpoint
  adapter: http
  op: resource
  recipe: stripe.webhook_endpoint
  name: preview-${ctx.scope}
  url: https://pr-42.preview.example.com
  enabled_events:
    - checkout.session.completed
    - customer.subscription.updated
  description: Preview webhook managed by Sponson

​

GitHub

• Ops: recipe github.repo_webhook
• Credential: GITHUB_TOKEN (bearer)
• Token: create it: A fine-grained token for the one repository with the permission the line’s op needs (Webhooks, Administration or Environments: Read and write). sponson init --setup checks it with GET /user.
• Detected by sponson init from: @octokit/webhooks, probot, GITHUB_WEBHOOK_SECRET

# under changes: (no provider block needed)
- id: repo_webhook
  adapter: http
  op: resource
  recipe: github.repo_webhook
  owner: acme
  repo: app
  url: https://${ctx.scope}.preview.example.com/api/github

​

Svix (as a sender)

• Ops: recipe svix.endpoint
• Credential: SVIX_AUTH_TOKEN (bearer)
• Token: create it: The environment’s API key (API Access); keys have no finer scopes. sponson init --setup checks it with GET /api/v1/app.
• Detected by sponson init from: svix, SVIX_*

# under changes: (no provider block needed)
- id: endpoint
  adapter: http
  op: resource
  recipe: svix.endpoint
  app_id: acme-customer
  uid: sponson-${ctx.env}-${ctx.scope}
  url: https://${ctx.scope}.preview.example.com/api/webhooks

​

Clerk webhooks

• Ops: manual.step
• Credential: none (a person does it)
• Detected by sponson init from: not detected (write the line yourself)

# from examples/google-oauth-manual-step.plan.yaml
changes:
  - id: google-redirect
    adapter: manual
    op: step
    title: Allow ${ctx.scope}'s OAuth callback on the Google OAuth client acme-web
    vars:
      url: { from: env.preview_url }
    instructions: |
      Google offers no API for a web client's redirect URIs, so this is done by hand.

      1. Open https://console.cloud.google.com/apis/credentials (project `acme-web`).
      2. Open the OAuth 2.0 client **acme-web**.
      3. Under **Authorized redirect URIs**, add `{url}/api/auth/callback/google`.
      4. Save. Google may take a few minutes to accept the new URI.
    undo: |
      In the same client, remove `{url}/api/auth/callback/google` from **Authorized redirect URIs**, and save.
    environments: [preview]

​

Twilio

• Ops: recipe twilio.twiml_app
• Credential: TWILIO_API_KEY / TWILIO_API_SECRET (basic)
• Token: create it: A Standard API key (Console > Account > API keys & tokens); its SID goes in TWILIO_API_KEY and its secret in TWILIO_API_SECRET. sponson init --setup cannot check it (no read-only request every such credential may send).
• Detected by sponson init from: twilio, TWILIO_*

# under changes: (no provider block needed)
- id: twiml_app
  adapter: http
  op: resource
  recipe: twilio.twiml_app
  account_sid: ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  name: sponson-${ctx.env}-${ctx.scope}
  url: https://pr-42.preview.example.com

​

Ably

• Ops: recipe ably.webhook_rule
• Credential: ABLY_CONTROL_TOKEN (bearer)
• Token: create it: An account access token (Account > My Access Tokens) with the read:rule and write:rule capabilities only. sponson init --setup checks it with GET /me.
• Detected by sponson init from: ably, ABLY_*

# under changes: (no provider block needed)
- id: webhook_rule
  adapter: http
  op: resource
  recipe: ably.webhook_rule
  app_id: 28GY6a
  channel_filter: "^${ctx.scope}:"
  url: https://pr-42.preview.example.com

​

Email: sending domains, webhooks, test inboxes

​

Resend

• Ops: recipe resend.api_key, recipe resend.webhook
• Credential: RESEND_API_KEY (bearer)
• Token: create it: An API key with Full access: Sending access can only send email, not manage webhooks, domains or keys. sponson init --setup checks it with GET /domains.
• Detected by sponson init from: resend, RESEND_*

# under changes: (no provider block needed)
- id: api_key
  adapter: http
  op: resource
  recipe: resend.api_key
  name: sponson-${ctx.env}-${ctx.scope}

​

Postmark

• Ops: recipe postmark.server, recipe postmark_server.webhook
• Credential: POSTMARK_ACCOUNT_TOKEN (header X-Postmark-Account-Token); POSTMARK_SERVER_TOKEN (header X-Postmark-Server-Token)
• Token: create it: The Account API token (Account Owner or Admin only); Postmark tokens have no scopes. sponson init --setup checks it with GET /servers.
• Token: create it: The server’s Server API token (the server’s API Tokens tab); Postmark tokens have no scopes. sponson init --setup checks it with GET /server.
• Detected by sponson init from: postmark, POSTMARK_*

# under changes: (no provider block needed)
- id: server
  adapter: http
  op: resource
  recipe: postmark.server
  name: sponson-${ctx.env}-${ctx.scope}
  inbound_hook_url: https://${ctx.scope}.preview.example.com/api/postmark/inbound

​

SendGrid

• Ops: recipe sendgrid.event_webhook, recipe sendgrid.parse_setting
• Credential: SENDGRID_API_KEY (bearer)
• Token: create it: A Restricted Access key with Mail Settings > Event Notification set to Full Access. sponson init --setup checks it with GET /v3/scopes.
• Detected by sponson init from: @sendgrid/*, SENDGRID_*

# under changes: (no provider block needed)
- id: event_webhook
  adapter: http
  op: resource
  recipe: sendgrid.event_webhook
  url: https://${ctx.scope}.preview.example.com/api/sendgrid/events
  friendly_name: sponson ${ctx.env} ${ctx.scope}

​

Mailgun

• Ops: recipe mailgun.webhook, recipe mailgun.route
• Credential: MAILGUN_API_KEY (basic, user api)
• Token: create it: An account API key (Account Settings > API Keys): Domain Sending Keys ‘only allow sending messages’ and cannot manage webhooks or routes. sponson init --setup checks it with GET /v1/webhooks.
• Detected by sponson init from: mailgun.js, mailgun-js, MAILGUN_*

# under changes: (no provider block needed)
- id: webhook
  adapter: http
  op: resource
  recipe: mailgun.webhook
  name: sponson-${ctx.env}-${ctx.scope}
  url: https://pr-42.preview.example.com

​

Observability per release

​

Sentry

• Ops: recipe sentry.release, recipe sentry.deploy
• Credential: SENTRY_AUTH_TOKEN (bearer)
• Token: create it: An organization auth token (Settings > Auth Tokens), or a personal token with project:releases. sponson init --setup cannot check it (no read-only request every such credential may send).
• Detected by sponson init from: @sentry/*, sentry.client.config.ts, sentry.client.config.js, sentry.server.config.ts, sentry.server.config.js, sentry.properties, .sentryclirc, SENTRY_*

# under changes: (no provider block needed)
- id: release
  adapter: http
  op: resource
  recipe: sentry.release
  organization: acme
  version: app@${ctx.git.sha}
  project: web
  url: https://github.com/acme/app/commit/${ctx.git.sha}

​

Datadog

• Ops: recipe datadog.synthetic_api_test
• Credential: DD_API_KEY (header DD-API-KEY) and DD_APP_KEY (header DD-APPLICATION-KEY)
• Token: create it: An API key, plus an Application key (Organization Settings > Application Keys) limited to the scopes the lines need. sponson init --setup checks it with GET /validate.
• Detected by sponson init from: dd-trace, @datadog/*, DD_*, DATADOG_*

# under changes: (no provider block needed)
- id: synthetic_api_test
  adapter: http
  op: resource
  recipe: datadog.synthetic_api_test
  name: preview ${ctx.scope}
  url: https://${ctx.scope}.preview.example.app/api/health
  locations:
    - aws:us-east-2

​

Honeycomb

• Ops: recipe honeycomb.marker
• Credential: HONEYCOMB_API_KEY (header X-Honeycomb-Team)
• Token: create it: An environment Configuration Key (Manage Environments > API Keys) with only the permission the lines need, such as Manage Markers. sponson init --setup checks it with GET /1/auth.
• Detected by sponson init from: @honeycombio/*, HONEYCOMB_*

# under changes: (no provider block needed)
- id: marker
  adapter: http
  op: resource
  recipe: honeycomb.marker
  dataset: __all__
  message: deploy ${ctx.scope} ${ctx.git.sha}
  url: https://${ctx.scope}.preview.example.com

​

New Relic

• Ops: recipe newrelic.deployment
• Credential: NEW_RELIC_API_KEY (header API-Key)
• Token: create it: A user key (NRAK-…, API keys > Create a key > User) of a user who can create change tracking events for the entity’s account. sponson init --setup cannot check it (no read-only request every such credential may send).
• Detected by sponson init from: newrelic, @newrelic/*, NEW_RELIC_*

# under changes: (no provider block needed)
- id: deployment
  adapter: http
  op: action
  recipe: newrelic.deployment
  entity_guid: MXxBUE18QVBQTElDQVRJT058MTIzNDU2Nzg
  version: ${ctx.git.sha}
  description: ${ctx.env} ${ctx.scope}

​

Rollbar

• Ops: recipe rollbar.deploy
• Credential: ROLLBAR_ACCESS_TOKEN (header X-Rollbar-Access-Token)
• Token: create it: A project access token with the post_server_item scope (‘Can perform all POST requests to /deploy/ and /item/’). sponson init --setup cannot check it (no read-only request every such credential may send).
• Detected by sponson init from: rollbar, @rollbar/*, ROLLBAR_*

# under changes: (no provider block needed)
- id: deploy
  adapter: http
  op: action
  recipe: rollbar.deploy
  environment: ${ctx.env}
  revision: ${ctx.git.sha}
  comment: ${ctx.scope}

​

BugSnag

• Ops: recipe bugsnag.build
• Credential: none of Sponson’s (calls a URL the line gives; a key it needs is a { secret } param)
• Detected by sponson init from: @bugsnag/*, BUGSNAG_*

# under changes: (no provider block needed)
- id: build
  adapter: http
  op: action
  recipe: bugsnag.build
  api_key:
    secret: env://BUGSNAG_API_KEY
  app_version: ${ctx.git.sha}
  release_stage: ${ctx.env}

​

DNS and preview domains

​

Cloudflare DNS

• Ops: recipe cloudflare.dns_cname
• Credential: CLOUDFLARE_API_TOKEN (bearer)
• Token: create it: A custom token (or the Edit zone DNS template) with Zone > DNS > Edit, its Zone Resources limited to the zone. sponson init --setup checks it with GET /user/tokens/verify.
• Detected by sponson init from: wrangler, @cloudflare/next-on-pages, wrangler.json, wrangler.jsonc, wrangler.toml, CLOUDFLARE_*

# under changes: (no provider block needed)
- id: dns_cname
  adapter: http
  op: resource
  recipe: cloudflare.dns_cname
  zone_id: 023e105f4ecef8ad9ca31a8372d0c353
  name: ${ctx.scope}.preview.example.com
  target: preview-host.example.net
  comment: Managed by Sponson

​

Vercel domains

• Ops: recipe vercel.project_domain
• Credential: VERCEL_TOKEN (bearer)
• Token: create it: A token scoped to the team that owns the project, with an expiration. sponson init --setup checks it with GET /v2/user.
• Detected by sponson init from: vercel, @vercel/*, vercel.json, .vercel/project.json, VERCEL_*

# under changes: (no provider block needed)
- id: project_domain
  adapter: http
  op: resource
  recipe: vercel.project_domain
  project: prj_12HKQaOmR5t5Uy6vdcQsNIiZgHGB
  team_id: team_1a2b3c4d5e6f7g8h9i0j1k2l
  name: ${ctx.scope}.preview.example.com
  git_branch: ${ctx.git.branch}

​

CORS and allowed origins

​

Firebase Storage (GCS bucket)

• Ops: recipe gcs.bucket_cors
• Credential: the token gcloud auth print-access-token prints (bearer)
• Token: set up access: Sign in with gcloud auth login as an identity holding Storage Admin (roles/storage.admin) on the bucket: storage.buckets.get and storage.buckets.update. sponson init --setup shows this; there is no token to store.
• Detected by sponson init from: @google-cloud/storage

# under changes: (no provider block needed)
- id: bucket_cors
  adapter: http
  op: list_item
  recipe: gcs.bucket_cors
  bucket: my-app.appspot.com
  origin: https://${ctx.scope}.preview.example.app

​

S3 / R2

• Ops: recipe s3.bucket_cors
• Credential: AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (AWS SigV4, s3 in us-east-1)
• Token: create it: AWS: an access key whose policy allows s3:GetBucketCORS and s3:PutBucketCORS on the bucket. R2: an API token with Admin Read & Write. sponson init --setup cannot check it (no read-only request every such credential may send).
• Detected by sponson init from: @aws-sdk/client-s3

providers:
  http:
    s3:
      recipe: s3
      base_url: https://assets.s3.us-east-1.amazonaws.com
changes:
  - id: bucket_cors
    adapter: http
    op: list_item
    recipe: s3.bucket_cors
    rule_id: sponson-${ctx.scope}
    origin: https://${ctx.scope}.preview.example.app

​

Sanity CORS

• Ops: recipe sanity.cors_origin
• Credential: SANITY_AUTH_TOKEN (bearer)
• Token: create it: A robot token of the project (API → Tokens) with the Administrator role, or Developer on Growth and Enterprise: editors cannot create datasets, and CORS origins are project settings. sponson init --setup cannot check it (no read-only request every such credential may send).
• Detected by sponson init from: sanity, @sanity/client, next-sanity, sanity.config.ts, sanity.config.js, sanity.cli.ts, sanity.cli.js, SANITY_*

# under changes: (no provider block needed)
- id: cors_origin
  adapter: http
  op: resource
  recipe: sanity.cors_origin
  project_id: abc123de
  origin: https://${ctx.scope}.preview.example.app

​

Queues, caches, background jobs

​

Upstash Redis

• Ops: recipe upstash.redis_database
• Credential: UPSTASH_EMAIL / UPSTASH_API_KEY (basic)
• Token: create it: A Developer API key (Account > Developer API) with Read/Write; the account’s email is its user name. sponson init --setup checks it with GET /redis/databases.
• Detected by sponson init from: @upstash/redis, UPSTASH_REDIS_*

# under changes: (no provider block needed)
- id: redis_database
  adapter: http
  op: resource
  recipe: upstash.redis_database
  name: app-${ctx.scope}
  primary_region: us-east-1

​

Upstash QStash

• Ops: recipe qstash.schedule
• Credential: QSTASH_TOKEN (bearer)
• Token: create it: The QStash token of the region (QStash tab); it has no scopes. sponson init --setup checks it with GET /v2/schedules.
• Detected by sponson init from: @upstash/qstash, QSTASH_*

# under changes: (no provider block needed)
- id: schedule
  adapter: http
  op: resource
  recipe: qstash.schedule
  schedule_id: cron-${ctx.scope}
  destination: https://${ctx.scope}.preview.example.com/api/cron
  cron: "*/15 * * * *"

​

Inngest

• Ops: recipe inngest.sync
• Credential: none of Sponson’s (calls a URL the line gives; a key it needs is a { secret } param)
• Detected by sponson init from: inngest, INNGEST_*

# under changes: (no provider block needed)
- id: sync
  adapter: http
  op: action
  recipe: inngest.sync
  url: https://acme-git-feat-x-acme.vercel.app
  revision: ${ctx.git.sha}

​

Search, payments test mode

​

Algolia

• Ops: algolia.index
• Credential: ALGOLIA_API_KEY
• Token: create it: A restricted API key (not the Admin key) with the addObject, deleteIndex, editSettings, settings and listIndexes ACLs. sponson init --setup checks it with one read-only request.
• Detected by sponson init from: algoliasearch, @algolia/*, instantsearch.js, react-instantsearch, ALGOLIA_*

# from scenarios/adapters/algolia.yaml
providers:
  algolia: { application_id: APP123 }
changes:
  - id: search
    adapter: algolia
    op: index
    name: products_${ctx.scope}
    copy_from: products
    environments: [preview]

​

Stripe test-mode objects

• Ops: recipe stripe.product, recipe stripe.price, recipe stripe.coupon
• Credential: STRIPE_SECRET_KEY (bearer)
• Token: create it: A test-mode restricted key (Create restricted key) with Webhook Endpoints set to Write and everything else None. sponson init --setup checks it with GET /webhook_endpoints.
• Detected by sponson init from: stripe, @stripe/*, STRIPE_*

# under changes: (no provider block needed)
- id: product
  adapter: http
  op: resource
  recipe: stripe.product
  product_id: pro-${ctx.scope}
  name: Pro (preview)

​

Stripe sandboxes

• Ops: manual.step
• Credential: none (a person does it)
• Detected by sponson init from: not detected (write the line yourself)

# from examples/google-oauth-manual-step.plan.yaml
changes:
  - id: google-redirect
    adapter: manual
    op: step
    title: Allow ${ctx.scope}'s OAuth callback on the Google OAuth client acme-web
    vars:
      url: { from: env.preview_url }
    instructions: |
      Google offers no API for a web client's redirect URIs, so this is done by hand.

      1. Open https://console.cloud.google.com/apis/credentials (project `acme-web`).
      2. Open the OAuth 2.0 client **acme-web**.
      3. Under **Authorized redirect URIs**, add `{url}/api/auth/callback/google`.
      4. Save. Google may take a few minutes to accept the new URI.
    undo: |
      In the same client, remove `{url}/api/auth/callback/google` from **Authorized redirect URIs**, and save.
    environments: [preview]

​

Headless CMS content per preview

​

Contentful

• Ops: contentful.environment, contentful.api_key_access
• Credential: CONTENTFUL_MANAGEMENT_TOKEN
• Token: create it: A personal access token (or an OAuth token) with the content_management_manage scope, of a user whose role may create and delete sandbox environments and edit API keys in the space. sponson init --setup checks it with one read-only request.
• Detected by sponson init from: contentful, contentful-management, @contentful/*, CONTENTFUL_*

# from scenarios/adapters/contentful.yaml
providers:
  contentful: { space: space1 }
changes:
  - id: content
    adapter: contentful
    op: environment
    name: ${ctx.scope}
    environments: [preview]

​

Sanity

• Ops: recipe sanity.dataset
• Credential: SANITY_AUTH_TOKEN (bearer)
• Token: create it: A robot token of the project (API → Tokens) with the Administrator role, or Developer on Growth and Enterprise: editors cannot create datasets, and CORS origins are project settings. sponson init --setup cannot check it (no read-only request every such credential may send).
• Detected by sponson init from: sanity, @sanity/client, next-sanity, sanity.config.ts, sanity.config.js, sanity.cli.ts, sanity.cli.js, SANITY_*

# under changes: (no provider block needed)
- id: dataset
  adapter: http
  op: resource
  recipe: sanity.dataset
  project_id: abc123de
  name: preview-${ctx.scope}

​

Backend platforms with preview deployments

​

Convex

• Ops: recipe convex.preview_deployment, recipe convex.deploy_key
• Credential: CONVEX_TEAM_ACCESS_TOKEN (bearer)
• Token: create it: A team access token (Team Settings → Access Tokens), preferably of a service-account member: it can do what that member’s role allows on the team. sponson init --setup cannot check it (no read-only request every such credential may send).
• Detected by sponson init from: convex, convex.json, CONVEX_*

# under changes: (no provider block needed)
- id: preview_deployment
  adapter: http
  op: resource
  recipe: convex.preview_deployment
  project_id: "12345"
  reference: ${ctx.scope}