From ea9f54e8f662d9f6e5a6bc7254706d54dac5ea8c Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 6 Mar 2026 15:57:40 +0000
Subject: [PATCH 1/6] Update Speakeasy config: rename requestBodyFieldName to
 body, use positional params in Python

- Change `requestBodyFieldName` from `params` to `body` across all three SDKs
- Switch Python SDK to `flattenRequests: false`, `maxMethodParams: 4`,
  `methodArguments: require-security-and-request` to match Go/TS style
  with positional path params and a named `body=` keyword argument

Expected Python signatures after regeneration:
  outpost.destinations.create("t1", body=DestinationCreate(...))
  outpost.destinations.update("t1", "d1", body=DestinationUpdate(...))

https://claude.ai/code/session_018pZ8NkJ3QqwPR8Aa7QD1eF
---
 sdks/outpost-go/.speakeasy/gen.yaml         | 2 +-
 sdks/outpost-python/.speakeasy/gen.yaml     | 8 ++++----
 sdks/outpost-typescript/.speakeasy/gen.yaml | 2 +-
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/sdks/outpost-go/.speakeasy/gen.yaml b/sdks/outpost-go/.speakeasy/gen.yaml
index bc19dec34..d0480574a 100644
--- a/sdks/outpost-go/.speakeasy/gen.yaml
+++ b/sdks/outpost-go/.speakeasy/gen.yaml
@@ -21,7 +21,7 @@ generation:
     hoistGlobalSecurity: true
   schemas:
     allOfMergeStrategy: shallowMerge
-  requestBodyFieldName: params
+  requestBodyFieldName: body
   versioningStrategy: automatic
   persistentEdits: {}
   tests:
diff --git a/sdks/outpost-python/.speakeasy/gen.yaml b/sdks/outpost-python/.speakeasy/gen.yaml
index 3246bbda8..d10b6bc44 100644
--- a/sdks/outpost-python/.speakeasy/gen.yaml
+++ b/sdks/outpost-python/.speakeasy/gen.yaml
@@ -21,7 +21,7 @@ generation:
     hoistGlobalSecurity: true
   schemas:
     allOfMergeStrategy: shallowMerge
-  requestBodyFieldName: params
+  requestBodyFieldName: body
   versioningStrategy: automatic
   persistentEdits: {}
   tests:
@@ -51,7 +51,7 @@ python:
     conflictResistantModelImportsFeb2026: false
     responseRequiredSep2024: true
   flattenGlobalSecurity: true
-  flattenRequests: true
+  flattenRequests: false
   flatteningOrder: parameters-first
   forwardCompatibleEnumsByDefault: false
   forwardCompatibleUnionsByDefault: "false"
@@ -66,8 +66,8 @@ python:
   inferUnionDiscriminators: true
   inputModelSuffix: input
   license: ""
-  maxMethodParams: 999
-  methodArguments: infer-optional-args
+  maxMethodParams: 4
+  methodArguments: require-security-and-request
   moduleName: ""
   multipartArrayFormat: legacy
   outputModelSuffix: output
diff --git a/sdks/outpost-typescript/.speakeasy/gen.yaml b/sdks/outpost-typescript/.speakeasy/gen.yaml
index 4487c5264..bb8c3c444 100644
--- a/sdks/outpost-typescript/.speakeasy/gen.yaml
+++ b/sdks/outpost-typescript/.speakeasy/gen.yaml
@@ -21,7 +21,7 @@ generation:
     hoistGlobalSecurity: true
   schemas:
     allOfMergeStrategy: shallowMerge
-  requestBodyFieldName: params
+  requestBodyFieldName: body
   versioningStrategy: automatic
   persistentEdits: {}
   tests:

From 44599cf053280d36f90483c3ec704022bbecbd10 Mon Sep 17 00:00:00 2001
From: Phil Leggetter <phil@leggetter.co.uk>
Date: Fri, 6 Mar 2026 17:38:49 +0000
Subject: [PATCH 2/6] fix(examples): use body= in Python create_destination
 example for SDK 0.13.2

destinations.create() now takes body= (not destination_create=) after
requestBodyFieldName: body in gen.yaml.

Made-with: Cursor
---
 examples/sdk-python/example/create_destination.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/sdk-python/example/create_destination.py b/examples/sdk-python/example/create_destination.py
