ci(release): add stable Python SDK release PR flow (#451)

AbhiPrasad · web-flow · commit d9e0737b6d33 · 2026-05-21T10:49:18.000-04:00
resolves https://linear.app/braintrustdata/issue/BT-5169/set-up-publish-workflow-environment-rules-for-python-sdk Add a GitHub Actions driven stable release path that creates a version-bump PR from the Prepare Stable Python SDK Release workflow. Merging the release/py-sdk-v<version> PR now triggers Publish Python SDK directly, so tagging and publishing live in one release workflow instead of a separate tag workflow. Gate only stable, non-dry-run PyPI publishes with the pypi-publish environment so the job that calls trusted publishing receives the protected environment context. After approval, the publish workflow builds, publishes to PyPI, and creates the py-sdk-v<version> GitHub Release tag and release. Prereleases continue to use the manual Publish Python SDK workflow without environment approval or a committed version bump; the requested prerelease version is supplied as a workflow input and applied as a build override. Update the release validator and docs for the new process.
diff --git a/.github/workflows/prepare-release.yml b/.github/workflows/prepare-release.yml
@@ -0,0 +1,66 @@
+# Starts the stable Python SDK release process by opening a PR that bumps the
+# package version. Merge the PR to trigger the approval-gated publish workflow.
+name: Prepare Stable Python SDK Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Stable version to release (e.g., 0.22.0)"
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  prepare:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+
+      - name: Validate version format
+        run: python py/scripts/validate-release.py stable --version "${{ inputs.version }}" --validate-version-only
+
+      - name: Generate app token
+        id: app-token
+        uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
+        with:
+          app-id: ${{ secrets.BRAINTRUST_BOT_APP_ID }}
+          private-key: ${{ secrets.BRAINTRUST_BOT_PRIVATE_KEY }}
+
+      - name: Bump version
+        run: python py/scripts/validate-release.py stable --version "${{ inputs.version }}" --set-version
+
+      - name: Compute changeset link
+        id: changeset
+        env:
+          VERSION: ${{ inputs.version }}
+          REPO_URL: ${{ github.server_url }}/${{ github.repository }}
+        run: |
+          LAST_TAG=$(git tag --sort=-version:refname 'py-sdk-v*' | head -n 1 || true)
+          if [[ -n "$LAST_TAG" ]]; then
+            URL="${REPO_URL}/compare/${LAST_TAG}...release/py-sdk-v${VERSION}"
+            echo "body=Changeset since [\`${LAST_TAG}\`](${REPO_URL}/releases/tag/${LAST_TAG}): ${URL}" >> "$GITHUB_OUTPUT"
+          else
+            URL="${REPO_URL}/commits/release/py-sdk-v${VERSION}"
+            echo "body=Changeset: ${URL}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create pull request
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          add-paths: py/src/braintrust/version.py
+          branch: release/py-sdk-v${{ inputs.version }}
+          commit-message: "chore: release Python SDK v${{ inputs.version }}"
+          title: "chore: release Python SDK v${{ inputs.version }}"
+          body: |
+            Automated stable Python SDK release PR for `${{ inputs.version }}`. Merging will trigger approval-gated publishing and create the `py-sdk-v${{ inputs.version }}` release tag.
+
+            ${{ steps.changeset.outputs.body }}
diff --git a/.github/workflows/publish-py-sdk.yaml b/.github/workflows/publish-py-sdk.yaml
@@ -1,6 +1,12 @@
 name: Publish Python SDK
 
 on:
+  pull_request:
+    types: [closed]
+    branches: [main]
+  push:
+    tags:
+      - "py-sdk-v*"
   workflow_dispatch:
     inputs:
       ref:
@@ -15,7 +21,12 @@ on:
         options:
           - stable
           - prerelease
+          - auto
         default: stable
+      version:
+        description: "Version to publish for prereleases (e.g. 0.22.0rc1). Stable releases read version.py."
+        required: false
+        type: string
       dry_run:
         description: "Validate and build without publishing to PyPI or creating a GitHub Release"
         required: true
@@ -24,6 +35,7 @@ on:
 
 jobs:
   validate:
+    if: github.event_name != 'pull_request' || (github.event.pull_request.merged == true && startsWith(github.event.pull_request.head.ref, 'release/py-sdk-v'))
     runs-on: ubuntu-latest
     timeout-minutes: 10
     outputs:
@@ -35,7 +47,7 @@ jobs:
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
-          ref: ${{ github.event.inputs.ref }}
+          ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.merge_commit_sha || (github.event_name == 'workflow_dispatch' && github.event.inputs.ref || github.ref) }}
           fetch-depth: 0
       - name: Set up mise
         uses: jdx/mise-action@1648a7812b9aeae629881980618f079932869151 # v4.0.1
