@sponson/adapters 0.4.0 → 0.6.0

package/recipes/fly.yaml

@@ -0,0 +1,97 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Fly.io GraphQL API recipes (app secrets). Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+# The per-PR app itself is in fly_machines.yaml (the Machines API has another base URL).
+provider: fly
+title: Fly.io
+category: deploy
+verified_on: "2026-10-11"
+docs:
+  - title: Secrets and Fly Apps
+    url: https://docs.fly.io/apps/secrets
+  - title: superfly/fly-go resource_secrets.go (the GraphQL operations flyctl sends)
+    url: https://github.com/superfly/fly-go/blob/main/resource_secrets.go
+  - title: superfly/fly-go schema.graphql
+    url: https://github.com/superfly/fly-go/blob/main/schema.graphql
+  - title: Working with the Machines API (tokens)
+    url: https://docs.fly.io/machines/api/working-with-machines-api/
+api:
+  base_url: https://api.fly.io/graphql
+  base_url_env: FLY_API_URL
+  auth: { bearer_env: FLY_API_TOKEN }
+detect:
+  env: ["FLY_*"]
+  files: [fly.toml]
+  starter:
+    - op: secret
+  where:
+    app: "the preview's Fly app: `app` in fly.toml, or the app per pull request a `fly_machines.app` line creates"
+assumptions:
+  - id: FS1
+    verified: true
+    text: "`query ($appName: String!) { app(name: $appName) { secrets { name digest createdAt } } }` lists an app's secrets; values are never returned (Fly does not allow reading plain-text secret values), so the recipe locates a secret by name and compares nothing else."
+    source: https://github.com/superfly/fly-go/blob/main/resource_secrets.go
+  - id: FS2
+    verified: true
+    text: "`mutation($input: SetSecretsInput!) { setSecrets(input: $input) { release { id version } } }` with `{ appId, secrets: [{ key, value }] }` sets secrets; `unsetSecrets(input: { appId, keys })` removes them."
+    source: https://github.com/superfly/fly-go/blob/main/resource_secrets.go
+  - id: FS3
+    verified: true
+    text: "Plain-text values cannot be read back (`fly secrets list` shows a name, a digest and a date), so a value changed in the console, or in the plan, is not detected: drift is the secret's presence only. To change a value, run `sponson apply --destroy` for the scope (or remove the line, apply, and add it back)."
+    source: https://docs.fly.io/apps/secrets
+  - id: FS4
+    verified: true
+    text: "Machines read secrets as environment variables at boot: a secret set without updating the Machines (as `fly secrets set --stage` does) reaches only Machines started or updated afterwards. Order the line before the PR's `fly deploy`; after a later change run `fly secrets deploy`."
+    source: https://docs.fly.io/apps/secrets
+  - id: FS5
+    verified: false
+    text: "A token from `fly tokens create` (`FlyV1 fm2_…`) or `fly auth token` is accepted as `Authorization: Bearer <token>` by the GraphQL API, as the Machines API documents for the same `FLY_API_TOKEN`. (fly-go itself sends a macaroon as `FlyV1 <token>`; a block that needs that sends it with `auth: { header: Authorization, value_env: FLY_API_TOKEN }`.)"
+  - id: FS6
+    verified: false
+    text: "Unsetting a secret of an app that no longer exists answers an error saying the app could not be found, which the adapter reads as already gone; unsetting an absent key of an existing app is not an error. setSecrets through GraphQL updates no Machines (FS4). Current flyctl sets secrets through the Machines API instead; the GraphQL mutations are not marked deprecated."
+ops:
+  secret:
+    kind: resource
+    title: App secret
+    summary: "One secret of a Fly app (typically the app made for the pull request, `fly_machines.app`), set with `setSecrets` and removed with `unsetSecrets`. Fly never returns secret values, so only its presence is compared: a secret unset in the console is recreated, a changed value is not noticed (FS3). Machines see it once started or updated after the write: order it before the PR's deploy (FS4)."
+    covers: [fly-secrets]
+    params:
+      app:
+        type: string
+        required: true
+        description: The app's name.
+        example: "demo-${ctx.scope}"
+      name:
+        type: string
+        required: true
+        pattern: "^[A-Za-z_][A-Za-z0-9_]*$"
+        description: The secret's name (the environment variable the Machines see).
+        example: DATABASE_URL
+      value:
+        type: string
+        required: true
+        description: The secret's value, normally a `{ secret }` reference. It is sent, never stored or compared.
+        example: "postgres://app@db.internal:5432/${ctx.scope}"
+    http:
+      find:
+        graphql:
+          query: "query ($appName: String!) { app(name: $appName) { secrets { name digest createdAt } } }"
+          variables: { appName: { param: app } }
+          data_path: /app/secrets
+        match: { name: { param: name } }
+      create:
+        graphql:
+          query: "mutation($input: SetSecretsInput!) { setSecrets(input: $input) { release { id version } } }"
+          variables: { input: { appId: { param: app }, secrets: [{ key: { param: name }, value: { param: value } }] } }
+          idempotent: true
+      delete:
+        graphql:
+          query: "mutation($input: UnsetSecretsInput!) { unsetSecrets(input: $input) { release { id version } } }"
+          variables: { input: { appId: { param: app }, keys: [{ param: name }] } }
+    sim:
+      provider: fly
+      seed: { apps: { demo-pr-42: {} } }
+      present: /apps/demo-pr-42/secrets/DATABASE_URL
+      drift:
+        missing: { secrets.demo-pr-42.DATABASE_URL: delete }
+    live:
+      params: { app: SPONSON_LIVE_FLY_APP }