index 666d9bb9e..64399d6df 100644
--- a/examples/sdk-python/example/create_destination.py
+++ b/examples/sdk-python/example/create_destination.py
@@ -99,7 +99,7 @@ def run():
     try:
         resp = sdk.destinations.create(
             tenant_id=tenant_id,
-            destination_create=models.DestinationCreateAzureServiceBus(
+            body=models.DestinationCreateAzureServiceBus(
                 type=(models.DestinationCreateAzureServiceBusType.AZURE_SERVICEBUS),
                 credentials=models.AzureServiceBusCredentials(
                     connection_string=connection_string

From 91c2adc1e46d53e53b25bef08fb3adde3c793c69 Mon Sep 17 00:00:00 2001
From: Phil Leggetter <phil@leggetter.co.uk>
Date: Mon, 9 Mar 2026 11:23:11 +0000
Subject: [PATCH 3/6] feat: tag-triggered SDK generation and release docs

- Add sdk-generate-on-release.yml: generates Go, Python, TS on push tags v*
- Add sdk-generate-one.yml: reusable workflow used by manual and tag-triggered runs
- Refactor manual sdk_generation_outpost_* workflows to call sdk-generate-one
- Add contributing/release.md as primary release playbook (checklist, 1.0.0 override)
- Update CONTRIBUTING.md with Release process and SDKs links
- Update contributing/sdks.md: lock file doc, release section, reusable workflow note

Made-with: Cursor
---
 .github/workflows/sdk-generate-on-release.yml | 50 ++++++++++++
 .github/workflows/sdk-generate-one.yml        | 50 ++++++++++++
 .../workflows/sdk_generation_outpost_go.yaml  | 15 ++--
 .../sdk_generation_outpost_python.yaml        | 17 ++--
 .../workflows/sdk_generation_outpost_ts.yaml  | 17 ++--
 CONTRIBUTING.md                               |  2 +
 contributing/release.md                       | 80 +++++++++++++++++++
 contributing/sdks.md                          | 23 +++++-
 8 files changed, 218 insertions(+), 36 deletions(-)
 create mode 100644 .github/workflows/sdk-generate-on-release.yml
 create mode 100644 .github/workflows/sdk-generate-one.yml
 create mode 100644 contributing/release.md

diff --git a/.github/workflows/sdk-generate-on-release.yml b/.github/workflows/sdk-generate-on-release.yml
new file mode 100644
index 000000000..d85753b79
--- /dev/null
+++ b/.github/workflows/sdk-generate-on-release.yml
@@ -0,0 +1,50 @@
+# Generate all three SDKs (Go, Python, TypeScript) when a version tag is pushed.
+# Runs sequentially to avoid conflicts on the shared .speakeasy/workflow.lock.
+# Uses the reusable sdk-generate-one.yml so logic lives in one place.
+# See contributing/release.md and contributing/sdks.md for the release process and lock file details.
+#
+# Outpost version from the tag is available as github.ref_name (e.g. v0.13.2) in the workflow context.
+# workflow_dispatch allows testing without pushing a tag (run from Actions UI; uses selected branch ref).
+name: SDK generate on release tag
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch: {}   # Run from Actions UI to test without pushing a tag (uses selected branch ref)
+
+jobs:
+  generate-go:
+    uses: ./.github/workflows/sdk-generate-one.yml
+    with:
+      target: outpost-go
+      force: true
+      # SDK version override only when Outpost is released as v1.0.0
+      set_version: ${{ github.ref_name == 'v1.0.0' && '1.0.0' || '' }}
+    secrets:
+      github_access_token: ${{ secrets.GITHUB_TOKEN }}
+      speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
+
+  generate-python:
+    needs: generate-go
+    uses: ./.github/workflows/sdk-generate-one.yml
+    with:
+      target: outpost-python
+      force: true
+      set_version: ${{ github.ref_name == 'v1.0.0' && '1.0.0' || '' }}
+    secrets:
+      github_access_token: ${{ secrets.GITHUB_TOKEN }}
+      speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
+      pypi_token: ${{ secrets.PYPI_TOKEN }}
+
+  generate-ts:
+    needs: generate-python
+    uses: ./.github/workflows/sdk-generate-one.yml
+    with:
+      target: outpost-ts
+      force: true
+      set_version: ${{ github.ref_name == 'v1.0.0' && '1.0.0' || '' }}
+    secrets:
+      github_access_token: ${{ secrets.GITHUB_TOKEN }}
+      speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
+      npm_token: ${{ secrets.NPM_TOKEN }}
diff --git a/.github/workflows/sdk-generate-one.yml b/.github/workflows/sdk-generate-one.yml
new file mode 100644
index 000000000..f15344d5f
--- /dev/null
+++ b/.github/workflows/sdk-generate-one.yml
@@ -0,0 +1,50 @@
+# Reusable workflow: generate one SDK target via Speakeasy.
+# Used by the manual per-language workflows and by sdk-generate-on-release.yml.
+# Callers pass target, optional set_version/force, and the required secrets.
+name: SDK generate one target
+
+on:
+  workflow_call:
+    inputs:
+      target:
+        description: "Speakeasy target (outpost-go, outpost-python, or outpost-ts)"
+        required: true
+        type: string
+      set_version:
+        description: "Optional SDK version override (e.g. 1.0.0). Empty = Speakeasy detection."
+        required: false
+        type: string
+      force:
+        description: "Force generation even if no changes detected"
+        required: false
+        type: boolean
+        default: false
+    secrets:
+      github_access_token:
+        required: true
+      speakeasy_api_key:
+        required: true
+      pypi_token:
+        required: false
+      npm_token:
+        required: false
+
+jobs:
+  generate:
+    permissions:
+      checks: write
+      contents: write
+      pull-requests: write
+      statuses: write
+      id-token: write
+    uses: speakeasy-api/sdk-generation-action/.github/workflows/workflow-executor.yaml@v15
+    with:
+      force: ${{ inputs.force }}
+      mode: pr
+      target: ${{ inputs.target }}
+      set_version: ${{ inputs.set_version || '' }}
+    secrets:
+      github_access_token: ${{ secrets.github_access_token }}
+      speakeasy_api_key: ${{ secrets.speakeasy_api_key }}
+      pypi_token: ${{ secrets.pypi_token }}
+      npm_token: ${{ secrets.npm_token }}
diff --git a/.github/workflows/sdk_generation_outpost_go.yaml b/.github/workflows/sdk_generation_outpost_go.yaml
index e203f13bb..4b7824d70 100644
--- a/.github/workflows/sdk_generation_outpost_go.yaml
+++ b/.github/workflows/sdk_generation_outpost_go.yaml
@@ -1,11 +1,6 @@
 name: Generate OUTPOST-GO
-permissions:
-  checks: write
-  contents: write
-  pull-requests: write
-  statuses: write
-  id-token: write
-"on":
+
+on:
   workflow_dispatch:
     inputs:
       force:
@@ -15,14 +10,14 @@ permissions:
       set_version:
         description: optionally set a specific SDK version
         type: string
+
 jobs:
   generate:
-    uses: speakeasy-api/sdk-generation-action/.github/workflows/workflow-executor.yaml@v15
+    uses: ./.github/workflows/sdk-generate-one.yml
     with:
+      target: outpost-go
       force: ${{ github.event.inputs.force }}
-      mode: pr
       set_version: ${{ github.event.inputs.set_version }}
-      target: outpost-go
     secrets:
       github_access_token: ${{ secrets.GITHUB_TOKEN }}
       speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
diff --git a/.github/workflows/sdk_generation_outpost_python.yaml b/.github/workflows/sdk_generation_outpost_python.yaml
index 436301546..e44898921 100644
--- a/.github/workflows/sdk_generation_outpost_python.yaml
+++ b/.github/workflows/sdk_generation_outpost_python.yaml
@@ -1,11 +1,6 @@
 name: Generate OUTPOST-PYTHON
-permissions:
-  checks: write
-  contents: write
-  pull-requests: write
-  statuses: write
-  id-token: write
-"on":
+
+on:
   workflow_dispatch:
     inputs:
       force:
@@ -15,15 +10,15 @@ permissions:
       set_version:
         description: optionally set a specific SDK version
         type: string
+
 jobs:
   generate:
-    uses: speakeasy-api/sdk-generation-action/.github/workflows/workflow-executor.yaml@v15
+    uses: ./.github/workflows/sdk-generate-one.yml
     with:
+      target: outpost-python
       force: ${{ github.event.inputs.force }}
-      mode: pr
       set_version: ${{ github.event.inputs.set_version }}
-      target: outpost-python
     secrets:
       github_access_token: ${{ secrets.GITHUB_TOKEN }}
-      pypi_token: ${{ secrets.PYPI_TOKEN }}
       speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
+      pypi_token: ${{ secrets.PYPI_TOKEN }}
diff --git a/.github/workflows/sdk_generation_outpost_ts.yaml b/.github/workflows/sdk_generation_outpost_ts.yaml
index 20d6733fe..f0a8fa5ae 100644
--- a/.github/workflows/sdk_generation_outpost_ts.yaml
+++ b/.github/workflows/sdk_generation_outpost_ts.yaml
@@ -1,11 +1,6 @@
 name: Generate OUTPOST-TS
-permissions:
-  checks: write
-  contents: write
-  pull-requests: write
-  statuses: write
-  id-token: write
-"on":
+
+on:
   workflow_dispatch:
     inputs:
       force:
@@ -15,15 +10,15 @@ permissions:
       set_version:
         description: optionally set a specific SDK version
         type: string
+
 jobs:
   generate:
-    uses: speakeasy-api/sdk-generation-action/.github/workflows/workflow-executor.yaml@v15
+    uses: ./.github/workflows/sdk-generate-one.yml
     with:
+      target: outpost-ts
       force: ${{ github.event.inputs.force }}
-      mode: pr
       set_version: ${{ github.event.inputs.set_version }}
-      target: outpost-ts
     secrets:
       github_access_token: ${{ secrets.GITHUB_TOKEN }}
-      npm_token: ${{ secrets.NPM_TOKEN }}
       speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}
+      npm_token: ${{ secrets.NPM_TOKEN }}
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e3ab71e45..50cdb6e89 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -20,3 +20,5 @@ The following guides are a work-in-progress with a focus on helping code contrib
 - [Configuration](contributing/config.md)
 - [Destinations](contributing/destinations.md)
 - [MQ](contributing/mq.md)
+- [Release process](contributing/release.md)
+- [SDKs](contributing/sdks.md)
diff --git a/contributing/release.md b/contributing/release.md
new file mode 100644
index 000000000..0430f69c3
--- /dev/null
+++ b/contributing/release.md
@@ -0,0 +1,80 @@
+# Release process
+
+This document is the **primary** guide for cutting an Outpost release. It covers both the Outpost binary/Docker release and SDK generation. For SDK-specific detail (manual generation, testing, publishing), see [SDKs](sdks.md).
+
+## Overview
+
+An Outpost release is tag-first: you create and push a version tag (e.g. `v0.13.2`). That triggers:
+
+1. **Outpost build and release** — the existing [release workflow](../.github/workflows/release.yml) builds the binary and Docker image and publishes them.
+2. **SDK generation** — the [SDK generate on release tag](../.github/workflows/sdk-generate-on-release.yml) workflow generates all three SDKs (Go, Python, TypeScript) and opens pull requests with the changes.
+
+After the workflows complete, you create the GitHub Release from the tag (or confirm it was created automatically).
+
+## Process
+
+### 1. Create and push a version tag
+
+From the branch you want to release (typically `main`):
+
+```bash
+git tag v0.13.2   # or your next version
+git push origin v0.13.2
+```
+
+Use [Semantic Versioning](https://semver.org/): `vMAJOR.MINOR.PATCH`.
+
+### 2. On tag push — what runs
+
+- **[release.yml](../.github/workflows/release.yml)** — Builds the Outpost binary and Docker image and publishes them (GoReleaser, Docker, etc.).
+- **[sdk-generate-on-release.yml](../.github/workflows/sdk-generate-on-release.yml)** — Generates the Go, Python, and TypeScript SDKs in sequence and opens **three pull requests** (one per SDK). The workflow runs the three generations sequentially to avoid conflicts on the shared `.speakeasy/workflow.lock` (see [SDKs – SDK generation and lock files](sdks.md#sdk-generation-and-lock-files)).
+
+### 3. SDK generation
+
+- The tag-triggered workflow generates all three SDKs and opens PRs with the generated changes.
+- **SDK versions** are determined by **Speakeasy detection** (breaking vs non-breaking changes), not by copying the Outpost tag version. Each SDK uses `versioningStrategy: automatic` in its `gen.yaml`.
+- **Special case — Outpost v1.0.0:** When you cut Outpost **v1.0.0**, the workflow sets all three SDKs to version **1.0.0** so they graduate with the Outpost release.
+- You will see **three SDK PRs** per release tag. Review and merge them (order does not matter; see [sdks.md](sdks.md)).
+
+### 4. Create the GitHub Release
+
+After the workflows complete and (if applicable) SDK PRs are merged:
+
+1. Go to **Releases** in the repository.
+2. Click **Draft a new release**.
+3. Choose the **existing tag** you pushed (e.g. `v0.13.2`).
+4. Add release notes and publish.
+
+If a future workflow is added to create the Release automatically, this step may be optional.
+
+---
+
+## When cutting an Outpost release (checklist)
+
+1. **Create and push the version tag** (e.g. `v0.13.2`) from the correct branch.
+2. **Wait for workflows** — [release.yml](../.github/workflows/release.yml) (Outpost build) and [sdk-generate-on-release.yml](../.github/workflows/sdk-generate-on-release.yml) (SDK generation) run automatically.
+3. **Review and merge the SDK PRs** — Three PRs (Go, Python, TypeScript) will be opened; merge them after review. See [SDKs](sdks.md) for testing and review guidance.
+4. **Create the GitHub Release** — Draft a new release from the tag, add notes, and publish.
+
+For more detail on SDK generation, versioning, and lock files, see [contributing/sdks.md](sdks.md).
+
+## Testing the tag-triggered SDK workflow
+
+To verify that [sdk-generate-on-release.yml](../.github/workflows/sdk-generate-on-release.yml) works without cutting a real release:
+
+1. **Option A — Push a temporary tag**  
+   From the branch you want to test (e.g. `main` or a feature branch):
+   ```bash
+   git tag v0.0.0-sdk-gen-test   # or e.g. v99.99.99-test
+   git push origin v0.0.0-sdk-gen-test
+   ```
+   - In the repo **Actions** tab, open the run for **SDK generate on release tag** and confirm all three jobs (generate-go, generate-python, generate-ts) run in order and open PRs (or commit, depending on the Speakeasy action behaviour).
+   - To remove the tag after testing (optional):
+     ```bash
+     git tag -d v0.0.0-sdk-gen-test
+     git push origin --delete v0.0.0-sdk-gen-test
+     ```
+   **Note:** Pushing a tag also triggers [release.yml](../.github/workflows/release.yml) (Outpost build/release). If you use a test tag, consider using a clearly non-release value (e.g. `v0.0.0-sdk-gen-test`) and skip creating a GitHub Release for it.
+
+2. **Option B — Manual run from Actions**  
+   The workflow supports **Run workflow** from the Actions tab (workflow_dispatch). Go to **Actions → SDK generate on release tag**, click **Run workflow**, choose the branch (e.g. `main`), and run. This uses the branch ref instead of a tag, so no tag or release is created; useful for a quick smoke test. Note: `set_version` is only applied when the ref is tag `v1.0.0`, so on manual runs Speakeasy detection applies.
diff --git a/contributing/sdks.md b/contributing/sdks.md
index e5cdcaced..5288a28ab 100644
--- a/contributing/sdks.md
+++ b/contributing/sdks.md
@@ -6,10 +6,7 @@ This guide covers the complete process for updating, generating, testing, and pu
 
 Outpost SDKs are automatically generated from the [OpenAPI specification](../docs/apis/openapi.yaml) using [Speakeasy](https://www.speakeasyapi.dev/). The SDK generation, testing, and publishing process is managed through GitHub Actions workflows, but currently requires manual triggering and careful coordination to ensure quality.
 
-**Key Point**: SDK generation is currently a **manual process** that requires explicit workflow triggering and version management. Future improvements may include:
-- Automatically triggering SDK generation when Outpost releases are published
-- Only generating SDKs if `docs/apis/openapi.yaml` has changed since the last release
-- Letting Speakeasy handle versioning automatically (it detects breaking vs non-breaking changes), testing and releasing
+**Key Point**: SDK generation runs **automatically when you push a version tag** (e.g. `v0.13.2`). The [release process](release.md) is the primary guide. You can also trigger generation manually per SDK (see below). SDK versions are determined by Speakeasy detection (breaking vs non-breaking); for Outpost v1.0.0 the workflow sets all SDKs to 1.0.0.
 
 ## Prerequisites
 
@@ -55,6 +52,24 @@ Outpost maintains three official SDKs, each in its own directory within the `sdk
 
 Each SDK is maintained as a sub-project within this repository and generated from the shared [OpenAPI specification](../docs/apis/openapi.yaml).
 
+### SDK generation and lock files
+
+When Speakeasy runs SDK generation, it updates the following:
+
+- **Root (shared):** `.speakeasy/workflow.lock` — updated when generation runs (observed when running multiple targets). This is a **shared file** across all three SDKs.
+- **Per-SDK:** Each target updates only its own directory, e.g.:
+  - `sdks/outpost-go/.speakeasy/gen.lock`, `sdks/outpost-go/.speakeasy/gen.yaml`, and all generated output under `sdks/outpost-go/`
+  - `sdks/outpost-python/.speakeasy/gen.lock`, `sdks/outpost-python/.speakeasy/gen.yaml`, and output under `sdks/outpost-python/`
+  - `sdks/outpost-typescript/.speakeasy/gen.lock`, `sdks/outpost-typescript/.speakeasy/gen.yaml`, and output under `sdks/outpost-typescript/`
+
+Because the root `.speakeasy/workflow.lock` is written by generation, **the three SDK generations must run sequentially** (not in parallel) to avoid overwriting or conflicting on that file. The tag-triggered workflow runs Go → Python → TypeScript in order. When using the Speakeasy action with `mode: pr`, each run opens its own PR, so **you will see three SDK PRs per release tag**; they can be merged in any order after review.
+
+All SDK generation (manual per-language and tag-triggered) goes through the same reusable workflow [sdk-generate-one.yml](../.github/workflows/sdk-generate-one.yml), which calls Speakeasy’s action once per target. The manual workflows (Generate OUTPOST-GO, etc.) and the release-tag workflow all use it, so behaviour and version handling stay in one place.
+
+### Outpost release and SDK generation
+
+The full release process (creating the tag, what runs on tag push, merging SDK PRs, creating the GitHub Release) is described in the **[Release process](release.md)** guide. When you push a version tag (e.g. `v0.13.2`), the [SDK generate on release tag](../.github/workflows/sdk-generate-on-release.yml) workflow runs and opens **three pull requests** (one for each SDK). Review and merge them in any order; see [Step 3: Review Generated SDK Pull Requests](#step-3-review-generated-sdk-pull-requests) and [Step 4: Test the Generated SDKs](#step-4-test-the-generated-sdks) below for review and testing.
+
 ## Updating the OpenAPI Specification
 
 All SDK changes begin with updating the OpenAPI specification:

From 82d6a2492caa1a9deab9119dae7d8872485ebac1 Mon Sep 17 00:00:00 2001
From: Phil Leggetter <phil@leggetter.co.uk>
Date: Mon, 9 Mar 2026 12:31:23 +0000
Subject: [PATCH 4/6] docs(release): merge SDK PRs before creating release, tag
 stays on original commit
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Order: tag → workflows → merge SDK PRs → create GitHub Release
- Remove optional 'move the tag' step; document that we do not rewrite the tag
- Clarify that release is created after SDKs are generated and merged

Made-with: Cursor
---
 contributing/release.md | 54 ++++++++++++++++++++++++-----------------
 1 file changed, 32 insertions(+), 22 deletions(-)

diff --git a/contributing/release.md b/contributing/release.md
index 0430f69c3..1a2d2c01b 100644
--- a/contributing/release.md
+++ b/contributing/release.md
@@ -4,12 +4,14 @@ This document is the **primary** guide for cutting an Outpost release. It covers
 
 ## Overview
 
-An Outpost release is tag-first: you create and push a version tag (e.g. `v0.13.2`). That triggers:
+The release flow is: **tag to generate assets** → **merge the SDK PRs into main** → **create the release in GitHub**. We merge the SDK PRs before creating the release so the SDKs are in main when we publish. The tag stays on the commit you tagged; we do not move or rewrite the tag.
 
-1. **Outpost build and release** — the existing [release workflow](../.github/workflows/release.yml) builds the binary and Docker image and publishes them.
-2. **SDK generation** — the [SDK generate on release tag](../.github/workflows/sdk-generate-on-release.yml) workflow generates all three SDKs (Go, Python, TypeScript) and opens pull requests with the changes.
+**Order of operations:**
 
-After the workflows complete, you create the GitHub Release from the tag (or confirm it was created automatically).
+1. **You:** Create and push a version tag (e.g. `v0.13.2`). This triggers the workflows that build assets and open the three SDK PRs (generated from that tag).
+2. **Automated:** Two workflows run — one builds Outpost binaries and Docker images, the other generates SDKs and opens PRs targeting your default branch (e.g. `main`).
+3. **You:** Review and merge the three SDK PRs into main.
+4. **You:** Create the GitHub Release (draft a new release, choose that tag, add notes, publish).
 
 ## Process
 
@@ -24,37 +26,45 @@ git push origin v0.13.2
 
 Use [Semantic Versioning](https://semver.org/): `vMAJOR.MINOR.PATCH`.
 
-### 2. On tag push — what runs
+### 2. What runs automatically on tag push (asset generation)
 
-- **[release.yml](../.github/workflows/release.yml)** — Builds the Outpost binary and Docker image and publishes them (GoReleaser, Docker, etc.).
-- **[sdk-generate-on-release.yml](../.github/workflows/sdk-generate-on-release.yml)** — Generates the Go, Python, and TypeScript SDKs in sequence and opens **three pull requests** (one per SDK). The workflow runs the three generations sequentially to avoid conflicts on the shared `.speakeasy/workflow.lock` (see [SDKs – SDK generation and lock files](sdks.md#sdk-generation-and-lock-files)).
+When you push a tag, two workflows run (they do not depend on each other):
 
-### 3. SDK generation
+| Workflow | What it does |
+|----------|----------------|
+| [release.yml](../.github/workflows/release.yml) | Builds Outpost binaries and Docker images (via GoReleaser) and uploads binary assets so they are available for the tag. Pushes Docker images to Docker Hub (e.g. `hookdeck/outpost:{{ tag }}-amd64`). |
+| [sdk-generate-on-release.yml](../.github/workflows/sdk-generate-on-release.yml) | Generates the Go, Python, and TypeScript SDKs in sequence and opens **three pull requests** (one per SDK). Runs sequentially to avoid conflicts on the shared `.speakeasy/workflow.lock` (see [SDKs – SDK generation and lock files](sdks.md#sdk-generation-and-lock-files)). |
 
-- The tag-triggered workflow generates all three SDKs and opens PRs with the generated changes.
-- **SDK versions** are determined by **Speakeasy detection** (breaking vs non-breaking changes), not by copying the Outpost tag version. Each SDK uses `versioningStrategy: automatic` in its `gen.yaml`.
-- **Special case — Outpost v1.0.0:** When you cut Outpost **v1.0.0**, the workflow sets all three SDKs to version **1.0.0** so they graduate with the Outpost release.
-- You will see **three SDK PRs** per release tag. Review and merge them (order does not matter; see [sdks.md](sdks.md)).
+### 3. Merge the SDK PRs (before creating the release)
+
+The [sdk-generate-on-release.yml](../.github/workflows/sdk-generate-on-release.yml) workflow opens **three pull requests** (Go, Python, TypeScript), generated from the tag you pushed. Merge them into main **before** you create the GitHub Release so the SDKs are in main when we publish the release.
+
+- **SDK versions** are set by **Speakeasy detection** (breaking vs non-breaking), not by the Outpost tag. Exception: when you release **Outpost v1.0.0**, the workflow sets all three SDKs to **1.0.0**.
+- Review and merge the three SDK PRs (order does not matter). See [sdks.md](sdks.md) for testing and review.
 
 ### 4. Create the GitHub Release
 
-After the workflows complete and (if applicable) SDK PRs are merged:
+**You** create the release in GitHub after the workflows have run and the SDK PRs are merged:
+
+1. Go to **Releases** → **Draft a new release**.
+2. Choose the **existing tag** (e.g. `v0.13.2`). The release is tied to that tag (the tag stays on the commit you originally tagged), so GitHub associates the built assets (binaries, etc.) with this release.
+3. Add release notes and publish.
+
+Order: **tag → workflows generate assets and open SDK PRs → merge SDK PRs → create the release in GitHub**.
 
-1. Go to **Releases** in the repository.
-2. Click **Draft a new release**.
-3. Choose the **existing tag** you pushed (e.g. `v0.13.2`).
-4. Add release notes and publish.
+### 5. Outpost binaries (when and where)
 
-If a future workflow is added to create the Release automatically, this step may be optional.
+- **When are they built?** — As soon as the tag is pushed. [release.yml](../.github/workflows/release.yml) runs and uses **GoReleaser** to build the binaries (e.g. `outpost`, `outpost-server`, `outpost-migrate-redis` for linux/amd64 and arm64), archive them (tar.gz), and build Docker images.
+- **Where do they go?** — Binary archives are uploaded so they are available for that tag (e.g. as release assets once you create the release for the tag). Docker images are pushed to Docker Hub (e.g. `hookdeck/outpost:{{ tag }}-amd64`).
 
 ---
 
 ## When cutting an Outpost release (checklist)
 
-1. **Create and push the version tag** (e.g. `v0.13.2`) from the correct branch.
-2. **Wait for workflows** — [release.yml](../.github/workflows/release.yml) (Outpost build) and [sdk-generate-on-release.yml](../.github/workflows/sdk-generate-on-release.yml) (SDK generation) run automatically.
-3. **Review and merge the SDK PRs** — Three PRs (Go, Python, TypeScript) will be opened; merge them after review. See [SDKs](sdks.md) for testing and review guidance.
-4. **Create the GitHub Release** — Draft a new release from the tag, add notes, and publish.
+1. **Create and push the version tag** (e.g. `v0.13.2`) from the correct branch. This triggers asset generation and opens the three SDK PRs.
+2. **Wait for workflows** — [release.yml](../.github/workflows/release.yml) (Outpost binaries + Docker) and [sdk-generate-on-release.yml](../.github/workflows/sdk-generate-on-release.yml) (SDK PRs) run automatically.
+3. **Merge the SDK PRs** — Review and merge the three PRs (Go, Python, TypeScript) into main. See [SDKs](sdks.md) for testing and review guidance.
+4. **Create the GitHub Release** — In GitHub, draft a new release, choose the tag (it stays on the commit you tagged), add release notes, and publish. The built assets are associated with the release via that tag.
 
 For more detail on SDK generation, versioning, and lock files, see [contributing/sdks.md](sdks.md).
 

From 86c643b325dc6b67b973cd8d25f7b3f43ad717f1 Mon Sep 17 00:00:00 2001
From: Phil Leggetter <phil@leggetter.co.uk>
Date: Mon, 9 Mar 2026 13:08:04 +0000
Subject: [PATCH 5/6] docs(sdks): state that workflows run on tag push with
 manual trigger available

Made-with: Cursor
---
 contributing/sdks.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/contributing/sdks.md b/contributing/sdks.md
index 5288a28ab..e811e1b66 100644
--- a/contributing/sdks.md
+++ b/contributing/sdks.md
@@ -4,7 +4,7 @@ This guide covers the complete process for updating, generating, testing, and pu
 
 ## Overview
 
-Outpost SDKs are automatically generated from the [OpenAPI specification](../docs/apis/openapi.yaml) using [Speakeasy](https://www.speakeasyapi.dev/). The SDK generation, testing, and publishing process is managed through GitHub Actions workflows, but currently requires manual triggering and careful coordination to ensure quality.
+Outpost SDKs are automatically generated from the [OpenAPI specification](../docs/apis/openapi.yaml) using [Speakeasy](https://www.speakeasyapi.dev/). The SDK generation, testing, and publishing process is managed through GitHub Actions workflows that run automatically on version tag pushes, with manual triggering also available per SDK.
 
 **Key Point**: SDK generation runs **automatically when you push a version tag** (e.g. `v0.13.2`). The [release process](release.md) is the primary guide. You can also trigger generation manually per SDK (see below). SDK versions are determined by Speakeasy detection (breaking vs non-breaking); for Outpost v1.0.0 the workflow sets all SDKs to 1.0.0.
 

From 1cec1773a9fa86c7de61f4cac109dcf4c53dda1f Mon Sep 17 00:00:00 2001
From: Phil Leggetter <phil@leggetter.co.uk>
Date: Tue, 10 Mar 2026 14:38:03 +0000
Subject: [PATCH 6/6] docs(release): release-first flow, tag trigger note

Made-with: Cursor
---
 contributing/release.md | 57 ++++++++++++++++++++---------------------
 1 file changed, 28 insertions(+), 29 deletions(-)

diff --git a/contributing/release.md b/contributing/release.md
index 1a2d2c01b..03df90c78 100644
--- a/contributing/release.md
+++ b/contributing/release.md
@@ -4,53 +4,52 @@ This document is the **primary** guide for cutting an Outpost release. It covers
 
 ## Overview
 
-The release flow is: **tag to generate assets** → **merge the SDK PRs into main** → **create the release in GitHub**. We merge the SDK PRs before creating the release so the SDKs are in main when we publish. The tag stays on the commit you tagged; we do not move or rewrite the tag.
+**Step one: create the GitHub Release** (with the version tag). That is when Outpost is released. Following that, the tag triggers automatic SDK generation and creation of PRs for all three SDKs, **sequentially**. You then merge those PRs into main, and the SDKs are released. The tag stays on the commit you tagged; we do not move or rewrite the tag.
 
 **Order of operations:**
 
-1. **You:** Create and push a version tag (e.g. `v0.13.2`). This triggers the workflows that build assets and open the three SDK PRs (generated from that tag).
-2. **Automated:** Two workflows run — one builds Outpost binaries and Docker images, the other generates SDKs and opens PRs targeting your default branch (e.g. `main`).
-3. **You:** Review and merge the three SDK PRs into main.
-4. **You:** Create the GitHub Release (draft a new release, choose that tag, add notes, publish).
+1. **You:** Create the **GitHub Release** with the version tag (e.g. `v0.13.2`). That is when Outpost is released. (Create the tag from the target branch when drafting the release if it doesn’t exist yet, or push the tag first and select it.)
+2. **Automated:** The tag triggers two workflows — [release.yml](../.github/workflows/release.yml) builds Outpost binaries and Docker images; [sdk-generate-on-release.yml](../.github/workflows/sdk-generate-on-release.yml) auto-generates the Go, Python, and TypeScript SDKs **sequentially** and opens a PR for each, targeting your default branch (e.g. `main`).
+3. **You:** Merge the three SDK PRs into main.
+4. **Automated:** The SDKs are released when those PRs are merged.
 
 ## Process
 
-### 1. Create and push a version tag
+### 1. Create the GitHub Release (Outpost is released)
 
-From the branch you want to release (typically `main`):
+**You** create the release in GitHub; that is when Outpost is released.
 
-```bash
-git tag v0.13.2   # or your next version
-git push origin v0.13.2
-```
+1. Go to **Releases** → **Draft a new release**.
+2. Attach the version tag (e.g. `v0.13.2`). If the tag doesn’t exist yet, create it from the target branch (e.g. `main`) when drafting the release, or create and push the tag first:
+   ```bash
+   git tag v0.13.2
+   git push origin v0.13.2
+   ```
+   Use [Semantic Versioning](https://semver.org/): `vMAJOR.MINOR.PATCH`.
+3. Add release notes and publish.
+
+The release is tied to that tag; GitHub associates the built assets (binaries, Docker) with the release once the tag exists and [release.yml](../.github/workflows/release.yml) has run.
 
-Use [Semantic Versioning](https://semver.org/): `vMAJOR.MINOR.PATCH`.
+### 2. What runs automatically (SDK generation and PRs)
 
-### 2. What runs automatically on tag push (asset generation)
+Both workflows are triggered on **tag push** (`push: tags: v*`). When you publish the GitHub Release, you attach (or create) the version tag; creating the tag in the UI causes GitHub to fire that tag push, so the workflows run right after the release is published. No change to Actions is needed: listening for the tag is equivalent for this process.
 
-When you push a tag, two workflows run (they do not depend on each other):
+The tag triggers two workflows (they do not depend on each other):
 
 | Workflow | What it does |
 |----------|----------------|
 | [release.yml](../.github/workflows/release.yml) | Builds Outpost binaries and Docker images (via GoReleaser) and uploads binary assets so they are available for the tag. Pushes Docker images to Docker Hub (e.g. `hookdeck/outpost:{{ tag }}-amd64`). |
-| [sdk-generate-on-release.yml](../.github/workflows/sdk-generate-on-release.yml) | Generates the Go, Python, and TypeScript SDKs in sequence and opens **three pull requests** (one per SDK). Runs sequentially to avoid conflicts on the shared `.speakeasy/workflow.lock` (see [SDKs – SDK generation and lock files](sdks.md#sdk-generation-and-lock-files)). |
+| [sdk-generate-on-release.yml](../.github/workflows/sdk-generate-on-release.yml) | Auto-generates the Go, Python, and TypeScript SDKs **sequentially** and opens **three pull requests** (one per SDK), targeting your default branch (e.g. `main`). Sequential runs avoid conflicts on the shared `.speakeasy/workflow.lock` (see [SDKs – SDK generation and lock files](sdks.md#sdk-generation-and-lock-files)). |
 
-### 3. Merge the SDK PRs (before creating the release)
+### 3. Merge the SDK PRs into main
 
-The [sdk-generate-on-release.yml](../.github/workflows/sdk-generate-on-release.yml) workflow opens **three pull requests** (Go, Python, TypeScript), generated from the tag you pushed. Merge them into main **before** you create the GitHub Release so the SDKs are in main when we publish the release.
+Review and merge the **three pull requests** (Go, Python, TypeScript) opened by [sdk-generate-on-release.yml](../.github/workflows/sdk-generate-on-release.yml). Merge order does not matter. See [sdks.md](sdks.md) for testing and review.
 
 - **SDK versions** are set by **Speakeasy detection** (breaking vs non-breaking), not by the Outpost tag. Exception: when you release **Outpost v1.0.0**, the workflow sets all three SDKs to **1.0.0**.
-- Review and merge the three SDK PRs (order does not matter). See [sdks.md](sdks.md) for testing and review.
 
-### 4. Create the GitHub Release
-
-**You** create the release in GitHub after the workflows have run and the SDK PRs are merged:
-
-1. Go to **Releases** → **Draft a new release**.
-2. Choose the **existing tag** (e.g. `v0.13.2`). The release is tied to that tag (the tag stays on the commit you originally tagged), so GitHub associates the built assets (binaries, etc.) with this release.
-3. Add release notes and publish.
+### 4. SDKs are released
 
-Order: **tag → workflows generate assets and open SDK PRs → merge SDK PRs → create the release in GitHub**.
+When the SDK PRs are merged into main, the SDKs are released (published).
 
 ### 5. Outpost binaries (when and where)
 
@@ -61,10 +60,10 @@ Order: **tag → workflows generate assets and open SDK PRs → merge SDK PRs 
 
 ## When cutting an Outpost release (checklist)
 
-1. **Create and push the version tag** (e.g. `v0.13.2`) from the correct branch. This triggers asset generation and opens the three SDK PRs.
-2. **Wait for workflows** — [release.yml](../.github/workflows/release.yml) (Outpost binaries + Docker) and [sdk-generate-on-release.yml](../.github/workflows/sdk-generate-on-release.yml) (SDK PRs) run automatically.
+1. **Create the GitHub Release** — In GitHub, draft a new release, attach the version tag (e.g. `v0.13.2`; create the tag from the target branch if needed), add release notes, and publish. **Outpost is released** when you publish the release.
+2. **Workflows run automatically** — The tag triggers [release.yml](../.github/workflows/release.yml) (Outpost binaries + Docker) and [sdk-generate-on-release.yml](../.github/workflows/sdk-generate-on-release.yml), which generates the three SDKs **sequentially** and opens a PR for each.
 3. **Merge the SDK PRs** — Review and merge the three PRs (Go, Python, TypeScript) into main. See [SDKs](sdks.md) for testing and review guidance.
-4. **Create the GitHub Release** — In GitHub, draft a new release, choose the tag (it stays on the commit you tagged), add release notes, and publish. The built assets are associated with the release via that tag.
+4. **SDKs are released** when those PRs are merged to main.
 
 For more detail on SDK generation, versioning, and lock files, see [contributing/sdks.md](sdks.md).