@sponson/adapters 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sponson/adapters",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The built-in resource adapters and secret sources for Sponson.",
   "keywords": [
     "sponson",
@@ -12,7 +12,8 @@
     "neon",
     "clerk",
     "adapters",
-    "secrets"
+    "secrets",
+    "recipes"
   ],
   "license": "Apache-2.0",
   "repository": {
@@ -33,17 +34,23 @@
     }
   },
   "dependencies": {
-    "@sponson/core": "0.4.0"
+    "yaml": "^2.8.1",
+    "@sponson/core": "0.5.0"
   },
   "devDependencies": {
-    "@sponson/sim": "0.4.0"
+    "@sponson/sim": "0.5.0"
   },
   "files": [
     "dist",
     "!dist/.tsbuildinfo",
+    "recipes",
     "README.md",
     "LICENSE"
   ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "homepage": "https://sponson.mintlify.site",
   "bugs": {
     "url": "https://github.com/MishaBear94/Sponson/issues"

package/recipes/amplify.yaml

@@ -0,0 +1,147 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# AWS Amplify Hosting API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: amplify
+title: AWS Amplify Hosting
+category: deploy
+verified_on: "2026-10-11"
+docs:
+  - title: CreateBranch
+    url: https://docs.aws.amazon.com/amplify/latest/APIReference/API_CreateBranch.html
+  - title: GetBranch
+    url: https://docs.aws.amazon.com/amplify/latest/APIReference/API_GetBranch.html
+  - title: UpdateBranch
+    url: https://docs.aws.amazon.com/amplify/latest/APIReference/API_UpdateBranch.html
+  - title: DeleteBranch
+    url: https://docs.aws.amazon.com/amplify/latest/APIReference/API_DeleteBranch.html
+  - title: Amplify endpoints and quotas
+    url: https://docs.aws.amazon.com/general/latest/gr/amplify.html
+  - title: Create a signed AWS API request (SigV4)
+    url: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-create-signed-request.html
+api:
+  base_url: https://amplify.us-east-1.amazonaws.com
+  base_url_env: AMPLIFY_API_URL
+  auth:
+    aws_sigv4: { region: us-east-1, service: amplify, access_key_id_env: AWS_ACCESS_KEY_ID, secret_access_key_env: AWS_SECRET_ACCESS_KEY }
+detect:
+  files: [amplify.yml]
+  starter:
+    - op: branch_variable
+      values: { branch_name: "${ctx.git.branch}" }
+  where:
+    app_id: "Amplify console → your app → App settings → General → App ID (`d…`), or `aws amplify list-apps --query 'apps[].appId'`"
+assumptions:
+  - id: AM1
+    verified: true
+    text: "The Amplify API is regional (`https://amplify.<region>.amazonaws.com`) and signed with SigV4 for the service `amplify`. The recipe defaults to `us-east-1`; an app in another region sets `base_url` and `auth` (with its `region`) in the provider block, and temporary credentials (a CI role) add `session_token_env: AWS_SESSION_TOKEN` there."
+    source: https://docs.aws.amazon.com/general/latest/gr/amplify.html
+  - id: AM2
+    verified: true
+    text: "`POST /apps/{appId}/branches` (CreateBranch) creates a branch from `branchName` (required) and optional `description`, `stage` (PRODUCTION, BETA, DEVELOPMENT, EXPERIMENTAL, PULL_REQUEST), `enableAutoBuild`, `environmentVariables`, …; it answers 200 with `{ branch }`."
+    source: https://docs.aws.amazon.com/amplify/latest/APIReference/API_CreateBranch.html
+  - id: AM3
+    verified: true
+    text: "`GET /apps/{appId}/branches/{branchName}` (GetBranch) answers `{ branch }` with `branchName`, `stage`, `description`, `enableAutoBuild` and `environmentVariables` (a map of string to string)."
+    source: https://docs.aws.amazon.com/amplify/latest/APIReference/API_GetBranch.html
+  - id: AM4
+    verified: true
+    text: "`POST /apps/{appId}/branches/{branchName}` (UpdateBranch) takes the same optional fields and answers `{ branch }`; `environmentVariables` is the branch's whole map of variables."
+    source: https://docs.aws.amazon.com/amplify/latest/APIReference/API_UpdateBranch.html
+  - id: AM5
+    verified: true
+    text: "`DELETE /apps/{appId}/branches/{branchName}` (DeleteBranch) deletes a branch; an unknown app or branch is 404 `NotFoundException`."
+    source: https://docs.aws.amazon.com/amplify/latest/APIReference/API_DeleteBranch.html
+  - id: AM6
+    verified: false
+    text: "UpdateBranch leaves the fields it is not sent as they are (so the branch op's update does not reset the variables, and the variable op's write does not reset the branch's settings), while an `environmentVariables` it is sent replaces the whole map, as the sim models it (assumption A4 of packages/sim/src/routes/aws.ts)."
+  - id: AM7
+    verified: false
+    text: "A build that ran before a variable was written does not see it: Sponson does not start a new job (StartJob), so order the variable lines before the branch's first build (`enable_auto_build: false` and a CI-started job, or the branch line, then the variables, then the push). The branches Amplify's own pull request previews make are not modelled; this recipe manages a branch the plan names."
+ops:
+  branch:
+    kind: resource
+    title: Branch
+    summary: "An Amplify branch named by the plan (the git branch of the pull request, `${ctx.git.branch}`), created with CreateBranch and deleted on destroy. Its `stage`, `description` and auto-build setting are compared: a console edit is drift. Variables on it are `amplify.branch_variable` lines."
+    covers: [amplify-branch]
+    params:
+      app_id:
+        type: string
+        required: true
+        pattern: "^d[a-z0-9]+$"
+        description: The Amplify app's id.
+        example: d1demo
+      branch_name:
+        type: string
+        required: true
+        description: The branch's name, as the repository names it.
+        example: "${ctx.scope}"
+      stage:
+        type: string
+        enum: [PRODUCTION, BETA, DEVELOPMENT, EXPERIMENTAL, PULL_REQUEST]
+        description: The branch's stage.
+        example: PULL_REQUEST
+      description:
+        type: string
+        description: The branch's description.
+        example: "Preview of ${ctx.scope}"
+      enable_auto_build:
+        type: boolean
+        description: Build automatically on every push (false lets CI start the build after the variables are written; AM7).
+    http:
+      read: { path: "/apps/{app_id}/branches/{branch_name}" }
+      create:
+        path: "/apps/{app_id}/branches"
+        body: { branchName: { param: branch_name } }
+      update: { method: POST }
+      item_path: /branch
+      id_path: /branchName
+      fields:
+        stage: { param: stage }
+        description: { param: description }
+        enableAutoBuild: { param: enable_auto_build }
+    sim:
+      id_from: branchName
+    live:
+      params: { app_id: SPONSON_LIVE_AMPLIFY_APP_ID }
+  branch_variable:
+    kind: list_item
+    title: Branch environment variable
+    summary: "One entry of a branch's `environmentVariables`, by read-modify-write of the whole map (UpdateBranch replaces the map it is sent); other variables are left alone, and the branch is locked while Sponson writes it. A branch that is not there yet reads as having no variables, so a plan that also creates the branch shows a create. Builds started before the write do not see it (AM7)."
+    covers: [amplify-branch]
+    params:
+      app_id:
+        type: string
+        required: true
+        pattern: "^d[a-z0-9]+$"
+        description: The Amplify app's id.
+        example: d1demo
+      branch_name:
+        type: string
+        required: true
+        description: The branch's name (a `{ from }` of the `amplify.branch` line orders the two).
+        example: "${ctx.scope}"
+      name:
+        type: string
+        required: true
+        description: The variable's name.
+        example: API_URL
+      value:
+        type: string
+        required: true
+        description: The variable's value.
+        example: "https://api-${ctx.scope}.example.app"
+    http:
+      parent: { path: "/apps/{app_id}/branches/{branch_name}", method: POST, send: collection, item_path: /branch, if_missing: empty }
+      list_path: /environmentVariables
+      shape: map
+      item: { param: name }
+      value: { param: value }
+    sim:
+      provider: aws
+      base_path: /aws/amplify
+      seed: { amplify: { d1demo: { branches: { pr-42: { environmentVariables: { NODE_ENV: production } } } } } }
+      present: /amplify/d1demo/branches/pr-42/environmentVariables/API_URL
+      drift:
+        changed: { amplify.d1demo.pr-42.API_URL: "https://somewhere-else.example" }
+        missing: { amplify.d1demo.pr-42.API_URL: delete }
+    live:
+      params: { app_id: SPONSON_LIVE_AMPLIFY_APP_ID, branch_name: SPONSON_LIVE_AMPLIFY_BRANCH }

package/recipes/auth0.yaml

@@ -0,0 +1,178 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Auth0 Management API recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: auth0
+title: Auth0
+category: auth
+verified_on: "2026-10-11"
+docs:
+  - title: Get Management API access tokens for production
+    url: https://auth0.com/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production
+  - title: Management API v2, get a client
+    url: https://auth0.com/docs/api/management/v2/clients/get-clients-by-id
+  - title: Management API v2, update a client
+    url: https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id
+  - title: Auth0 Terraform provider, configuration (conventional variable names)
+    url: https://raw.githubusercontent.com/auth0/terraform-provider-auth0/main/docs/index.md
+api:
+  base_url_env: AUTH0_API_URL
+  auth:
+    oauth2_client_credentials:
+      token_url: /oauth/token
+      token_url_env: AUTH0_TOKEN_URL
+      client_id_env: AUTH0_CLIENT_ID
+      client_secret_env: AUTH0_CLIENT_SECRET
+      audience: /api/v2/
+base_url_example: https://acme.eu.auth0.com/api/v2
+detect:
+  deps: [auth0, "@auth0/"]
+  env: ["AUTH0_*"]
+  starter:
+    - op: callback_url
+    - op: logout_url
+      preview_url: url
+  where:
+    base_url: "`https://<tenant>.<region>.auth0.com/api/v2`: Auth0 Dashboard → Settings → General → Domain (the canonical domain, not a custom one)"
+    client_id: "Auth0 Dashboard → Applications → your application → Settings → Client ID"
+    url: "the exact callback URL the app sends as `redirect_uri` on a preview: its URL plus the callback path (a `{ from }` reference cannot carry a path)"
+assumptions:
+  - id: AU1
+    verified: true
+    text: "A machine-to-machine application gets a Management API token from `POST https://<tenant>/oauth/token` (form-encoded `grant_type=client_credentials`, `client_id`, `client_secret`, `audience`); the audience is the Management API's identifier `https://<tenant>/api/v2/`. The answer has `access_token`, `expires_in` (86400 in the example) and `token_type: Bearer`. The recipe writes both as paths, so a plan's `base_url: https://<tenant>/api/v2` names the tenant once."
+    source: https://auth0.com/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production
+  - id: AU2
+    verified: true
+    text: "`GET /api/v2/clients/{id}` answers the application with its `callbacks`, `allowed_logout_urls`, `web_origins` and `allowed_origins` arrays, which only a token with `read:clients` (or `read:client_keys`) receives. `fields` with `include_fields=true` limits the answer to the listed fields, so the recipe never reads the client secret."
+    source: https://auth0.com/docs/api/management/v2/clients/get-clients-by-id
+  - id: AU3
+    verified: true
+    text: "`PATCH /api/v2/clients/{id}` (scope `update:clients`) updates an application; `callbacks`, `allowed_logout_urls`, `web_origins` and `allowed_origins` are arrays of strings, and the body needs at least one property, so a write sends the one array alone."
+    source: https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id
+  - id: AU4
+    verified: false
+    text: "An array sent in a PATCH replaces the stored array whole (it is not merged), so the recipe sends the full list read just before with one URL added or removed. The reference does not say so for these fields."
+  - id: AU5
+    verified: false
+    text: "Updates have no precondition (no ETag or version): the line locks the application (`lockOn`, one lock per tenant and client id, shared by the four ops) against other Sponson runs, and a console edit made between the read and the write can still be lost (the next apply then reports it as drift)."
+  - id: AU6
+    verified: false
+    text: "URLs are stored and read back exactly as written (no trailing slash added or case changed), so a URL identifies its entry."
+  - id: AU7
+    verified: true
+    text: "`AUTH0_CLIENT_ID` and `AUTH0_CLIENT_SECRET` are the variables the Auth0 Terraform provider reads for a machine-to-machine client."
+    source: https://raw.githubusercontent.com/auth0/terraform-provider-auth0/main/docs/index.md
+  - id: AU8
+    verified: false
+    text: "The audience stays the tenant's canonical domain when the tenant has a custom domain, so `base_url` names the canonical domain (`<tenant>.<region>.auth0.com`), not the custom one."
+ops:
+  callback_url:
+    kind: list_item
+    title: Application callback URL
+    summary: "One URL in an Auth0 application's Allowed Callback URLs (`callbacks`), such as the preview's `/callback`; usually `{ from: <deploy line>.preview_url }` joined with the path in the app. Added by read-modify-write of the list under a lock on the application, removed on destroy; every other URL is left as it is. A URL removed in the Dashboard is drift (`missing`) that the next apply puts back."
+    covers: [auth0-callbacks]
+    params:
+      client_id:
+        type: string
+        required: true
+        description: The application's Client ID.
+        example: AbC123dEf456GhI789jKl012MnO345pQ
+      url:
+        type: string
+        required: true
+        pattern: "^https?://\\S+$"
+        description: "The callback URL, exactly as the application sends it as `redirect_uri`."
+        example: "https://${ctx.scope}.preview.example.app/callback"
+    http:
+      parent:
+        path: "/clients/{client_id}"
+        read_path: "/clients/{client_id}?fields=callbacks,allowed_logout_urls,web_origins,allowed_origins&include_fields=true"
+      list_path: /callbacks
+      item: { param: url }
+    sim:
+      objects:
+        "/clients/{client_id}": { callbacks: [https://app.example.com/callback], allowed_logout_urls: [https://app.example.com], web_origins: [https://app.example.com], allowed_origins: [] }
+    live:
+      params: { client_id: SPONSON_LIVE_AUTH0_APP_CLIENT_ID }
+  logout_url:
+    kind: list_item
+    title: Application allowed logout URL
+    summary: "One URL in an Auth0 application's Allowed Logout URLs (`allowed_logout_urls`), where `/v2/logout` may return the user, such as the preview's home page. Read-modify-write of the list under the application's lock; removed on destroy; every other URL is left as it is."
+    covers: [auth0-callbacks]
+    params:
+      client_id:
+        type: string
+        required: true
+        description: The application's Client ID.
+        example: AbC123dEf456GhI789jKl012MnO345pQ
+      url:
+        type: string
+        required: true
+        pattern: "^https?://\\S+$"
+        description: "The URL the application passes as `returnTo` on logout."
+        example: "https://${ctx.scope}.preview.example.app"
+    http:
+      parent:
+        path: "/clients/{client_id}"
+        read_path: "/clients/{client_id}?fields=callbacks,allowed_logout_urls,web_origins,allowed_origins&include_fields=true"
+      list_path: /allowed_logout_urls
+      item: { param: url }
+    sim:
+      objects:
+        "/clients/{client_id}": { callbacks: [https://app.example.com/callback], allowed_logout_urls: [https://app.example.com], web_origins: [https://app.example.com], allowed_origins: [] }
+    live:
+      params: { client_id: SPONSON_LIVE_AUTH0_APP_CLIENT_ID }
+  web_origin:
+    kind: list_item
+    title: Application allowed web origin
+    summary: "One origin in an Auth0 application's Allowed Web Origins (`web_origins`), which silent authentication and the SPA SDKs' token refresh need for the preview's origin. Read-modify-write of the list under the application's lock; removed on destroy; every other origin is left as it is."
+    covers: [auth0-callbacks]
+    params:
+      client_id:
+        type: string
+        required: true
+        description: The application's Client ID.
+        example: AbC123dEf456GhI789jKl012MnO345pQ
+      origin:
+        type: string
+        required: true
+        pattern: "^https?://[^/\\s]+$"
+        description: "The origin, scheme and host without a path (`https://pr-42.preview.example.app`)."
+        example: "https://${ctx.scope}.preview.example.app"
+    http:
+      parent:
+        path: "/clients/{client_id}"
+        read_path: "/clients/{client_id}?fields=callbacks,allowed_logout_urls,web_origins,allowed_origins&include_fields=true"
+      list_path: /web_origins
+      item: { param: origin }
+    sim:
+      objects:
+        "/clients/{client_id}": { callbacks: [https://app.example.com/callback], allowed_logout_urls: [https://app.example.com], web_origins: [https://app.example.com], allowed_origins: [] }
+    live:
+      params: { client_id: SPONSON_LIVE_AUTH0_APP_CLIENT_ID }
+  allowed_origin:
+    kind: list_item
+    title: Application allowed origin (CORS)
+    summary: "One origin in an Auth0 application's Allowed Origins (CORS, `allowed_origins`), for a preview that calls Auth0 from the browser across origins (embedded login, cross-origin authentication). Read-modify-write of the list under the application's lock; removed on destroy; every other origin is left as it is."
+    covers: [auth0-callbacks]
+    params:
+      client_id:
+        type: string
+        required: true
+        description: The application's Client ID.
+        example: AbC123dEf456GhI789jKl012MnO345pQ
+      origin:
+        type: string
+        required: true
+        pattern: "^https?://[^/\\s]+$"
+        description: "The origin, scheme and host without a path (`https://pr-42.preview.example.app`)."
+        example: "https://${ctx.scope}.preview.example.app"
+    http:
+      parent:
+        path: "/clients/{client_id}"
+        read_path: "/clients/{client_id}?fields=callbacks,allowed_logout_urls,web_origins,allowed_origins&include_fields=true"
+      list_path: /allowed_origins
+      item: { param: origin }
+    sim:
+      objects:
+        "/clients/{client_id}": { callbacks: [https://app.example.com/callback], allowed_logout_urls: [https://app.example.com], web_origins: [https://app.example.com], allowed_origins: [] }
+    live:
+      params: { client_id: SPONSON_LIVE_AUTH0_APP_CLIENT_ID }

package/recipes/azure_swa.yaml

@@ -0,0 +1,116 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Azure Static Web Apps (Azure Resource Manager) recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: azure_swa
+title: Azure Static Web Apps
+category: deploy
+verified_on: "2026-10-11"
+docs:
+  - title: Static Sites - Create Or Update Static Site Build App Settings
+    url: https://learn.microsoft.com/en-us/rest/api/appservice/static-sites/create-or-update-static-site-build-app-settings?view=rest-appservice-2024-04-01
+  - title: Static Sites - List Static Site Build App Settings
+    url: https://learn.microsoft.com/en-us/rest/api/appservice/static-sites/list-static-site-build-app-settings?view=rest-appservice-2024-04-01
+  - title: Static Sites - Get Static Site Builds
+    url: https://learn.microsoft.com/en-us/rest/api/appservice/static-sites/get-static-site-builds?view=rest-appservice-2024-04-01
+  - title: Preview environments in Azure Static Web Apps
+    url: https://learn.microsoft.com/en-us/azure/static-web-apps/preview-environments
+  - title: Configure application settings for Azure Static Web Apps
+    url: https://learn.microsoft.com/en-us/azure/static-web-apps/application-settings
+  - title: az account get-access-token
+    url: https://learn.microsoft.com/en-us/cli/azure/account#az-account-get-access-token
+api:
+  base_url: https://management.azure.com
+  base_url_env: AZURE_SWA_API_URL
+  auth: { command: [az, account, get-access-token, --query, accessToken, -o, tsv] }
+detect:
+  files: [staticwebapp.config.json]
+  env: ["AZURE_STATIC_WEB_APPS_*"]
+  starter:
+    - op: build_app_setting
+      values: { environment: "${ctx.pr.number}" }
+  where:
+    subscription_id: "`az account show --query id -o tsv`"
+    resource_group: "`az staticwebapp show --name <site> --query resourceGroup -o tsv`"
+    site: "`az staticwebapp list --query '[].name'`"
+assumptions:
+  - id: AZ1
+    verified: true
+    text: "`PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/staticSites/{name}/builds/{environmentName}/config/appsettings?api-version=2024-04-01` with `{ properties: { <name>: <value>, … } }` sets the app settings of one environment (build) and answers 200 with the same `properties`."
+    source: https://learn.microsoft.com/en-us/rest/api/appservice/static-sites/create-or-update-static-site-build-app-settings?view=rest-appservice-2024-04-01
+  - id: AZ2
+    verified: true
+    text: "The settings are read with `POST …/builds/{environmentName}/listAppSettings?api-version=2024-04-01` (no body), which answers a StringDictionary `{ id, properties }`; there is no GET, so the recipe reads with `parent.read_method: POST`."
+    source: https://learn.microsoft.com/en-us/rest/api/appservice/static-sites/list-static-site-build-app-settings?view=rest-appservice-2024-04-01
+  - id: AZ3
+    verified: true
+    text: "Each environment is a `builds/{environmentName}` resource: production is `default`, a pull request's preview environment is named by the pull request's number (`builds/12`)."
+    source: https://learn.microsoft.com/en-us/rest/api/appservice/static-sites/get-static-site-builds?view=rest-appservice-2024-04-01
+  - id: AZ4
+    verified: true
+    text: "A preview environment exists from the pull request's first deployment and is deleted, with its settings, when the pull request is closed; app settings reach the app's managed API (Functions), not the front-end build."
+    source: https://learn.microsoft.com/en-us/azure/static-web-apps/preview-environments
+  - id: AZ5
+    verified: true
+    text: "`az account get-access-token --query accessToken -o tsv` prints an Azure Resource Manager access token for the signed-in account (the default resource is `https://management.azure.com/`), sent as a bearer token."
+    source: https://learn.microsoft.com/en-us/cli/azure/account#az-account-get-access-token
+  - id: AZ6
+    verified: false
+    text: "The PUT replaces the whole settings map (a setting it is not sent is removed), so the recipe sends the map as read with the one entry changed (`send: collection`); there is no ETag on this resource, so only Sponson's own writers are serialised (the parent lock), and a setting added in the portal between the read and the write is lost."
+  - id: AZ7
+    verified: false
+    text: "Listing the settings of an environment that does not exist (not deployed yet, or deleted with its pull request) answers 404, which the recipe reads as no settings (`if_missing: empty`): plan shows a create before the first deploy, and destroy after the pull request closed is a no-op. A write before the first deploy fails with that 404; order the line after the deploy."
+ops:
+  build_app_setting:
+    kind: list_item
+    title: App setting of a preview environment
+    summary: "One app setting of a Static Web App environment (a pull request's preview environment is named by its number), by read-modify-write of the environment's settings: read with `listAppSettings`, written whole with a PUT. Other settings are left alone and the environment is locked while Sponson writes it. Settings reach the app's managed API, not the front-end build (AZ4); the environment exists only after the PR's first deploy (AZ7)."
+    covers: [azure-swa-settings]
+    params:
+      subscription_id:
+        type: string
+        required: true
+        description: The Azure subscription id.
+        example: 00000000-0000-0000-0000-000000000000
+      resource_group:
+        type: string
+        required: true
+        description: The resource group of the static web app.
+        example: rg-web
+      site:
+        type: string
+        required: true
+        description: The static web app's name.
+        example: web
+      environment:
+        type: string
+        required: true
+        pattern: "^[a-zA-Z0-9]+$"
+        description: The environment's name (the pull request's number for its preview environment; `default` is production).
+        example: "42"
+      name:
+        type: string
+        required: true
+        description: The setting's name.
+        example: API_URL
+      value:
+        type: string
+        required: true
+        description: The setting's value.
+        example: "https://api-${ctx.scope}.example.app"
+    http:
+      parent:
+        path: "/subscriptions/{subscription_id}/resourceGroups/{resource_group}/providers/Microsoft.Web/staticSites/{site}/builds/{environment}/config/appsettings?api-version=2024-04-01"
+        read_path: "/subscriptions/{subscription_id}/resourceGroups/{resource_group}/providers/Microsoft.Web/staticSites/{site}/builds/{environment}/listAppSettings?api-version=2024-04-01"
+        read_method: POST
+        method: PUT
+        send: collection
+        if_missing: empty
+      list_path: /properties
+      shape: map
+      item: { param: name }
+      value: { param: value }
+    sim:
+      objects:
+        "/subscriptions/{subscription_id}/resourceGroups/{resource_group}/providers/Microsoft.Web/staticSites/{site}/builds/{environment}/config/appsettings":
+          properties: { SHARED_SETTING: from-the-portal }
+    live:
+      params: { subscription_id: SPONSON_LIVE_AZURE_SUBSCRIPTION_ID, resource_group: SPONSON_LIVE_AZURE_RESOURCE_GROUP, site: SPONSON_LIVE_AZURE_SWA_SITE, environment: SPONSON_LIVE_AZURE_SWA_ENVIRONMENT }

package/recipes/cloud_run.yaml

@@ -0,0 +1,97 @@
+# yaml-language-server: $schema=../../../schema/recipe.schema.json
+# Google Cloud Run Admin API v2 recipes. Format and checklist: docs/adr/0020-recipes.md, CONTRIBUTING.md "Adding a recipe".
+provider: cloud_run
+title: Google Cloud Run
+category: deploy
+verified_on: "2026-10-11"
+docs:
+  - title: "REST Resource: projects.locations.services (Service, TrafficTarget)"
+    url: https://docs.cloud.google.com/run/docs/reference/rest/v2/projects.locations.services
+  - title: "Method: projects.locations.services.patch"
+    url: https://docs.cloud.google.com/run/docs/reference/rest/v2/projects.locations.services/patch
+  - title: "Method: projects.locations.services.get"
+    url: https://docs.cloud.google.com/run/docs/reference/rest/v2/projects.locations.services/get
+  - title: Rollbacks, gradual rollouts, and traffic migration (tags)
+    url: https://cloud.google.com/run/docs/rollouts-rollbacks-traffic-migration
+  - title: gcloud auth print-access-token
+    url: https://cloud.google.com/sdk/gcloud/reference/auth/print-access-token
+api:
+  base_url: https://run.googleapis.com/v2
+  base_url_env: CLOUD_RUN_API_URL
+  auth: { command: [gcloud, auth, print-access-token] }
+assumptions:
+  - id: CR1
+    verified: true
+    text: "`GET https://run.googleapis.com/v2/projects/{project}/locations/{location}/services/{service}` answers the Service with its `traffic` list and an `etag`, 'a system-generated fingerprint for this version of the resource' that 'may be used to detect modification conflict during updates'."
+    source: https://docs.cloud.google.com/run/docs/reference/rest/v2/projects.locations.services
+  - id: CR2
+    verified: true
+    text: "`PATCH https://run.googleapis.com/v2/{service.name}` takes a Service and an optional `updateMask` (fields to update), answers a long-running Operation, and needs the `cloud-platform` scope; the recipe sends `?updateMask=traffic` with `{ traffic, etag }` only, so the revision template is never written."
+    source: https://docs.cloud.google.com/run/docs/reference/rest/v2/projects.locations.services/patch
+  - id: CR3
+    verified: true
+    text: "A TrafficTarget is `{ type, revision, percent, tag }`; `type: TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION` sends traffic to the named `revision`, `percent` defaults to zero, and `tag` is 'a string to be part of the URI to exclusively reference this target', which is the per-PR URL."
+    source: https://docs.cloud.google.com/run/docs/reference/rest/v2/projects.locations.services
+  - id: CR4
+    verified: true
+    text: "`gcloud auth print-access-token` prints an OAuth access token for the active account, sent as a bearer token."
+    source: https://cloud.google.com/sdk/gcloud/reference/auth/print-access-token
+  - id: CR5
+    verified: false
+    text: "A patch whose `etag` no longer matches (a deploy changed the service after the read) is refused (409 ABORTED or 412) rather than applied: the line fails and the next apply reads again, so a concurrent `gcloud run deploy` is never overwritten. Sponson's own writers are serialised by the parent lock."
+  - id: CR6
+    verified: false
+    text: "The Service answered right after the patch's Operation is accepted already shows the new `traffic` (the desired state), so the re-read that confirms the write sees the tag; `percent` 0 is left out of the answer and `type` and `revision` are answered as sent."
+  - id: CR7
+    verified: false
+    text: "The revision a tag points to exists before the line applies: the PR's deploy creates it (`gcloud run deploy --no-traffic --revision-suffix <scope>` gives `<service>-<scope>`). Its environment variables are part of that revision, set by the deploy, not by this recipe; a deploy that tags (`--tag`) itself conflicts with this line's tag."
+ops:
+  traffic_tag:
+    kind: list_item
+    title: Traffic tag of a revision
+    summary: "A tag (`pr-42`) in a service's `traffic` list pointing at the PR's revision with no traffic share, which gives the revision its own URL (`https://pr-42---<service>-<hash>.a.run.app`). Read-modify-write of `traffic` only (`updateMask=traffic`), sent with the service's `etag` so a concurrent deploy makes the write fail instead of being overwritten (CR5); other tags and the traffic split are left alone, and destroy removes only this tag. The revision itself, and its environment variables, are the deploy's (CR7)."
+    covers: []
+    params:
+      project:
+        type: string
+        required: true
+        description: The Google Cloud project id.
+        example: demo-project
+      region:
+        type: string
+        required: true
+        description: The service's region.
+        example: us-central1
+      service:
+        type: string
+        required: true
+        description: The Cloud Run service's name.
+        example: web
+      tag:
+        type: string
+        required: true
+        pattern: "^[a-z][a-z0-9-]*$"
+        description: The tag, the prefix of the revision's own URL.
+        example: "${ctx.scope}"
+      revision:
+        type: string
+        required: true
+        description: The revision the tag points to (made by the PR's deploy).
+        example: "web-${ctx.scope}"
+    http:
+      parent:
+        path: "/projects/{project}/locations/{region}/services/{service}?updateMask=traffic"
+        read_path: "/projects/{project}/locations/{region}/services/{service}"
+        method: PATCH
+        send: [etag]
+      list_path: /traffic
+      key_field: tag
+      item: { tag: { param: tag }, revision: { param: revision }, type: TRAFFIC_TARGET_ALLOCATION_TYPE_REVISION }
+    sim:
+      objects:
+        "/projects/{project}/locations/{region}/services/{service}":
+          name: projects/demo-project/locations/us-central1/services/web
+          etag: '"sim-etag-1"'
+          traffic: [{ type: TRAFFIC_TARGET_ALLOCATION_TYPE_LATEST, percent: 100 }]
+    live:
+      params: { project: SPONSON_LIVE_GCP_PROJECT, region: SPONSON_LIVE_CLOUD_RUN_REGION, service: SPONSON_LIVE_CLOUD_RUN_SERVICE, revision: SPONSON_LIVE_CLOUD_RUN_REVISION }