[STG-2449] ci: publish browserbase/browse Docker image on browse release

[shrey150]

What

Publish the browse CLI as a Docker image to GHCR on every release, pinned 1:1 to the npm version, so code sandboxes can consume it by image reference.

• ghcr.io/browserbase/browse:<version> + :latest, pushed via the built-in GITHUB_TOKEN (no new secrets).
• Multi-arch linux/amd64,linux/arm64 (amd64 is required — sandbox runtimes are amd64).
• No browser is bundled. browse connects out to a Browserbase cloud browser over CDP, so the image stays a thin client (~481 MB on node:20-slim).

Docker Hub (browserbase/browse) is intentionally out of scope here — the browserbase Docker Hub namespace isn't ours yet, so shipping those steps would be dead code. It's tracked as a follow-up (see below).

Why

Most sandbox providers (E2B, Modal, Daytona) have no public template registry — but they can all pull a public image by reference, so one published image makes browse consumable with no Dockerfile:

# E2B / any OCI sandbox
FROM ghcr.io/browserbase/browse

# Modal
image = modal.Image.from_registry("ghcr.io/browserbase/browse")

# Daytona
daytona snapshot create browse --image ghcr.io/browserbase/browse

How it hooks in

Reuses the existing Check if browse publish is needed gate in release.yml (should_publish / version outputs) — the Docker steps run under the same condition as Publish browse to npm, right after the npm publish + tag. No new version-detection logic. Image version is pinned via --build-arg BROWSE_VERSION=<version>.

Conventions

• node:20-slim to match the repo's node 20.x standard (engines ^20.19.0 || >=22.12.0).
• Actions SHA-pinned with # vX.Y.Z comments, matching the repo's existing style.
• No WORKDIR / ENTRYPOINT — sandbox runtimes set their own working dir and exec their own commands.
• Dockerfile lives in packages/cli/ but is excluded from the npm tarball by the package's files allowlist.

Prerequisite (one-time, maintainer)

GHCR packages default to private. After the first release pushes the package, set ghcr.io/browserbase/browse visibility to Public in the org package settings so sandboxes can pull it anonymously. (Requires the release job's packages: write permission, added here.)

Follow-up (not in this PR) — STG-2449

Publish browse to Docker Hub for the clean bare-name reference (browserbase/browse, which resolves to Docker Hub by default). Blocked on claiming the namespace: the browserbase name on Docker Hub is already taken by an org with no public repos and unknown owner. Options: recover it if it's an old Browserbase registration, dispute it via Docker support (trademark), or fall back to browserbasehq. Once the namespace + a DOCKERHUB_* token exist, adding Docker Hub tags is a small follow-up.

E2E Test Matrix

Command / flow	Observed output	Confidence / sufficiency
docker buildx build --platform linux/amd64 --build-arg BROWSE_VERSION=0.9.1	image built under QEMU; browse --version → browse/0.9.1 linux-x64 node-v20.20.2; ~481 MB	Proves the mandatory sandbox arch (amd64) builds and browse runs on node:20-slim
docker build (native arm64)	image built; browse --version → browse/0.9.1 linux-arm64; browse --help renders	Proves the second published arch builds and runs
actionlint .github/workflows/release.yml	exit 0, no findings	Workflow YAML + ${{ }} expressions are valid and well-formed

Not yet exercised (requires a real release run): the live GHCR push, the should_publish gate firing on a tagged release, and GHCR org-package first-push permission.

---

Linear: STG-2449

[changeset-bot]

⚠️ No Changeset found

Latest commit: dcf2a4d

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 2 files

Confidence score: 3/5

• In .github/workflows/release.yml, Docker/GHCR publish is gated behind the npm publish retry check, so a partial failure (npm succeeds, GHCR fails) can make reruns skip the image build/push and leave a release without the expected container artifact. Decouple GHCR publishing from the npm “already published” path (or add an explicit retry path for image publish) before merging.

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/release.yml">

<violation number="1" location=".github/workflows/release.yml:168">
P2: Docker publishing is coupled to the npm publish retry gate. If the workflow fails after npm publish but before/during the GHCR push, rerunning the release will see the npm package as already published and skip building `ghcr.io/browserbase/browse:<version>`.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Git as GitHub Release (tag push)
    participant CI as Release Workflow
    participant NPM as npm Registry
    participant GHCR as GHCR (ghcr.io/browserbase/browse)
    participant Sandbox as Sandbox (E2B/Modal/Daytona)

    Note over Git,Sandbox: NEW: Publish browse Docker image on release

    Git->>CI: Trigger release.yml (tag vX.Y.Z)

    CI->>CI: Check should_publish and already_published<br/>(existing gate)

    alt should_publish == true & already_published != true
        CI->>NPM: Publish browse@vX.Y.Z (existing)
        NPM-->>CI: Success

        Note over CI: NEW: Docker image steps
        CI->>CI: Set up QEMU for multi-arch build
        CI->>CI: Set up Docker Buildx
        CI->>GHCR: Login using GITHUB_TOKEN
        CI->>CI: Build & push image (linux/amd64 + linux/arm64)
        CI->>GHCR: Push ghcr.io/browserbase/browse:vX.Y.Z
        CI->>GHCR: Push ghcr.io/browserbase/browse:latest
        GHCR-->>CI: Publish complete
    end

    Note over Sandbox: Later: Consumer pulls image
    Sandbox->>GHCR: Pull ghcr.io/browserbase/browse (version or latest)
    GHCR-->>Sandbox: Thin client image (no bundled browser)
    Sandbox->>Sandbox: Run "browse" commands (connects to Browserbase cloud CDP)

Loading

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Docker publishing is coupled to the npm publish retry gate. If the workflow fails after npm publish but before/during the GHCR push, rerunning the release will see the npm package as already published and skip building ghcr.io/browserbase/browse:<version>.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At .github/workflows/release.yml, line 168:

<comment>Docker publishing is coupled to the npm publish retry gate. If the workflow fails after npm publish but before/during the GHCR push, rerunning the release will see the npm package as already published and skip building `ghcr.io/browserbase/browse:<version>`.</comment>

<file context>
@@ -146,6 +147,37 @@ jobs:
+
+      - name: Build and push browse image to GHCR
+        if: steps.browse_cli.outputs.should_publish == 'true' && steps.browse_cli.outputs.already_published != 'true'
+        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
+        with:
+          context: packages/cli
</file context>