@@ -45,13 +57,98 @@ jobs:
       - name: Validate release inputs
         id: validate
         run: |
-          mise exec -- python py/scripts/validate-release.py \
-            "${{ github.event.inputs.release_type }}" \
-            --github-output "$GITHUB_OUTPUT"
-          echo "dry_run=${{ github.event.inputs.dry_run }}" >> "$GITHUB_OUTPUT"
+          VALIDATE_ARGS=("${{ github.event_name == 'workflow_dispatch' && github.event.inputs.release_type || 'auto' }}" --github-output "$GITHUB_OUTPUT")
+          VERSION_INPUT="${{ github.event_name == 'workflow_dispatch' && github.event.inputs.version || '' }}"
+          if [[ -n "$VERSION_INPUT" ]]; then
+            VALIDATE_ARGS+=(--version "$VERSION_INPUT")
+          fi
+          if [[ "${{ github.event_name }}" == "push" ]]; then
+            VALIDATE_ARGS+=(--allow-existing-tag)
+          fi
+          mise exec -- python py/scripts/validate-release.py "${VALIDATE_ARGS[@]}"
+          echo "dry_run=${{ github.event_name == 'workflow_dispatch' && github.event.inputs.dry_run || 'false' }}" >> "$GITHUB_OUTPUT"
+
+  build-and-publish-stable:
+    needs: validate
+    if: needs.validate.outputs.release_type == 'stable' && needs.validate.outputs.dry_run != 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: write
+      id-token: write # Required for PyPI trusted publishing
+    environment: pypi-publish
+
+    env:
+      COMMIT_SHA: ${{ needs.validate.outputs.commit_sha }}
+      DRY_RUN: ${{ needs.validate.outputs.dry_run }}
+      RELEASE_TAG: ${{ needs.validate.outputs.release_tag }}
+      RELEASE_TYPE: ${{ needs.validate.outputs.release_type }}
+      VERSION: ${{ needs.validate.outputs.version }}
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          ref: ${{ env.COMMIT_SHA }}
+          fetch-depth: 0
+      - name: Set up mise
+        uses: jdx/mise-action@1648a7812b9aeae629881980618f079932869151 # v4.0.1
+        with:
+          cache: true
+          experimental: true
+      - name: Build and verify
+        env:
+          BRAINTRUST_RELEASE_CHANNEL: ${{ env.RELEASE_TYPE }}
+          BRAINTRUST_VERSION_OVERRIDE: ${{ env.VERSION }}
+        run: |
+          mise exec -- make -C py install-dev verify-build
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: python-sdk-dist
+          path: py/dist/
+          retention-days: 5
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # release/v1
+        with:
+          packages-dir: py/dist/
+
+      - name: Create local release tag
+        run: |
+          if ! git rev-parse "$RELEASE_TAG" >/dev/null 2>&1; then
+            git tag "$RELEASE_TAG" "$COMMIT_SHA"
+          fi
+
+      # Create GitHub Release
+      - name: Generate release notes
+        id: release_notes
+        run: |
+          RELEASE_NOTES=$(.github/scripts/generate-release-notes.sh "${{ env.RELEASE_TAG }}" "py/")
+          echo "notes<<EOF" >> $GITHUB_OUTPUT
+          echo "$RELEASE_NOTES" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+          echo "release_name=Python SDK v${VERSION}" >> $GITHUB_OUTPUT
+
+      - name: Create GitHub Release
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          RELEASE_NOTES: ${{ steps.release_notes.outputs.notes }}
+          RELEASE_NAME: ${{ steps.release_notes.outputs.release_name }}
+        with:
+          script: |
+            await github.rest.repos.createRelease({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              tag_name: process.env.RELEASE_TAG,
+              target_commitish: process.env.COMMIT_SHA,
+              name: process.env.RELEASE_NAME,
+              body: process.env.RELEASE_NOTES,
+              draft: false,
+              prerelease: false
+            });
 
   build-and-publish:
     needs: validate
