Skip to content

release.md

Latest commit

 

History

History
89 lines (60 loc) · 7.12 KB

release.md

File metadata and controls

89 lines (60 loc) · 7.12 KB
Raw

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.

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 builds Outpost binaries and Docker images; sdk-generate-on-release-dispatch.yml dispatches sdk-generate-on-release.yml at that tag so the SDKs match the release commit, while PRs still target 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: 
    git tag v0.13.2
git push origin v0.13.2
    Use Semantic Versioning: 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 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 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-dispatch.yml → sdk-generate-on-release.yml Dispatch runs the Speakeasy workflow at the release tag (same tree as the tag). A vendored Speakeasy executor forces PRs against main. Generates the Go, Python, and TypeScript SDKs sequentially and opens three pull requests (one per SDK). Sequential runs avoid conflicts on the shared .speakeasy/workflow.lock (see SDKs – SDK generation and lock files).

3. Merge the SDK PRs into main

Review and merge the three pull requests (Go, Python, TypeScript) opened by the SDK generate workflows. Merge order does not matter. See 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 runs and uses GoReleaser to build the binaries (e.g. outpost, outpost-server 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 (Outpost binaries + Docker) and the SDK generate workflows (sdk-generate-on-release-dispatch.yml → 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 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.

Testing the tag-triggered SDK workflow

To verify that the SDK release workflows (sdk-generate-on-release-dispatch.yml / sdk-generate-on-release.yml) work 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):

    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, you should see SDK generate on release tag — dispatch (quick) then SDK generate on release tag with all three jobs (generate-go, generate-python, generate-ts) in order and PRs opened against main.
    • To remove the tag after testing (optional): 
      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 (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
    Go to Actions → SDK generate on release tag, click Run workflow. Under Use workflow from, select the same tag you enter in release_tag (e.g. tag v0.0.0-sdk-gen-test and input v0.0.0-sdk-gen-test). The first job fails fast if the ref and input disagree. Note: the workflow sets all SDKs to 1.0.0 only when release_tag is exactly v1.0.0; otherwise Speakeasy detection applies.