@sponson/adapters 0.0.0-stage → 0.5.0

package/recipes/configcat.yaml

@@ -0,0 +1,123 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# ConfigCat Public Management API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: configcat
+title: ConfigCat
+category: flags
+verified_on: "2026-10-11"
+docs:
+  - title: Public Management API
+    url: https://api.configcat.com/docs/
+  - title: OpenAPI spec (get value v2, replace value v2, targeting rule models)
+    url: https://api.configcat.com/docs/v1/swagger.json
+  - title: Terraform provider (credential variable names)
+    url: https://github.com/configcat/terraform-provider-configcat/blob/main/docs/index.md
+api:
+  base_url: https://api.configcat.com
+  base_url_env: CONFIGCAT_API_URL
+  auth: { basic: { user_env: CONFIGCAT_BASIC_AUTH_USERNAME, password_env: CONFIGCAT_BASIC_AUTH_PASSWORD } }
+detect:
+  deps: [configcat-js, configcat-js-ssr, configcat-js-full, configcat-node, configcat-react]
+  env: ["CONFIGCAT_*"]
+  starter:
+    - op: targeting_rule
+      values: { match: "${ctx.scope}" }
+  where:
+    environment_id: "ConfigCat Dashboard → your product → Environments → the preview environment's ID"
+    setting_id: "ConfigCat Public Management API `GET /v1/configs/{configId}/settings`: the flag's `settingId`"
+assumptions:
+  - id: CC1
+    verified: true
+    text: "The API is at `https://api.configcat.com`, authenticated with Basic auth from Public API credentials (the Terraform provider's `CONFIGCAT_BASIC_AUTH_USERNAME` / `CONFIGCAT_BASIC_AUTH_PASSWORD`)."
+    source: https://api.configcat.com/docs/v1/swagger.json
+  - id: CC2
+    verified: true
+    text: "`GET /v2/environments/{environmentId}/settings/{settingId}/value` answers the setting's value in the environment bare: `defaultValue`, `targetingRules`, `percentageEvaluationAttribute` and read-only fields."
+    source: https://api.configcat.com/docs/v1/swagger.json
+  - id: CC3
+    verified: true
+    text: "`PUT` on the same path replaces the value: only `defaultValue`, `targetingRules` and `percentageEvaluationAttribute` can be set, and one not sent is reset. So those three are sent, as read, with the rule list changed (`parent.send`)."
+    source: https://api.configcat.com/docs/v1/swagger.json
+  - id: CC4
+    verified: true
+    text: "A targeting rule is `{ conditions: [{ userCondition: { comparisonAttribute, comparator, comparisonValue: { stringValue, doubleValue, listValue: [{ value, hint }] } } }], value | percentageOptions }`; rules have no id and are evaluated in order. `isOneOf` and `sensitiveIsOneOf` compare a user attribute with a list."
+    source: https://api.configcat.com/docs/v1/swagger.json
+  - id: CC5
+    verified: true
+    text: "Answers carry every member of a value (`boolValue`, `stringValue`, `intValue`, `doubleValue`, `predefinedVariationId`) and of a comparison value, the unused ones null; the rule is written with the same nulls so that it reads back equal."
+    source: https://api.configcat.com/docs/v1/swagger.json
+  - id: CC6
+    verified: false
+    text: "A condition is read back with `segmentCondition` and `prerequisiteFlagCondition` null and each list value's `hint` null, exactly as written; otherwise every plan shows the rule as changed."
+  - id: CC7
+    verified: false
+    text: "In a product with \"Config changes require a reason\" or approvals turned on, the PUT without `reason` / `bypassApproval` is refused (the query parameters are not sent); the apply then fails."
+    source: https://api.configcat.com/docs/v1/swagger.json
+ops:
+  targeting_rule:
+    kind: list_item
+    title: Feature flag targeting rule
+    summary: "A targeting rule on a boolean feature flag in one environment that serves a value to the preview, such as `IF Preview IS ONE OF [pr-42] THEN true`. Added after the flag's other rules (evaluated in order: an earlier matching rule wins); the default value and the other rules are written back as read. Identified by the matched value; a console edit of its condition or served value is drift. Destroy removes the rule."
+    covers: [configcat-rule]
+    params:
+      environment_id:
+        type: string
+        required: true
+        description: The environment's id (a UUID).
+        example: 08d8becf-d4d9-4c66-8b48-6ac74cd95fba
+      setting_id:
+        type: string
+        required: true
+        pattern: "^[0-9]+$"
+        description: The feature flag's numeric setting id.
+        example: "12345"
+      attribute:
+        type: string
+        required: true
+        description: The user attribute the rule compares (a custom attribute such as `Preview`, or `Identifier`, `Email`).
+        example: Preview
+      comparator:
+        type: string
+        default: isOneOf
+        enum: [isOneOf, sensitiveIsOneOf]
+        description: "`isOneOf`, or `sensitiveIsOneOf` (hashed in the config JSON)."
+      match:
+        type: string
+        required: true
+        description: The attribute value that is the preview; it identifies the rule.
+        example: "${ctx.scope}"
+      serve:
+        type: boolean
+        default: true
+        description: The value the flag serves to the preview.
+    http:
+      parent:
+        path: "/v2/environments/{environment_id}/settings/{setting_id}/value"
+        method: PUT
+        send: [defaultValue, percentageEvaluationAttribute]
+      list_path: /targetingRules
+      key_field: /conditions/0/userCondition/comparisonValue/listValue/0/value
+      item:
+        conditions:
+          - userCondition:
+              comparisonAttribute: { param: attribute }
+              comparator: { param: comparator }
+              comparisonValue:
+                stringValue: null
+                doubleValue: null
+                listValue: [{ value: { param: match }, hint: null }]
+            segmentCondition: null
+            prerequisiteFlagCondition: null
+        value:
+          boolValue: { param: serve }
+          stringValue: null
+          intValue: null
+          doubleValue: null
+          predefinedVariationId: null
+    sim:
+      objects:
+        "/v2/environments/{environment_id}/settings/{setting_id}/value":
+          defaultValue: { boolValue: false, stringValue: null, intValue: null, doubleValue: null, predefinedVariationId: null }
+          targetingRules: []
+          percentageEvaluationAttribute: null
+    live:
+      params: { environment_id: SPONSON_LIVE_CONFIGCAT_ENVIRONMENT_ID, setting_id: SPONSON_LIVE_CONFIGCAT_SETTING_ID }

