feat: tag-triggered SDK generation and release docs

.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 }}

.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 }}

.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 }}

.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 }}

.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 }}

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)

contributing/release.md

@@ -0,0 +1,89 @@
+# 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
+
+**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 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 the GitHub Release (Outpost is released)
+
+**You** create the release in GitHub; that is when Outpost is released.
+
+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.
+
+### 2. What runs automatically (SDK generation and PRs)
+
+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.
+
+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) | 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 into main
+
+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**.
+
+### 4. SDKs are released
+
+When the SDK PRs are merged into main, the SDKs are released (published).
+
+### 5. Outpost binaries (when and where)
+
+- **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 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. **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).
+
+## 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.

contributing/sdks.md

@@ -4,12 +4,9 @@ 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 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:

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

sdks/outpost-go/.speakeasy/gen.yaml

@@ -21,7 +21,7 @@ generation:
     hoistGlobalSecurity: true
   schemas:
     allOfMergeStrategy: shallowMerge
-  requestBodyFieldName: params
+  requestBodyFieldName: body
   versioningStrategy: automatic
   persistentEdits: {}
   tests:

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

sdks/outpost-typescript/.speakeasy/gen.yaml

@@ -21,7 +21,7 @@ generation:
     hoistGlobalSecurity: true
   schemas:
     allOfMergeStrategy: shallowMerge
-  requestBodyFieldName: params
+  requestBodyFieldName: body
   versioningStrategy: automatic
   persistentEdits: {}
   tests: