production-readiness.md

Production Readiness

This document describes the concrete steps required to move BrowserBox/BrowserBox-distribution from packaging exploration to a production distribution system.

It is written against the repo as it exists today:

• upstream binary source: BrowserBox/BrowserBox
• sync workflow: .github/workflows/sync-from-public-release.yaml
• Linux package build workflow: .github/workflows/build-linux-packages.yaml
• generator: scripts/sync-release.mjs
• Linux package builder: scripts/build-linux-packages.sh

What "Production" Means Here

This repo is production-ready only when all of these are true:

• package surfaces update automatically from a public BrowserBox release only after the public saga is green
• each surface installs or locates the release manifest correctly at runtime
• Linux packages are built, retained, and published from a repeatable workflow
• Windows and macOS package channels are published from a repeatable workflow
• at least smoke-install verification exists for each supported surface
• rollback to a prior tag is documented and reversible without manual archaeology
• secrets, tokens, and publication permissions are scoped narrowly and documented

Current State

What is already in place:

• The repo tracks the newest BrowserBox/BrowserBox release whose public saga succeeded.
• Linux deb and rpm packages can be built as workflow artifacts.
• Homebrew, Chocolatey, and Nix package surfaces are generated from upstream release metadata.
• Runtime release-manifest handling is wired into all current package surfaces.

What is not yet in place:

• no immediate upstream-to-downstream dispatch from the public saga
• no publication workflow for deb / rpm repositories
• no dedicated Homebrew tap publication flow
• no Chocolatey feed publication flow
• no Winget publication flow in this repo
• no install CI for package-manager surfaces
• no rollback or release-ops runbook

Phase 1: Close The Automation Gap

Goal: make repo updates deterministic and low-latency.

1. Add upstream dispatch from BrowserBox/BrowserBox. The sender should be the public saga workflow after success, not the release-publish step. Use repository_dispatch with payload { tag, source_repo, source_workflow }.

2. Add a narrowly scoped token in the upstream repo. Required capability: trigger workflows or write repository_dispatch events on BrowserBox/BrowserBox-distribution only. Do not reuse a broad org-wide PAT.

3. Keep schedule polling as fallback. The hourly schedule is still useful if dispatch breaks or the upstream workflow is temporarily edited.

4. Broaden success detection in scripts/sync-release.mjs. Today it looks only at release-event saga runs. Before production it should also recognize explicit successful reruns or accept the dispatch payload as authoritative.

5. Add generator parity protection. Add a workflow step that runs node ./scripts/sync-release.mjs and fails if generated files differ from checked-in files.

Phase 2: Finalize Supported Package Surfaces

Goal: define what is actually supported and remove ambiguity.

Linux

1. Pick the publication model for apt and dnf. Options:

   • publish signed deb and rpm repos from GitHub Pages or another static host
   • publish via a managed package repository service
   • keep GitHub artifact-only for internal use

2. Add repository metadata generation. For production, package files alone are not enough. You need:

   • Debian repo metadata and signing
   • RPM repo metadata and signing

3. Decide the supported distributions. Minimum recommended explicit support list:

   • Ubuntu LTS
   • Debian stable
   • Rocky or RHEL-compatible
   • Fedora or another dnf family target

4. Add install instructions for repository bootstrap. Document:

   • repo URL
   • signing key install
   • package install command
   • how to pass BROWSERBOX_HOSTNAME and BROWSERBOX_EMAIL when desired

macOS

1. Decide whether this repo remains the cask source or whether Homebrew gets a dedicated tap repo. A dedicated tap is usually cleaner operationally.

2. Move from cask file generation only to tap publication. Production requires a repeatable push to the tap branch/repo.

3. Revisit manifest delivery. Current behavior downloads the manifest in postflight. For production, consider shipping a tarball or installer artifact that already contains:

   • the binary
   • release.manifest.json
   • release.manifest.json.sig

4. Keep macOS signing aligned with upstream binary release policy. If upstream macOS binaries are notarized or otherwise signed, this repo should not introduce a second unsigned wrapper artifact.

Windows

1. Choose the supported Windows channels. Recommended production target:

   • Chocolatey
   • Winget

2. Import the existing Winget scaffolding from BrowserBox-source. Reuse the existing manifests under BrowserBox-source/spread-channels/packages/winget instead of inventing a second Winget shape.

3. Decide the Chocolatey publication target. Options:

   • private/internal feed
   • Chocolatey Community repository