package/recipes/fly_machines.yaml

@@ -0,0 +1,67 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Fly.io Machines API recipes (the per-PR app). Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+# The app's secrets are in fly.yaml (the GraphQL API has another base URL).
+provider: fly_machines
+title: Fly.io Machines API
+category: deploy
+verified_on: "2026-10-11"
+docs:
+  - title: Working with the Machines API
+    url: https://docs.fly.io/machines/api/working-with-machines-api/
+  - title: Apps resource
+    url: https://docs.fly.io/machines/api/apps-resource/
+api:
+  base_url: https://api.machines.dev/v1
+  base_url_env: FLY_MACHINES_API_URL
+  auth: { bearer_env: FLY_API_TOKEN }
+assumptions:
+  - id: FM1
+    verified: true
+    text: "The Machines API's public base URL is `https://api.machines.dev`, its paths start with `/v1`, and requests carry `Authorization: Bearer <fly_api_token>`."
+    source: https://docs.fly.io/machines/api/working-with-machines-api/
+  - id: FM2
+    verified: true
+    text: "`POST /v1/apps` with `app_name` (unique) and `org_slug` (both required) and optional `network` creates an app and answers 201 with `id` and `created_at`."
+    source: https://docs.fly.io/machines/api/apps-resource/
+  - id: FM3
+    verified: true
+    text: "`GET /v1/apps/{app_name}` answers the app (`id`, `name`, `status`, `organization { name, slug }`), so the name the plan chooses locates it."
+    source: https://docs.fly.io/machines/api/apps-resource/
+  - id: FM4
+    verified: true
+    text: "`DELETE /v1/apps/{app_name}` answers 202; Machines should be stopped first, and `?force=true` stops them and deletes the app at once, which is what the recipe's destroy sends (a PR app has the PR's Machines running)."
+    source: https://docs.fly.io/machines/api/apps-resource/
+  - id: FM5
+    verified: false
+    text: "Deleting the app deletes its secrets and its Machines with it; an app name another organization holds is refused with a conflict, which the adapter then fails to read (403/404) and reports."
+ops:
+  app:
+    kind: resource
+    title: App
+    summary: "A Fly app per pull request, such as `demo-${ctx.scope}`, in an organization: created with `POST /v1/apps`, located by its name, deleted with its Machines on destroy (`?force=true`). Its secrets are `fly.secret` lines; the Machines are what the PR's `fly deploy` creates. Nothing about the app is compared besides its existence."
+    covers: [fly-secrets]
+    params:
+      app_name:
+        type: string
+        required: true
+        pattern: "^[a-z0-9][a-z0-9-]*$"
+        description: The app's name, unique across Fly.io.
+        example: "demo-${ctx.scope}"
+      org_slug:
+        type: string
+        required: true
+        description: The organization the app is created in.
+        example: acme
+      network:
+        type: string
+        description: A private network (6PN) to put the app on.
+    http:
+      read: { path: "/apps/{app_name}" }
+      create:
+        path: /apps
+        body: { app_name: { param: app_name }, org_slug: { param: org_slug }, network: { param: network } }
+      delete: { path: "/apps/{app_name}?force=true" }
+    sim:
+      id_from: app_name
+    live:
+      params: { org_slug: SPONSON_LIVE_FLY_ORG }