package/recipes/datadog.yaml

@@ -0,0 +1,136 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Datadog API recipes: every request carries the API key and the application key. Format and checklist:
+# docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: datadog
+title: Datadog
+category: observability
+verified_on: "2026-10-11"
+docs:
+  - title: Synthetics API reference
+    url: https://docs.datadoghq.com/api/latest/synthetics/
+  - title: API authentication (keys, sites)
+    url: https://docs.datadoghq.com/api/latest/authentication/
+  - title: Datadog API v1 OpenAPI document (datadog-api-client)
+    url: https://github.com/DataDog/datadog-api-client-typescript/blob/master/.generator/schemas/v1/openapi.yaml
+api:
+  base_url: https://api.datadoghq.com/api/v1
+  base_url_env: DATADOG_API_URL
+  auth:
+    headers:
+      - { header: DD-API-KEY, value_env: DD_API_KEY }
+      - { header: DD-APPLICATION-KEY, value_env: DD_APP_KEY }
+detect:
+  deps: [dd-trace, "@datadog/"]
+  env: ["DD_*", "DATADOG_*"]
+  starter:
+    - op: synthetic_api_test
+      preview_url: url
+      values: { name: "preview ${ctx.scope}", locations: ["aws:us-east-2"] }
+assumptions:
+  - id: DD1
+    verified: true
+    text: "Requests carry the API key in `DD-API-KEY` and the application key in `DD-APPLICATION-KEY`; Datadog's clients read them from `DD_API_KEY` and `DD_APP_KEY`. Reading needs the application key too."
+    source: https://github.com/DataDog/datadog-api-client-typescript/blob/master/.generator/schemas/v1/openapi.yaml
+  - id: DD2
+    verified: true
+    text: "Each Datadog site has its own API host (`https://api.datadoghq.eu`, `https://api.us3.datadoghq.com`, …): outside US1, set `base_url` in the provider block."
+    source: https://docs.datadoghq.com/api/latest/authentication/
+  - id: DD3
+    verified: true
+    text: "`POST /synthetics/tests/api` creates an API test from `name`, `type` (`api`), `config` (`request` with `method` and `url`, `assertions`), `locations`, `options` and `message` (all required), with `subtype` (`http`), `status` (`live` or `paused`) and `tags`, answering it with its `public_id`."
+    source: https://github.com/DataDog/datadog-api-client-typescript/blob/master/.generator/schemas/v1/openapi.yaml
+  - id: DD4
+    verified: true
+    text: "`GET /synthetics/tests/api/{public_id}` answers one API test; `PUT` on the same path replaces its configuration with a whole test definition."
+    source: https://github.com/DataDog/datadog-api-client-typescript/blob/master/.generator/schemas/v1/openapi.yaml
+  - id: DD5
+    verified: true
+    text: "`GET /synthetics/tests` lists every test as `{ tests: [...] }` (`page_size` and `page_number` are optional); `POST /synthetics/tests/delete` with `{ public_ids: [...] }` deletes tests."
+    source: https://github.com/DataDog/datadog-api-client-typescript/blob/master/.generator/schemas/v1/openapi.yaml
+  - id: DD6
+    verified: false
+    text: "Without `page_size` the list answers every test of the organisation, and a test name identifies one test (two with one name make `find` refuse with PARAM_INVALID)."
+  - id: DD7
+    verified: false
+    text: "The fields compared (`config.request`, `config.assertions`, `locations`, `options.tick_every`, `message`, `status`, `tags`) are answered as they were sent, in order."
+  - id: DD8
+    verified: false
+    text: "Deleting a test that is already gone answers 404 (destroy treats it as done)."
+  - id: DD9
+    verified: false
+    text: "Deployment events (`datadog-ci deployment mark`, the DORA deployments API) are not a recipe: they are listed with a POST over a time window and cannot be deleted, so a later run could not find the one it made."
+ops:
+  synthetic_api_test:
+    kind: resource
+    title: Synthetic API test against a preview
+    summary: "A Synthetic HTTP test per scope that checks the preview's URL from Datadog's locations, such as `preview pr-42` asserting status 200, with its own monitor. Located by its name; a console edit of its request, assertions, locations, frequency, message, status or tags is drift; destroy deletes the test (and its monitor)."
+    covers: [datadog-marker]
+    params:
+      name:
+        type: string
+        required: true
+        description: The test's name; its identity (DD6).
+        example: "preview ${ctx.scope}"
+      url:
+        type: string
+        required: true
+        pattern: "^https?://\\S+$"
+        description: The URL to request (the preview's URL, or a health path on it).
+        example: "https://${ctx.scope}.preview.example.app/api/health"
+      method:
+        type: string
+        default: GET
+        enum: [GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS]
+        description: The HTTP method.
+      assertions:
+        type: list
+        default: [{ type: statusCode, operator: is, target: 200 }]
+        description: "The assertions, each `{ type, operator, target }` (`statusCode`, `responseTime`, `body`, `header`)."
+      locations:
+        type: list
+        required: true
+        description: "The managed locations to run from, such as `aws:us-east-2` or `aws:eu-central-1`."
+        example: ["aws:us-east-2"]
+      tick_every:
+        type: integer
+        default: 300
+        description: How often the test runs, in seconds.
+      message:
+        type: string
+        default: Preview check managed by Sponson
+        description: The notification message of the test's monitor.
+      status:
+        type: string
+        default: live
+        enum: [live, paused]
+        description: "`paused` keeps the test without running it."
+      tags:
+        type: list
+        default: ["managed-by:sponson"]
+        description: The test's tags.
+    http:
+      find:
+        path: /synthetics/tests
+        list_path: /tests
+        match: { name: { param: name } }
+      read: { path: "/synthetics/tests/api/{id}" }
+      create:
+        path: /synthetics/tests/api
+        body: { type: api, subtype: http }
+      update:
+        method: PUT
+        body: { type: api, subtype: http }
+      delete:
+        method: POST
+        path: /synthetics/tests/delete
+        body: { public_ids: ["{id}"] }
+      id_path: /public_id
+      fields:
+        /config/request/method: { param: method }
+        /config/request/url: { param: url }
+        /config/assertions: { param: assertions }
+        locations: { param: locations }
+        /options/tick_every: { param: tick_every }
+        message: { param: message }
+        status: { param: status }
+        tags: { param: tags }

package/recipes/firebase.yaml

@@ -0,0 +1,84 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Firebase Authentication (Identity Toolkit admin API) recipes. Format and checklist: docs/adr/0020-recipes.md,
+# CONTRIBUTING.md "Adding a recipe".
+provider: firebase
+title: Firebase Authentication
+category: auth
+verified_on: "2026-10-11"
+docs:
+  - title: Identity Toolkit API v2, projects.getConfig
+    url: https://docs.cloud.google.com/identity-platform/docs/reference/rest/v2/projects/getConfig
+  - title: Identity Toolkit API v2, projects.updateConfig
+    url: https://docs.cloud.google.com/identity-platform/docs/reference/rest/v2/projects/updateConfig
+  - title: Identity Toolkit API v2, Config
+    url: https://docs.cloud.google.com/identity-platform/docs/reference/rest/v2/Config
+  - title: Authenticate for using REST
+    url: https://docs.cloud.google.com/docs/authentication/rest
+api:
+  base_url: https://identitytoolkit.googleapis.com/admin/v2
+  base_url_env: FIREBASE_API_URL
+  auth: { command: [gcloud, auth, print-access-token] }
+detect:
+  deps: [firebase, firebase-admin]
+  env: ["FIREBASE_*"]
+  files: [firebase.json, .firebaserc]
+  starter:
+    - op: authorized_domain
+  where:
+    project: "`projects.default` in .firebaserc, or `firebase projects:list`"
+    domain: "the preview's host name without `https://` (Firebase takes a domain, so a `{ from }` URL cannot be used)"
+assumptions:
+  - id: FB1
+    verified: true
+    text: "`GET https://identitytoolkit.googleapis.com/admin/v2/projects/{project}/config` answers the project's Auth `Config`."
+    source: https://docs.cloud.google.com/identity-platform/docs/reference/rest/v2/projects/getConfig
+  - id: FB2
+    verified: true
+    text: "`PATCH …/admin/v2/projects/{project}/config?updateMask=authorizedDomains` updates the config with a `Config` body; fields set in the body but not named in `updateMask` are ignored, so the write changes the authorized domains only. It needs one of the `identitytoolkit`, `firebase` or `cloud-platform` OAuth scopes."
+    source: https://docs.cloud.google.com/identity-platform/docs/reference/rest/v2/projects/updateConfig
+  - id: FB3
+    verified: true
+    text: "`authorizedDomains` is a list of strings, the domains authorized for OAuth redirects; the masked field is replaced by the list sent, so the recipe sends the whole list read just before with one domain added or removed."
+    source: https://docs.cloud.google.com/identity-platform/docs/reference/rest/v2/Config
+  - id: FB4
+    verified: true
+    text: "`gcloud auth print-access-token` prints an access token for the signed-in credentials, used as `Authorization: Bearer`. With user credentials some APIs also need the quota project in `x-goog-user-project`: add `headers: { x-goog-user-project: <project> }` to the `providers.http.firebase` block (not needed with a service account; a block's headers are part of its identity)."
+    source: https://docs.cloud.google.com/docs/authentication/rest
+  - id: FB5
+    verified: false
+    text: "The config has no precondition the update honours (no etag in `Config`): the line locks the project's config (`lockOn`) against other Sponson runs; a console edit made between the read and the write can still be lost."
+  - id: FB6
+    verified: false
+    text: "An authorized domain is a host name without scheme, port or path, and is read back exactly as written."
+  - id: FB7
+    verified: false
+    text: "The same admin v2 config holds the authorized domains of a Firebase Authentication project with or without the Identity Platform upgrade."
+ops:
+  authorized_domain:
+    kind: list_item
+    title: Authorized domain
+    summary: "One domain in Firebase Authentication's authorized domains (Authentication, Settings, Authorized domains), which OAuth sign-in redirects and email links require, such as the preview deployment's host. Read-modify-write of the list with `updateMask=authorizedDomains` under a lock on the project's config; removed on destroy; every other domain (localhost, the Firebase hosting domains) is left as it is."
+    covers: [firebase-auth-domains]
+    params:
+      project:
+        type: string
+        required: true
+        description: The Google Cloud / Firebase project id.
+        example: demo-project
+      domain:
+        type: string
+        required: true
+        pattern: "^[A-Za-z0-9.-]+$"
+        description: "The domain, a host name without scheme or path (`pr-42.preview.example.app`, `my-app-git-feat-x.vercel.app`)."
+        example: "${ctx.scope}.preview.example.app"
+    http:
+      parent:
+        path: "/projects/{project}/config?updateMask=authorizedDomains"
+        read_path: "/projects/{project}/config"
+      list_path: /authorizedDomains
+      item: { param: domain }
+    sim:
+      objects:
+        "/projects/{project}/config": { name: projects/demo-project/config, authorizedDomains: [localhost, demo-project.firebaseapp.com, demo-project.web.app] }
+    live:
+      params: { project: SPONSON_LIVE_FIREBASE_PROJECT }

package/recipes/flagsmith.yaml

@@ -0,0 +1,98 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Flagsmith Admin (management) API recipes, authenticated by an organisation API key. Format and checklist:
+# docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: flagsmith
+title: Flagsmith
+category: flags
+verified_on: "2026-10-11"
+docs:
+  - title: Admin API authentication
+    url: https://docs.flagsmith.com/integrating-with-flagsmith/flagsmith-api-overview/admin-api/authentication
+  - title: Admin API overview
+    url: https://docs.flagsmith.com/integrating-with-flagsmith/flagsmith-api-overview/admin-api
+  - title: Flagsmith API OpenAPI document
+    url: https://api.flagsmith.com/api/v1/swagger.json
+api:
+  base_url: https://api.flagsmith.com/api/v1
+  base_url_env: FLAGSMITH_API_URL
+  auth: { header: Authorization, value_env: FLAGSMITH_MASTER_API_KEY, prefix: "Api-Key " }
+detect:
+  deps: [flagsmith, flagsmith-nodejs, react-native-flagsmith]
+  env: ["FLAGSMITH_*"]
+  starter:
+    - op: environment
+      values: { name: "preview-${ctx.scope}" }
+  where:
+    project_id: "Flagsmith → your project: the number in its URL (`/project/<id>/…`)"
+assumptions:
+  - id: FS1
+    verified: true
+    text: "The Admin API authenticates with an organisation API key as `Authorization: Api-Key <key>`; Bearer is only for short-lived OIDC-exchanged tokens."
+    source: https://docs.flagsmith.com/integrating-with-flagsmith/flagsmith-api-overview/admin-api/authentication
+  - id: FS2
+    verified: true
+    text: "`POST /environments/` creates an environment from `name` and `project` (both required) and optional `description`, answering it (201) with its integer `id` and its `api_key`, the client-side environment key SDKs use."
+    source: https://api.flagsmith.com/api/v1/swagger.json
+  - id: FS3
+    verified: true
+    text: "`GET /environments/?project=<id>` lists a project's environments as `{ count, next, previous, results: [...] }`."
+    source: https://api.flagsmith.com/api/v1/swagger.json
+  - id: FS4
+    verified: true
+    text: "`GET`, `PATCH` and `DELETE /environments/{api_key}/` read, update and delete one environment (DELETE answers 204)."
+    source: https://api.flagsmith.com/api/v1/swagger.json
+  - id: FS5
+    verified: false
+    text: "A project has fewer environments than one page of the list holds, so `find` sees them all (`next` is a URL, which the http adapter does not follow)."
+  - id: FS6
+    verified: false
+    text: "A new environment starts with every feature of the project at its default state, and environment names are unique in a project in practice (two with one name make `find` refuse with PARAM_INVALID)."
+  - id: FS7
+    verified: false
+    text: "`description` is answered as sent; `FLAGSMITH_MASTER_API_KEY` is the variable Flagsmith's Terraform provider reads the key from."
+  - id: FS8
+    verified: false
+    text: "Identity and segment overrides are not recipes: Edge projects (Flagsmith SaaS's default) address identities by UUID through `edge-identities`, and a segment override is two objects (a feature segment, then a feature state) created in order."
+  - id: FS9
+    verified: false
+    text: "The create takes the project id as a string of digits (`\"1234\"`) as well as a number, as Django REST Framework's primary-key fields do."
+ops:
+  environment:
+    kind: resource
+    title: Environment per preview
+    summary: "A Flagsmith environment per scope in a project, such as `preview-pr-42`, starting from the project's default flag states; its client-side environment key is the output `api_key` for the preview's SDK configuration. Located by name in the project; a console edit of its description is drift; destroy deletes the environment with its flag states and identities."
+    covers: [flagsmith-override]
+    params:
+      project_id:
+        type: string
+        required: true
+        pattern: "^[0-9]+$"
+        description: The project's id, digits as a string (FS9).
+        example: "1234"
+      name:
+        type: string
+        required: true
+        description: The environment's name; its identity in the project (FS6).
+        example: "preview-${ctx.scope}"
+      description:
+        type: string
+        default: Preview environment managed by Sponson
+        description: The environment's description.
+    http:
+      find:
+        path: "/environments/?project={project_id}"
+        list_path: /results
+        match: { name: { param: name } }
+      read: { path: "/environments/{id}/" }
+      create:
+        path: /environments/
+        body: { project: { param: project_id } }
+      update: { method: PATCH }
+      id_path: /api_key
+      fields:
+        description: { param: description }
+      outputs:
+        api_key: /api_key
+        environment_id: /id
+    live:
+      params: { project_id: SPONSON_LIVE_FLAGSMITH_PROJECT_ID }

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 }