@sponson/adapters 0.0.0-stage → 0.5.0

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,123 @@
+# 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: false
+    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`."
+  - 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 }

package/recipes/honeycomb.yaml

@@ -0,0 +1,89 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Honeycomb API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: honeycomb
+title: Honeycomb
+category: observability
+verified_on: "2026-10-11"
+docs:
+  - title: Create a Marker
+    url: https://docs.honeycomb.io/api/markers/create-a-marker
+  - title: List All Markers
+    url: https://docs.honeycomb.io/api/markers
+  - title: Update a Marker
+    url: https://docs.honeycomb.io/api/markers/update-a-marker
+  - title: Delete a Marker
+    url: https://docs.honeycomb.io/api/markers/delete-a-marker
+api:
+  base_url: https://api.honeycomb.io
+  base_url_env: HONEYCOMB_API_URL
+  auth: { header: X-Honeycomb-Team, value_env: HONEYCOMB_API_KEY }
+detect:
+  deps: ["@honeycombio/"]
+  env: ["HONEYCOMB_*"]
+  starter:
+    - op: marker
+      values: { dataset: __all__, message: "deploy ${ctx.scope} ${ctx.git.sha}" }
+assumptions:
+  - id: HC1
+    verified: true
+    text: "`POST /1/markers/{datasetSlug}` creates a marker from `start_time`, `end_time` (Unix seconds), `message`, `type` and `url` (all optional; `start_time` defaults to the request's arrival), answering 201 with the marker and its `id`; `__all__` as the dataset slug makes an environment-wide marker. Requests carry a Configuration Key with the Manage Markers permission in `X-Honeycomb-Team`."
+    source: https://docs.honeycomb.io/api/markers/create-a-marker
+  - id: HC2
+    verified: true
+    text: "`GET /1/markers/{datasetSlug}` answers a bare array of the dataset's markers (`id`, `message`, `type`, `url`, `start_time`, `end_time`, `created_at`, `updated_at`, `color`)."
+    source: https://docs.honeycomb.io/api/markers
+  - id: HC3
+    verified: true
+    text: "`PUT /1/markers/{datasetSlug}/{markerId}` replaces the marker: a field left out of the body is erased."
+    source: https://docs.honeycomb.io/api/markers/update-a-marker
+  - id: HC4
+    verified: true
+    text: "`DELETE /1/markers/{datasetSlug}/{markerId}` removes the marker and answers it (200)."
+    source: https://docs.honeycomb.io/api/markers/delete-a-marker
+  - id: HC5
+    verified: true
+    text: "The API is served from `api.honeycomb.io` (US) and `api.eu1.honeycomb.io` (EU); EU teams set `base_url` in the provider block."
+    source: https://docs.honeycomb.io/api/markers/create-a-marker
+  - id: HC6
+    verified: false
+    text: "Message and type identify the marker this recipe created among the dataset's markers (Honeycomb does not require them to be unique: two equal ones make `find` refuse with PARAM_INVALID), and the list holds every marker of the dataset in one answer."
+  - id: HC7
+    verified: false
+    text: "An update (a changed `url`) re-sends message, type and url but not `start_time`, which Honeycomb then sets to the time of the update (HC3), moving the marker; markers are rarely edited."
+  - id: HC8
+    verified: false
+    text: "A deleted marker answers 404 to DELETE, which destroy treats as already gone."
+ops:
+  marker:
+    kind: resource
+    title: Deploy marker
+    summary: "A marker on an environment's dataset (or on every dataset of the environment with `__all__`) for a deploy, such as `deploy pr-42 0123abc`. Located by its message and type; a console edit of its URL is drift. Destroying the scope removes it; write `destroy: keep` to keep the deploy history."
+    covers: [honeycomb-marker]
+    params:
+      dataset:
+        type: string
+        required: true
+        description: The dataset's slug, or `__all__` for an environment-wide marker.
+        example: __all__
+      message:
+        type: string
+        required: true
+        description: The marker's text; with its type, its identity (HC6).
+        example: "deploy ${ctx.scope} ${ctx.git.sha}"
+      type:
+        type: string
+        default: deploy
+        description: The marker's type, which groups markers (and their color).
+      url:
+        type: string
+        description: The link opened from the marker (the preview or the build).
+        example: "https://${ctx.scope}.preview.example.com"
+    http:
+      find:
+        path: "/1/markers/{dataset}"
+        match: { message: { param: message }, type: { param: type } }
+      create: { path: "/1/markers/{dataset}" }
+      update: { method: PUT, path: "/1/markers/{dataset}/{id}" }
+      delete: { path: "/1/markers/{dataset}/{id}" }
+      fields:
+        url: { param: url }

package/recipes/inngest.yaml

@@ -0,0 +1,97 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Inngest recipes. Format and checklist: docs/adr/0020-recipes.md, docs/adr/0022-one-off-actions.md, CONTRIBUTING.md
+# "Adding a recipe". No API block: the sync is a request to the app's own serve endpoint, which registers itself
+# with Inngest using its own signing key, so Sponson sends no Inngest credential at all.
+provider: inngest
+title: Inngest
+category: queues
+verified_on: "2026-10-11"
+docs:
+  - title: Syncing an Inngest app (curl -X PUT on the serve endpoint), Inngest's integration guide
+    url: https://www.inngest.com/llm-context.md
+  - title: Apps in Inngest Cloud (sync methods, when to sync)
+    url: https://www.inngest.com/docs/apps/cloud
+  - title: Environments and branch environments
+    url: https://www.inngest.com/docs/platform/environments
+  - title: The TypeScript SDK's serve handler (InngestCommHandler, PUT = register)
+    url: https://github.com/inngest/inngest-js/blob/main/packages/inngest/src/components/InngestCommHandler.ts
+  - title: REST API v2 OpenAPI document (V2_SyncApp)
+    url: https://api-docs.inngest.com/api-specs/v2.json
+detect:
+  deps: [inngest]
+  env: ["INNGEST_*"]
+  starter:
+    - op: sync
+      preview_url: url
+      values: { revision: "${ctx.git.sha}" }
+assumptions:
+  - id: IN1
+    verified: true
+    text: "A `PUT` to the app's serve endpoint (by convention `/api/inngest`, `curl -X PUT https://your-app.com/api/inngest --fail-with-body`) makes the app's SDK register its functions with Inngest; the SDK authenticates that registration with the app's own `INNGEST_SIGNING_KEY`, so the caller sends no credential."
+    source: https://www.inngest.com/llm-context.md
+  - id: IN2
+    verified: true
+    text: "The app registers into the environment its SDK is configured for: `INNGEST_ENV` (or the client's `env` option) names the branch environment and always wins; Vercel's `VERCEL_GIT_COMMIT_REF` is detected automatically, while Netlify, Cloudflare Pages, Railway and Render must pass their branch variable. Sponson does not choose the environment: the app must be configured so."
+    source: https://www.inngest.com/docs/platform/environments
+  - id: IN3
+    verified: true
+    text: "A branch environment is created on demand the first time an app syncs with it (or events are sent to it), and every branch environment shares one signing key and one event key, so a preview needs no per-branch key."
+    source: https://www.inngest.com/docs/platform/environments
+  - id: IN4
+    verified: true
+    text: "Without `x-inngest-sync-kind: in-band` (which this recipe never sends) the serve handler syncs out of band: it calls Inngest's register endpoint itself and answers with that call's status and a JSON body `{ message, modified }`; a failed registration answers 500 (`Failed to register`)."
+    source: https://github.com/inngest/inngest-js/blob/main/packages/inngest/src/components/InngestCommHandler.ts
+  - id: IN5
+    verified: true
+    text: "Sync only once the new version of the code is live: some hosts roll a deploy out over seconds or minutes and an early sync registers the old functions. The recipe's trigger is the deployment's URL (a deploy line's external output, so the line waits for the deploy) and a revision."
+    source: https://www.inngest.com/docs/apps/cloud
+  - id: IN6
+    verified: true
+    text: "Branch environments are archived automatically three days after their latest deployment (archiving stops functions from triggering and keeps the data), and archiving cannot be undone per app; there is no request to undo a sync, so destroy sends nothing and forgets the record."
+    source: https://www.inngest.com/docs/platform/environments
+  - id: IN7
+    verified: true
+    text: "The REST API's `POST /v2/apps/{appId}/syncs` (marked beta, `x-beta: true`) takes `{ url }` and answers a sync with `status` pending, success, error or duplicate, but the operation declares no header or parameter that selects a branch environment; this recipe does not use it."
+    source: https://api-docs.inngest.com/api-specs/v2.json
+  - id: IN8
+    verified: false
+    text: "Syncing the same deployment again is harmless (the same functions registered again, `modified: false`), so the at-least-once delivery of an action (sent again after a crash before it was recorded) needs no idempotency key."
+  - id: IN9
+    verified: false
+    text: "A preview behind Vercel Deployment Protection answers the `PUT` with 401 unless it carries `x-vercel-protection-bypass` with the project's automation bypass secret; pass it with `headers`, as a `{ secret }`."
+ops:
+  sync:
+    kind: action
+    title: App sync into its branch environment
+    summary: Registers a preview deployment's Inngest functions by sending `PUT` to its serve endpoint, once per deployment URL and revision; the app's SDK picks the branch environment (`INNGEST_ENV`, IN2) and signs the registration with its own key (IN1), so no Inngest credential is needed.
+    covers: [inngest-sync]
+    params:
+      url:
+        type: string
+        description: "The deployment's base URL, without a trailing slash: usually `{ from: <deploy line>.preview_url }`, so the sync waits for the deploy (IN5)."
+        required: true
+        pattern: "^https?://\\S+[^/]$"
+        example: https://acme-git-feat-x-acme.vercel.app
+      path:
+        type: string
+        description: Where the app serves Inngest's `serve()` handler, appended to `url`.
+        default: /api/inngest
+        pattern: "^/\\S*$"
+      revision:
+        type: string
+        description: "What else makes it sync again when it changes, usually the commit: `\"${ctx.git.sha}\"`."
+        required: true
+        example: "${ctx.git.sha}"
+      headers:
+        type: map
+        description: "Extra request headers, such as `x-vercel-protection-bypass: { secret: env://VERCEL_AUTOMATION_BYPASS_SECRET }` for a protected preview (IN9)."
+    http:
+      trigger: { url: { param: url }, path: { param: path }, revision: { param: revision } }
+      request:
+        method: PUT
+        url: { join: [{ param: url }, { param: path }] }
+        headers: { param: headers }
+      outputs: { modified: /modified }
+    live:
+      # A deployed app with Inngest's serve handler and INNGEST_ENV set to a throwaway branch environment.
+      params: { url: SPONSON_LIVE_INNGEST_APP_URL }