4. If Winget is in scope, automate manifest updates and submission packaging. The repo should own the generated Winget manifests and the submission/runbook.

5. Keep manifest placement consistent with BrowserBox runtime lookup. Preferred order remains:

   • global location
   • user-config fallback

Nix

1. Decide whether the production target is:

   • this repo as a flake input
   • an overlay exported from this repo
   • a submission path into another Nix package set

2. Add a basic nix build validation workflow.

3. Document the unfree policy clearly. Nix users need to know they are opting into unfree redistributable software.

Phase 3: Add Minimal Install Verification

The repo intentionally skipped install CI at the exploration stage. That is no longer acceptable in production.

Before calling this production, add at least one smoke test per surface:

• Linux deb: install package on an Ubuntu runner/container and verify browserbox --version
• Linux rpm: install package on a Rocky or Fedora runner/container and verify browserbox --version
• Homebrew: install the cask on a macOS runner and verify:
  • browserbox exists
  • release manifest files were placed correctly
• Chocolatey: install on a Windows runner and verify:
  • browserbox.exe exists
  • release manifest files were placed correctly
• Nix: nix build and verify the wrapped binary exposes BBX_RELEASE_MANIFEST_PATH

The tests do not need to perform a full BrowserBox session claim or license flow at first. The first production gate is: package install succeeds and the binary can start its integrity path without missing-manifest failure.

Phase 4: Publish Artifacts, Not Just Metadata

Production needs immutable outputs.

1. Publish Linux packages somewhere durable. The current workflow only uploads GitHub Actions artifacts. Those are not a production distribution channel.

2. Add release attachment strategy for this repo. Recommended shape:

   • one tag in this repo per synced BrowserBox tag
   • attach built deb / rpm files there
   • attach repo metadata if using static hosting

3. Publish tap/feed updates transactionally. Avoid a state where:

   • package metadata points to one BrowserBox tag
   • but the package files were not published yet

4. Keep the source of truth monotonic. packages/release/current-release.json should always match the published package content.

Phase 5: Define Rollback And Operators' Runbook

Production means failure recovery is routine, not improvised.

Document all of this in the repo:

1. How to pin this repo back to a previous BrowserBox tag.

2. How to republish only one surface if a single ecosystem fails. Examples:

   • rebuild only Linux packages
   • republish only the Homebrew cask
   • rerun only Chocolatey publication

3. How to stop auto-advance temporarily. Recommended mechanism:

   • disable the dispatch sender upstream, or
   • disable the schedule in this repo, or
   • pin workflow_dispatch to a chosen tag during incident handling

4. How to inspect whether a repo version is safe to publish. Minimum checks:

   • target tag in packages/release/current-release.json
   • successful upstream public saga
   • generated package surfaces committed
   • package publication workflow green

Phase 6: Security And Provenance

Do not treat package publication as a pure metadata problem.

Before production:

1. Scope all tokens narrowly. Separate:

   • upstream dispatch token
   • publication tokens per ecosystem
   • any package repository signing keys

2. Decide where Linux repository signing keys live and who rotates them.

3. Preserve upstream checksum authority. Package generation must continue deriving release artifact checksums from the upstream BrowserBox release assets, not from ad hoc local files.

4. Avoid introducing a second opaque installer authority unless necessary. If you add platform-native installer bundles later, document why they exist and how they preserve manifest integrity.

Recommended Implementation Order

If you want the shortest path from current state to something operational, do it in this order:

1. Upstream saga dispatch into this repo
2. Success detection that handles dispatch and reruns cleanly
3. Linux package publication and repository metadata
4. Winget surface import and publication plan
5. Homebrew tap publication
6. Chocolatey feed publication
7. Minimal smoke-install CI across all supported surfaces
8. Rollback runbook and incident handling doc

Open Decisions

These decisions should be made explicitly before production work starts:

• Does this repo publish only Linux packages, while macOS and Windows publish metadata to external channels?
• Is Winget in scope for production, or is Chocolatey the only Windows package-manager surface?
• Does Homebrew stay in this repo or move to a dedicated tap repo?
• Are Linux repos hosted statically, through GitHub releases/pages, or through a managed package repository?
• Is the first production milestone "internal feed only" or "public ecosystem publication"?

Definition Of Done

This repo is ready to be called production when:

• a green public BrowserBox saga causes this repo to update automatically without manual polling
• package outputs are published through stable channels, not just workflow artifacts
• each supported surface has at least one smoke-install verification path
• rollback is documented and exercised once
• secrets, signing, and operator ownership are documented in-repo