+    if: needs.validate.result == 'success' && (needs.validate.outputs.release_type != 'stable' || needs.validate.outputs.dry_run == 'true')
     runs-on: ubuntu-latest
     timeout-minutes: 20
     permissions:
@@ -76,6 +173,9 @@ jobs:
           cache: true
           experimental: true
       - name: Build and verify
+        env:
+          BRAINTRUST_RELEASE_CHANNEL: ${{ env.RELEASE_TYPE }}
+          BRAINTRUST_VERSION_OVERRIDE: ${{ env.VERSION }}
         run: |
           mise exec -- make -C py install-dev verify-build
       - name: Upload build artifacts
@@ -91,7 +191,10 @@ jobs:
           packages-dir: py/dist/
 
       - name: Create local release tag
-        run: git tag "$RELEASE_TAG" "$COMMIT_SHA"
+        run: |
+          if ! git rev-parse "$RELEASE_TAG" >/dev/null 2>&1; then
+            git tag "$RELEASE_TAG" "$COMMIT_SHA"
+          fi
 
       # Create GitHub Release
       - name: Generate release notes
@@ -128,8 +231,8 @@ jobs:
           echo "Dry run completed for $RELEASE_TAG from $COMMIT_SHA"
 
   notify-success:
-    needs: [validate, build-and-publish]
-    if: always() && needs.build-and-publish.result == 'success'
+    needs: [validate, build-and-publish-stable, build-and-publish]
+    if: always() && (needs.build-and-publish-stable.result == 'success' || needs.build-and-publish.result == 'success')
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
@@ -149,11 +252,11 @@ jobs:
               - type: "section"
                 text:
                   type: "mrkdwn"
-                  text: "${{ needs.validate.outputs.dry_run == 'true' && format('*Mode:* dry run\n*Release type:* {0}\n*Version:* {1}\n*Ref:* {2}\n\n<{3}/{4}/actions/runs/{5}|View Run>', needs.validate.outputs.release_type, needs.validate.outputs.version, github.event.inputs.ref, github.server_url, github.repository, github.run_id) || format('*Release type:* {0}\n*Version:* {1}\n*Package:* <https://pypi.org/project/braintrust/|braintrust>\n\n<{2}/{3}/actions/runs/{4}|View Run>', needs.validate.outputs.release_type, needs.validate.outputs.version, github.server_url, github.repository, github.run_id) }}"
+                  text: "${{ needs.validate.outputs.dry_run == 'true' && format('*Mode:* dry run\n*Release type:* {0}\n*Version:* {1}\n*Ref:* {2}\n\n<{3}/{4}/actions/runs/{5}|View Run>', needs.validate.outputs.release_type, needs.validate.outputs.version, github.event_name == 'workflow_dispatch' && github.event.inputs.ref || github.ref_name, github.server_url, github.repository, github.run_id) || format('*Release type:* {0}\n*Version:* {1}\n*Package:* <https://pypi.org/project/braintrust/|braintrust>\n\n<{2}/{3}/actions/runs/{4}|View Run>', needs.validate.outputs.release_type, needs.validate.outputs.version, github.server_url, github.repository, github.run_id) }}"
 
   notify-failure:
-    needs: [validate, build-and-publish]
-    if: always() && (needs.validate.result == 'failure' || needs.build-and-publish.result == 'failure')
+    needs: [validate, build-and-publish-stable, build-and-publish]
+    if: always() && (needs.validate.result == 'failure' || needs.build-and-publish-stable.result == 'failure' || needs.build-and-publish.result == 'failure')
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
@@ -173,4 +276,4 @@ jobs:
               - type: "section"
                 text:
                   type: "mrkdwn"
-                  text: "*Release type:* ${{ github.event.inputs.release_type }}\n*Ref:* ${{ github.event.inputs.ref }}\n*Commit:* ${{ needs.validate.outputs.commit_sha || github.sha }}\n\n<${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|View Run>"
+                  text: "*Release type:* ${{ needs.validate.outputs.release_type || (github.event_name == 'workflow_dispatch' && github.event.inputs.release_type || 'auto') }}\n*Ref:* ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.ref || github.ref_name }}\n*Commit:* ${{ needs.validate.outputs.commit_sha || github.sha }}\n\n<${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|View Run>"
diff --git a/AGENTS.md b/AGENTS.md
@@ -287,6 +287,21 @@ Caveat:
 
 Avoid editing `py/src/braintrust/version.py` while also running build commands.
 
+## Publishing Notes
+
+See `docs/publishing.md` for the full release playbook.
+
+Stable Python SDK releases:
+
+1. Run the `Prepare Stable Python SDK Release` workflow with a stable `X.Y.Z` version.
+2. Review and merge the generated `release/py-sdk-v<version>` PR.
+3. The merge triggers `Publish Python SDK`; the actual PyPI publish job is gated by the `pypi-publish` GitHub environment.
+4. After approval, the workflow publishes to PyPI and creates the `py-sdk-v<version>` GitHub Release tag and release.
+
+Prereleases stay on the manual `Publish Python SDK` path, but do not require a committed version bump: run the workflow against `main` or a commit on `main` with `release_type=prerelease` and the `version` input set to `X.Y.Zrc1`, `X.Y.Za1`, or `X.Y.Zb1`. Prereleases are not gated by the `pypi-publish` environment.
+
+Do not create or push release tags locally.
+
 ## Dependency Pinning
 
 All nox session dependency pins are centralized in `py/pyproject.toml`:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -250,11 +250,22 @@ Main workflows:
 - `checks.yaml`: merged SDK checks workflow, including lint, pinned-action validation, the Python test matrix, wheel build, and the `checks-passed` required-check aggregator
 - `langchain-py-test.yaml`: LangChain integration tests
 - `adk-py-test.yaml`: ADK integration tests
-- `publish-py-sdk.yaml`: PyPI release
+- `prepare-release.yml`: stable Python SDK version-bump PR creation
+- `publish-py-sdk.yaml`: PyPI release, including stable release PR merges
 - `test-publish-py-sdk.yaml`: TestPyPI release validation
 
 CI uses committed HTTP VCR cassettes and Claude Agent SDK subprocess cassettes, so forks do not need provider API secrets for normal replayed test runs.
 
+## Publishing
+
+See `docs/publishing.md` for the full Python SDK publishing playbook.
+
+Stable releases are started from GitHub Actions by running `Prepare Stable Python SDK Release` with a stable version such as `0.22.0`. That workflow opens a `release/py-sdk-v<version>` PR that updates `py/src/braintrust/version.py`. Merging the PR triggers `Publish Python SDK`. The stable PyPI publish job requires approval through the `pypi-publish` GitHub environment, then publishes to PyPI and creates the `py-sdk-v<version>` GitHub Release tag and release.
+
+Prereleases use the manual `Publish Python SDK` workflow without a committed version bump: run the workflow against `main` or a commit on `main` with `release_type=prerelease` and the `version` input set to a prerelease version such as `0.22.0rc1`. Prereleases are not gated by the `pypi-publish` environment.
+
+Do not create or push release tags locally.
+
 ## Submitting Changes
 
 1. Make your change in the narrowest relevant area.
diff --git a/docs/publishing.md b/docs/publishing.md
diff --git a/py/scripts/validate-release.py b/py/scripts/validate-release.py
