Add stable v4 release automation

[monadoid]

Now that the v4 package names and versions are established, this PR adds the stable release flow for the TypeScript and Python SDKs.

• just changeset records the release intent for a pull request.
• just _version is used by CI to apply those changes, keep the Python version in sync, and update the root changelog.
• Changesets maintains the release pull request on main.
• Merging that release pull request publishes the TypeScript SDK to npm and the Python SDK to PyPI.

The private protocol package is also versioned through Changesets because its major version is the compatibility contract between the SDK and extension, but it is not published to npm.

We keep one root CHANGELOG.md for the repository, beginning with the existing v3 history. The release workflows only run from main, so this stack cannot publish anything.

---

Summary by cubic

Adds stable v4 release automation for the TypeScript and Python SDKs. On pushes to main, we open a release PR or publish TS to npm, and publish Python to PyPI only when a new version is needed (skips if pending Changesets exist).

• New Features

  • Adopted changesets for @browserbasehq/stagehand, @browserbasehq/stagehand-python, and versioned private @browserbasehq/stagehand-protocol (not published).
  • Release workflow on main: runs just check/just build, opens a release PR via changesets/action, publishes TS via just _publish-typescript, then uses a status check to publish Python only if PyPI is missing the version and no Changesets are pending.
  • Reusable Python workflow: builds wheels/sdists, smoke-tests with uv, uses trusted publishing, and tags stagehand-python@<version>.
  • Consolidated SDK changelogs into the root CHANGELOG.md with SDK-labeled headings; package changelogs are temporary and removed in CI.
  • Added release scripts and just tasks to validate Changesets (allowed packages only), consolidate changelogs, sync Python version from the proxy package.json, verify uv.lock, gate Python publishing on PyPI status, and clean stale dist/ artifacts (including legacy names).
  • Documented the release flow and contributor steps in README.md.

• Migration

  • When a PR changes a public SDK or the protocol contract, run just changeset. Internal-only changes don’t need one.
  • Merge the release PR on main to publish TypeScript; Python auto-publishes if the synchronized version is not on PyPI. Release jobs run only on main.

^{Written for commit 7fe4b8e. Summary will update on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 7fe4b8e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[cubic-dev-ai]

1 issue found across 17 files

Confidence score: 2/5

• In .github/workflows/publish-python.yaml, the workflow_dispatch path can publish stagehand and create release tags from non-main branches, which bypasses the intended Release + python-release-status gate and could ship unreviewed artifacts to PyPI — remove manual dispatch for publish/tagging or enforce the same main-only and status-check protections on that path.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".github/workflows/publish-python.yaml">

<violation number="1" location=".github/workflows/publish-python.yaml:5">
P1: Manual dispatch can publish `stagehand` and create a release tag from a selected branch, bypassing the main-only Release trigger and `python-release-status` PyPI/Changeset gate. Remove this trigger or apply equivalent ref and release-status checks before publishing.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Dev as Developer
    participant PR as Pull Request
    participant CI as CI (Main Branch)
    participant Changesets as Changesets Bot
    participant NPM as npm Registry
    participant PyPI as PyPI Registry
    participant GH as GitHub Releases

    Note over Dev,GH: Release Automation Flow

    Dev->>PR: Makes changes to public SDK or protocol
    Dev->>Dev: Runs `just changeset` to record release intent
    PR->>CI: Merges to main branch
    CI->>CI: Triggers Release workflow (just check, just build)

    CI->>Changesets: Runs changesets/action
    alt Changesets detects pending version bumps
        Changesets->>CI: Creates/updates Release PR on main
        CI->>CI: Runs `just _version` (consolidate changelogs, sync Python version, update uv.lock)
        CI->>GH: Tags release commit (stagehand-python@<version>)
        Changesets-->>CI: Release PR ready for merge
    else Standard push (no pending changesets)
        Changesets->>CI: No release PR needed
        Note over CI: Falls through to Python publish check
    end

    alt Release PR merged
        CI->>CI: Runs `just _publish-typescript`
        CI->>NPM: publish @browserbasehq/stagehand
        NPM-->>CI: Published

        CI->>CI: Check Python release status
        CI->>PyPI: GET /pypi/stagehand/<version>/json
        alt Version not on PyPI (404)
            PyPI-->>CI: Not found
            CI->>CI: should-publish = true
            CI->>PyPI: Publish via publish-python.yaml (uv publish, trusted publishing)
            PyPI-->>CI: Published
            CI->>GH: Tag stagehand-python@<version>
        else Version already on PyPI (200)
            PyPI-->>CI: Exists
            CI->>CI: should-publish = false, skip Python publish
        end
    end

    Note over CI,GH: Private protocol package is versioned internally but not published

    Note over Dev,GH: Validation (on every `just check`)
    Dev->>Dev: Runs check-changesets.ts (validates allowed packages only)
    Dev->>Dev: Runs consolidate-changelogs.ts --check (ensures no stale package changelogs)
    Dev->>Dev: Runs sync-python-version.ts --check (pyproject.toml and uv.lock match proxy package.json)

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​changesets/​parse@​0.4.3

View full report