package/recipes/gcs.yaml

@@ -0,0 +1,102 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Google Cloud Storage JSON API recipes (Firebase Storage buckets too), authenticated by the token gcloud prints.
+# Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: gcs
+title: Google Cloud Storage (Firebase Storage)
+category: cors
+verified_on: "2026-10-11"
+docs:
+  - title: "Buckets: patch"
+    url: https://docs.cloud.google.com/storage/docs/json_api/v1/buckets/patch
+  - title: Buckets resource (cors)
+    url: https://docs.cloud.google.com/storage/docs/json_api/v1/buckets
+  - title: Set up and view CORS configurations
+    url: https://docs.cloud.google.com/storage/docs/using-cors
+  - title: Performance tips (patch semantics)
+    url: https://docs.cloud.google.com/storage/docs/json_api/v1/how-tos/performance
+api:
+  base_url: https://storage.googleapis.com/storage/v1
+  base_url_env: GCS_API_URL
+  auth: { command: [gcloud, auth, print-access-token] }
+detect:
+  deps: ["@google-cloud/storage"]
+  starter:
+    - op: bucket_cors
+      preview_url: origin
+  where:
+    bucket: "`gcloud storage buckets list`, or Firebase console → Storage (the bucket's name)"
+assumptions:
+  - id: GC1
+    verified: true
+    text: "The JSON API takes an OAuth access token as `Authorization: Bearer`; Google's own example gets it from `gcloud auth print-access-token`."
+    source: https://docs.cloud.google.com/storage/docs/using-cors
+  - id: GC2
+    verified: true
+    text: "`GET /b/{bucket}?fields=cors` answers the bucket's CORS configuration; `PATCH /b/{bucket}?fields=cors` with `{ cors: [...] }` sets it, and `{ cors: [] }` removes it."
+    source: https://docs.cloud.google.com/storage/docs/using-cors
+  - id: GC3
+    verified: true
+    text: "A patch that contains a list replaces the whole list: individual entries cannot be added or removed, so the whole `cors` list is written back."
+    source: https://docs.cloud.google.com/storage/docs/json_api/v1/how-tos/performance
+  - id: GC4
+    verified: true
+    text: "Each `cors` entry has `origin` (list), `method` (list), `responseHeader` (list) and `maxAgeSeconds` (integer)."
+    source: https://docs.cloud.google.com/storage/docs/json_api/v1/buckets
+  - id: GC5
+    verified: true
+    text: "`PATCH` takes `ifMetagenerationMatch`, a precondition on the bucket's metageneration. The recipe does not send it (the http adapter has no preconditions); Sponson's own writers are serialised by the parent lock, a writer outside Sponson can still race."
+    source: https://docs.cloud.google.com/storage/docs/json_api/v1/buckets/patch
+  - id: GC6
+    verified: true
+    text: "Changing a bucket's CORS needs the `storage.buckets.update` permission."
+    source: https://docs.cloud.google.com/storage/docs/json_api/v1/buckets/patch
+  - id: GC7
+    verified: false
+    text: "A bucket without a CORS configuration answers `{}` (no `cors` field), read as an empty list, and entries are answered as written, in order."
+  - id: GC8
+    verified: false
+    text: "An entry is identified by its first origin: the recipe writes one origin per entry, and no other entry of the bucket starts with the same origin."
+ops:
+  bucket_cors:
+    kind: list_item
+    title: CORS entry of a bucket
+    summary: "An entry of a bucket's `cors` list allowing one origin, such as the preview's URL on the Firebase Storage bucket `my-app.appspot.com`, with its methods, response headers and max age. The rest of the list is left as it is; a console edit of the entry is drift, and destroy removes only this entry."
+    covers: [gcs-cors]
+    params:
+      bucket:
+        type: string
+        required: true
+        description: The bucket's name (Firebase Storage's default bucket is `<project>.appspot.com` or `<project>.firebasestorage.app`).
+        example: my-app.appspot.com
+      origin:
+        type: string
+        required: true
+        pattern: "^(https?://\\S+|\\*)$"
+        description: The origin allowed, without a path (the preview's URL); the entry's identity (GC8).
+        example: "https://${ctx.scope}.preview.example.app"
+      methods:
+        type: list
+        default: [GET, HEAD]
+        description: The methods allowed.
+      response_headers:
+        type: list
+        default: [Content-Type]
+        description: The response headers the browser may read.
+      max_age_seconds:
+        type: integer
+        default: 3600
+        description: How long a preflight answer may be cached.
+    http:
+      parent: { path: "/b/{bucket}?fields=cors", method: PATCH }
+      list_path: /cors
+      key_field: /origin/0
+      item:
+        origin: [{ param: origin }]
+        method: { param: methods }
+        responseHeader: { param: response_headers }
+        maxAgeSeconds: { param: max_age_seconds }
+    sim:
+      objects:
+        "/b/{bucket}": { cors: [{ origin: [https://app.example.com], method: [GET], responseHeader: [Content-Type], maxAgeSeconds: 3600 }] }
+    live:
+      params: { bucket: SPONSON_LIVE_GCS_BUCKET }

package/recipes/github.yaml

@@ -0,0 +1,124 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# GitHub REST API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: github
+title: GitHub
+category: webhooks
+verified_on: "2026-10-11"
+docs:
+  - title: REST API endpoints for repository webhooks
+    url: https://docs.github.com/en/rest/repos/webhooks
+  - title: Authenticating to the REST API
+    url: https://docs.github.com/en/rest/authentication/authenticating-to-the-rest-api
+  - title: Getting started with the REST API (headers, API versions)
+    url: https://docs.github.com/en/rest/using-the-rest-api/getting-started-with-the-rest-api
+api:
+  base_url: https://api.github.com
+  base_url_env: GITHUB_API_URL
+  auth: { bearer_env: GITHUB_TOKEN }
+  headers: { X-GitHub-Api-Version: "2022-11-28", User-Agent: sponson }
+detect:
+  deps: ["@octokit/webhooks", probot]
+  env: [GITHUB_WEBHOOK_SECRET]
+  starter:
+    - op: repo_webhook
+  where:
+    url: "the preview's webhook handler: its URL plus the handler's path (a `{ from }` reference cannot carry a path)"
+assumptions:
+  - id: GH1
+    verified: true
+    text: "`POST /repos/{owner}/{repo}/hooks` creates a repository webhook from `name: web`, `config` (`url`, `content_type`, `secret`, `insecure_ssl`), `events` and `active`, answering 201 with the hook (its integer `id` and `config`), authenticated with `Authorization: Bearer <token>`."
+    source: https://docs.github.com/en/rest/repos/webhooks
+  - id: GH2
+    verified: true
+    text: "`GET /repos/{owner}/{repo}/hooks` answers a bare array of hooks, each with `config.url`; it pages with `per_page` (at most 100) and `page`."
+    source: https://docs.github.com/en/rest/repos/webhooks
+  - id: GH3
+    verified: true
+    text: "`PATCH /repos/{owner}/{repo}/hooks/{hook_id}` updates `config`, `events` (replacing the list) and `active`; a secret set before is removed unless the same or a new one is sent, so every update sends the config's `url` and `secret` again."
+    source: https://docs.github.com/en/rest/repos/webhooks
+  - id: GH4
+    verified: true
+    text: "`DELETE /repos/{owner}/{repo}/hooks/{hook_id}` answers 204, and 404 when the hook is gone."
+    source: https://docs.github.com/en/rest/repos/webhooks
+  - id: GH5
+    verified: true
+    text: "Each hook should have a unique config, and hooks may share one only when their events do not overlap. The recipe takes the URL as the hook's identity; two hooks with the same URL make `find` refuse (PARAM_INVALID) instead of guessing."
+    source: https://docs.github.com/en/rest/repos/webhooks
+  - id: GH6
+    verified: false
+    text: "The secret is write-only: answers carry it masked or not at all, so it is sent on create and update but never compared, and a secret changed in the plan reaches GitHub only with the next change of a compared field. Keep it in a secret manager and reference it with `{ secret: … }`."
+  - id: GH7
+    verified: false
+    text: "A repository has at most 100 hooks for this purpose (GitHub limits hooks per event), so the first page of `?per_page=100` holds the one `find` looks for."
+  - id: GH8
+    verified: true
+    text: "`config.content_type` and `config.insecure_ssl` are answered as sent (`json`/`form`, the strings `\"0\"`/`\"1\"`), and `Accept: application/json` is served like `application/vnd.github+json`. Verified live 2026-10-11: create, then a re-apply that wrote nothing, then destroy, against api.github.com."
+    source: https://docs.github.com/en/rest/repos/webhooks
+  - id: GH9
+    verified: false
+    text: "The token needs the repository permission Webhooks (write) or the classic `admin:repo_hook` scope; the `GITHUB_TOKEN` of GitHub Actions does not have it, so use a GitHub App token or a fine-grained token. `GITHUB_API_URL` (set by Actions) points at GitHub Enterprise Server where that is the host."
+ops:
+  repo_webhook:
+    kind: resource
+    title: Repository webhook
+    summary: A repository webhook delivering to an environment's URL, such as the preview deployment's `/api/github` handler. Located by its URL; a console edit of its events, its active flag, its content type or its TLS check is drift. The secret is sent but not compared (GH6).
+    covers: [github-webhook]
+    params:
+      owner:
+        type: string
+        required: true
+        description: The repository's owner (user or organization).
+        example: acme
+      repo:
+        type: string
+        required: true
+        description: The repository's name.
+        example: app
+      url:
+        type: string
+        required: true
+        pattern: "^https?://\\S+$"
+        description: The URL GitHub delivers to; it identifies the hook in the repository.
+        example: "https://${ctx.scope}.preview.example.com/api/github"
+      events:
+        type: list
+        default: [push]
+        description: The events that trigger a delivery (`["*"]` for all).
+      active:
+        type: boolean
+        default: true
+        description: Whether deliveries are sent.
+      content_type:
+        type: string
+        default: json
+        enum: [json, form]
+        description: The payload's media type.
+      insecure_ssl:
+        type: string
+        default: "0"
+        enum: ["0", "1"]
+        description: '"1" skips verifying the TLS certificate of the URL.'
+      secret:
+        type: string
+        description: "The secret deliveries are signed with (write-only; GH6). Use `{ secret: … }`."
+    http:
+      find:
+        path: "/repos/{owner}/{repo}/hooks?per_page=100"
+        match: { /config/url: { param: url } }
+      create:
+        path: "/repos/{owner}/{repo}/hooks"
+        body: { name: web, config: { secret: { param: secret } } }
+      update:
+        method: PATCH
+        path: "/repos/{owner}/{repo}/hooks/{id}"
+        body: { config: { url: { param: url }, secret: { param: secret } } }
+      delete: { path: "/repos/{owner}/{repo}/hooks/{id}" }
+      fields:
+        active: { param: active }
+        events: { param: events }
+        /config/content_type: { param: content_type }
+        /config/insecure_ssl: { param: insecure_ssl }
+    sim:
+      numeric_ids: true
+    live:
+      params: { owner: SPONSON_LIVE_GITHUB_OWNER, repo: SPONSON_LIVE_GITHUB_REPO }

package/recipes/growthbook.yaml

@@ -0,0 +1,124 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# GrowthBook REST API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: growthbook
+title: GrowthBook
+category: flags
+verified_on: "2026-10-11"
+docs:
+  - title: REST API reference (authentication, versioning)
+    url: https://docs.growthbook.io/api
+  - title: Get a feature (v2)
+    url: https://docs.growthbook.io/api#operation/getFeatureV2
+  - title: Update a feature (v2)
+    url: https://docs.growthbook.io/api#operation/updateFeatureV2
+  - title: OpenAPI spec
+    url: https://api.growthbook.io/api/v1/openapi.yaml
+api:
+  base_url: https://api.growthbook.io/api
+  base_url_env: GROWTHBOOK_API_URL
+  auth: { bearer_env: GROWTHBOOK_API_KEY }
+detect:
+  deps: ["@growthbook/"]
+  env: ["GROWTHBOOK_*"]
+  starter:
+    - op: force_rule
+      values: { description: "Sponson preview ${ctx.scope}", condition: "{\"preview\": \"${ctx.scope}\"}" }
+  where:
+    feature_id: "GrowthBook → Features: the feature's key"
+    environment: "GrowthBook → Settings → Environments: the one previews evaluate in"
+assumptions:
+  - id: GB1
+    verified: true
+    text: "GrowthBook Cloud's API is at `https://api.growthbook.io/api` (self-hosted: its API host plus `/api`), authenticated with a secret key or personal access token as `Authorization: Bearer`."
+    source: https://docs.growthbook.io/api
+  - id: GB2
+    verified: true
+    text: "The v1 feature endpoints (rules per environment) are deprecated; in v2 a feature's rules are one top-level `rules` array, each rule naming its `environments` (or `allEnvironments`)."
+    source: https://docs.growthbook.io/api#operation/getFeatureV2
+  - id: GB3
+    verified: true
+    text: "`GET /v2/features/{id}` answers `{ feature: { …, rules: [...] } }`."
+    source: https://docs.growthbook.io/api#operation/getFeatureV2
+  - id: GB4
+    verified: true
+    text: "`POST /v2/features/{id}` patch-merges the top-level fields it is sent, and `rules`, when sent, replaces the whole array: so the array is read, the rule added or changed, and the whole array sent back. Rules read with GET may be posted back unchanged. The update publishes a new revision at once."
+    source: https://docs.growthbook.io/api#operation/updateFeatureV2
+  - id: GB5
+    verified: true
+    text: "A force rule is `{ type: force, description, condition, value, enabled, allEnvironments, environments }`; `condition` is a JSON query serialised as a string and `value` is a string (`\"true\"` for a boolean feature)."
+    source: https://api.growthbook.io/api/v1/openapi.yaml
+  - id: GB6
+    verified: false
+    text: "Rule ids may be chosen by the client but what the server does with them is not documented, so the rule is identified by its `description`, which it stores as written; two rules with that description are one rule to Sponson."
+  - id: GB7
+    verified: false
+    text: "A rule is read back with `condition` exactly as sent (not reformatted), so the compared fields do not show as changed on every plan."
+  - id: GB8
+    verified: true
+    text: "When the feature requires approval, the update answers 422 with the gates that blocked it, unless the organisation lets the REST API bypass approvals; the apply then fails."
+    source: https://docs.growthbook.io/api#operation/updateFeatureV2
+ops:
+  force_rule:
+    kind: list_item
+    title: Feature force rule
+    summary: "A force rule on an existing feature that serves a value to the preview in one environment, such as `value \"true\"` when `{\"preview\": \"pr-42\"}`. Added after the feature's other rules (rules are evaluated in order: an earlier rule that matches the preview wins). A console edit of its condition, value, environments or enabled state is drift. Destroy removes the rule."
+    covers: [growthbook-force-rule]
+    params:
+      feature_id:
+        type: string
+        required: true
+        description: The feature's key.
+        example: new-checkout
+      environment:
+        type: string
+        required: true
+        description: The environment the rule applies in.
+        example: staging
+      description:
+        type: string
+        required: true
+        description: The rule's description, unique among the feature's rules; it identifies the rule.
+        example: "Sponson preview ${ctx.scope}"
+      condition:
+        type: string
+        required: true
+        description: The targeting condition, a JSON query as a string.
+        example: "{\"preview\": \"${ctx.scope}\"}"
+      value:
+        type: string
+        required: true
+        description: The value served, as a string (`"true"` for a boolean feature, JSON for a JSON feature).
+        example: "true"
+      enabled:
+        type: boolean
+        default: true
+        description: Whether the rule is on.
+    http:
+      parent: { path: "/v2/features/{feature_id}", method: POST, item_path: /feature }
+      list_path: /rules
+      key_field: description
+      item:
+        description: { param: description }
+        type: force
+        condition: { param: condition }
+        value: { param: value }
+        enabled: { param: enabled }
+        allEnvironments: false
+        environments: [{ param: environment }]
+    sim:
+      objects:
+        "/v2/features/{feature_id}":
+          id: new-checkout
+          valueType: boolean
+          defaultValue: "false"
+          rules:
+            - id: fr_internal
+              type: force
+              description: Internal users
+              condition: "{\"internal\": true}"
+              value: "true"
+              enabled: true
+              allEnvironments: true
+              environments: []
+    live:
+      params: { feature_id: SPONSON_LIVE_GROWTHBOOK_FEATURE_ID, environment: SPONSON_LIVE_GROWTHBOOK_ENVIRONMENT }

package/recipes/heroku.yaml

@@ -0,0 +1,98 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Heroku Platform API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: heroku
+title: Heroku
+category: deploy
+verified_on: "2026-10-11"
+docs:
+  - title: Platform API reference (clients, Config Vars, Review App)
+    url: https://devcenter.heroku.com/articles/platform-api-reference
+  - title: Platform API JSON schema (config-var)
+    url: https://api.heroku.com/schema
+  - title: Configuration and config vars
+    url: https://devcenter.heroku.com/articles/config-vars
+  - title: CLI authentication (HEROKU_API_KEY)
+    url: https://devcenter.heroku.com/articles/authentication
+api:
+  base_url: https://api.heroku.com
+  base_url_env: HEROKU_API_URL
+  auth: { bearer_env: HEROKU_API_KEY }
+  media_type: "application/vnd.heroku+json; version=3"
+detect:
+  env: ["HEROKU_*"]
+  files: [heroku.yml]
+  starter:
+    - op: config_var
+  where:
+    app: "the review app's name (`heroku apps`; by default `<pipeline>-pr-<n>`)"
+assumptions:
+  - id: HK1
+    verified: true
+    text: "Requests authenticate as `Authorization: Bearer <token>`; the Heroku CLI reads the token from `HEROKU_API_KEY`."
+    source: https://devcenter.heroku.com/articles/authentication
+  - id: HK2
+    verified: true
+    text: "Every request must send `Accept: application/vnd.heroku+json; version=3`; without it the API refuses the request (documented as 406 `not_acceptable`; a request without it was answered 400 `missing_version` when checked)."
+    source: https://devcenter.heroku.com/articles/platform-api-reference
+  - id: HK3
+    verified: true
+    text: "`GET /apps/{app_id_or_name}/config-vars` answers the app's config vars as one flat map of name to string value."
+    source: https://devcenter.heroku.com/articles/platform-api-reference
+  - id: HK4
+    verified: true
+    text: "`PATCH /apps/{app_id_or_name}/config-vars` with a map sets the named vars and removes those set to `null`, leaving every other var as it is: one var is written without reading or rewriting the others, so concurrent writers of other vars cannot lose them (no lock needed)."
+    source: https://devcenter.heroku.com/articles/platform-api-reference
+  - id: HK5
+    verified: true
+    text: "Config var names match `^\\w+$` and values are strings (`null` only as a delete in a PATCH)."
+    source: https://api.heroku.com/schema
+  - id: HK6
+    verified: true
+    text: "Every change to config vars creates a new release and restarts the app, so a write takes effect without a separate deploy."
+    source: https://devcenter.heroku.com/articles/config-vars
+  - id: HK7
+    verified: true
+    text: "Review apps are created asynchronously (`POST /review-apps` answers `pending` with a nullable `app`), by Heroku itself when the pipeline has automatic review apps; this recipe does not create them, it writes vars on an app that exists (the review app's name or id)."
+    source: https://devcenter.heroku.com/articles/platform-api-reference
+  - id: HK9
+    verified: false
+    text: "A PATCH whose `Content-Type` is the same vendor media type (`media_type` sends it as both `Accept` and `Content-Type`) is accepted like `application/json`; the reference's examples send `application/json`."
+    source: https://devcenter.heroku.com/articles/platform-api-reference
+  - id: HK8
+    verified: false
+    text: "A missing app answers 404 `not_found` on GET and PATCH, which destroy treats as the var being gone."
+    source: https://devcenter.heroku.com/articles/platform-api-reference
+ops:
+  config_var:
+    kind: list_item
+    title: App config var
+    summary: "One config var on a Heroku app, such as a review app's `API_URL`. Written as a merge patch of that one var (`null` deletes it), so other vars, including other scopes', are never rewritten. A console edit of its value is drift; destroy removes only this var. Heroku restarts the app on every change (HK6)."
+    covers: [heroku-config-vars]
+    params:
+      app:
+        type: string
+        required: true
+        description: The app's name or id (a review app's, such as `myapp-pr-42`).
+        example: "myapp-${ctx.scope}"
+      key:
+        type: string
+        required: true
+        pattern: "^\\w+$"
+        description: The config var's name.
+        example: API_URL
+      value:
+        type: string
+        required: true
+        description: "The value: a literal, `{ from }` or `{ secret }`."
+        example: "https://api-${ctx.scope}.example.com"
+    http:
+      parent: { path: "/apps/{app}/config-vars" }
+      list_path: ""
+      shape: map
+      item: { param: key }
+      value: { param: value }
+    sim:
+      objects:
+        "/apps/{app}/config-vars": { DATABASE_URL: "postgres://seeded", LOG_LEVEL: info }
+    live:
+      params: { app: SPONSON_LIVE_HEROKU_APP }