goodbuddy/docs/development/release-runbook.md

GoodBuddy Release Runbook

Read this runbook only when preparing, publishing, recovering, or verifying a desktop or GoodBuddy Agent release.

This is an operator and CI procedure. It does not authorize adding application persistence, snapshots, journals, rollback engines, recovery protocols, or compatibility layers to automate release operations. Determine release recovery from the authoritative GitHub, OSS, workflow, and Git state, then use the smallest existing idempotent rerun or a new immutable version as specified below.

Release Packaging

• Unless the user explicitly requests a local Windows package, never run local Windows packaging or launch probes as part of release preparation. In particular, do not run npm run portable, Windows npm run release:package, direct electron-builder packaging, or launch a locally packaged Windows app before publishing a release. Source validation and the native GitHub Actions jobs are the release authorities.
• After a release is published, confirm only that the expected Windows assets exist in the public release metadata. Do not locally rebuild or launch the Windows package, download or hash published installers, attach browser automation to a packaged app, or perform exhaustive per-asset network probes unless the user explicitly asks for that additional validation.
• .github/workflows/packages.yml is the canonical cross-platform packaging workflow. It validates and builds out once, then packages on six native runners: Windows, macOS, and Linux, each for x64 and arm64.
• The experimental Linux LoongArch (loong64) preview is built separately through build/loongarch-cross by following docs/development/loongarch-preview-build.md. It is not part of .github/workflows/packages.yml, the six-runner GitHub Actions matrix, standard release manifests, GitHub Release asset expectations, or the production update index. Do not add it to those paths unless the user explicitly requests a future production-support migration.
• Run the unified packager with npm run release:package -- --platform <platform> --arch <arch>. It only packages for the native host and writes to dist/release/<platform>-<arch>.
• Default deliverables are NSIS and portable ZIP for Windows, DMG and ZIP for macOS, and AppImage, DEB, and RPM for Linux. Every target includes release-manifest.json with SHA-256 hashes.
• build/build-release.cjs verifies the unpacked application, app.asar, bundled Continue and OpenCode runtimes, executable architecture, and package signatures before atomically replacing a release directory.
• All desktop build paths, including local portable, package the Agent and remote Runtime version locks plus the public signing-key registry without embedding installable Linux Agent or remote Runtime payloads. Managed SSH is optional: users explicitly download a compatible compound .gbagent package from Settings or import one offline before GoodBuddy can install or update a Host.
• Each independently published Linux x64 or arm64 .gbagent contains the Agent daemon, pinned Node, and the desktop-maintained compatible OpenCode Runtime. Build both architectures on native GitHub Actions runners from one immutable agent-v<agentVersion> tag.
• Keep the GoodBuddy Agent source, shared protocol/contracts, runtime lock, bundle tooling, and tests in this repository so a desktop commit identifies the exact Agent source it expects. Do not create a separate Agent repository or long-lived Agent release branch unless the Agent becomes an independently released product serving multiple clients.
• .github/workflows/agents.yml is the branch and pull-request build verification workflow for GoodBuddy Agent. It must build Linux x64 and arm64 on native runners from the checked-out commit, acquire the locked official Node archive and locked OpenCode npm archive, verify every locked digest, use only an ephemeral in-memory test signing identity, and verify the resulting compound package and deterministic archive. It must not read production signing secrets, publish installable release artifacts, or modify the checked-in public key registry.
• .github/workflows/agent-release.yml is the only production compound Agent publication path. It requires an annotated immutable Agent tag, the protected agent-signing Environment, native x64/arm64 builds, one production GoodBuddy signing identity for every layer of the compound package and catalog, a non-Latest GitHub Agent Release, and synchronized immutable Beijing OSS objects plus the final signed latest-catalog pointer.
• .github/workflows/packages.yml and release:package build only desktop products. Missing Agent packages, remote Runtime inputs, or GoodBuddy signing credentials must never block an ordinary desktop package or release.
• Keep electron-builder invocations on --publish never. Main-branch builds run validation and build the production bundle without running the native package matrix. Manual builds upload 30-day GitHub Actions artifacts. Version-tag builds verify and aggregate packages before publishing GitHub Release assets. The macOS jobs sign, notarize, and verify packages when all five Apple credentials are configured. With no Apple credentials they must use the explicit --unsigned path, warn that Gatekeeper may block the packages, and still complete; a partial credential set must fail rather than silently downgrade.
• Keep ELECTRON_CACHE and ELECTRON_BUILDER_CACHE under ${{ runner.temp }} in step-level workflow contexts. A cache beneath the repository inherits the root "type": "module" and breaks electron-builder's CommonJS macOS icon tool.
• Tag builds must use v${package.version}. The workflow also supports manual dispatch and main-branch changes to release tooling.

Agent Release Process

• Agent releases use annotated agent-v${agent-runtime-lock.agentVersion} tags and are separate from desktop v${package.version} releases. Confirm the exact Agent release commit and tag with the user before creating or pushing either.
• The tagged commit must be reachable from protected main. The two native jobs build the compound x64/arm64 packages from the same source and locks; the catalog job rejects missing architectures, changed bytes for an existing version/architecture identity, invalid prior signatures, and incompatible matrix metadata.
• Agent GitHub Releases are ordinary non-draft, non-prerelease releases but must use --latest=false; they must never replace the desktop release marked Latest. Publish immutable packages and the versioned catalog to agent-releases/v<agentVersion>/ in Beijing OSS, publish the GitHub Agent Release, then atomically update the single agent-releases/latest.json pointer to that version's immutable catalog and signature.
• Do not report an Agent release complete until both public package architectures match the signed catalog by size and SHA-256, the GitHub and OSS catalog bytes/signatures are identical, the application can read the selected source, and GitHub's repository Latest tag remains the desktop tag.

Tagged Release Process

Every version-tag release must follow this sequence. A branch-only push does not require release notes.

1. Confirm that the user wants a release tag and identify the exact release commit and the new package.json version. Separately ask whether this release should also receive an experimental LoongArch preview build; never infer that choice from an earlier release.
2. Find the latest stable version tag reachable before the release commit and inspect the complete commit and file diff from that tag to the release commit. For the first tagged release, inspect the relevant repository history instead.
3. Draft concise, user-facing release notes in both Simplified Chinese and English based only on verified changes in that range. Use the titles GoodBuddy <version> 更新内容 and What's New in GoodBuddy <version>, with corresponding 功能更新 / Features and 问题修复 / Bug Fixes sections when applicable. The two language versions must describe the same changes. Do not expose internal-only details, credentials, private content, or unverified claims.
4. Show the exact bilingual release-note draft to the user and wait for explicit approval. If the release commit or either language version changes after approval, inspect the updated tag range and request approval again.
5. Write the approved notes to the single entry for the release version in resources/release-notes.json. A failed unpublished candidate whose content is carried forward must not retain a duplicate packaged entry.
6. Verify that package.json, the root package-lock.json version, and package-lock.json.packages[""].version all equal the release version. Run npm run release:notes:verify, the required source validators, the production build. The six native CI jobs remain the cross-platform authority; do not add local packaging or packaged-app launch probes unless the user explicitly requests them. If the user requested a LoongArch preview in step 1, build it separately from this exact candidate by following the LoongArch build document, record its size and SHA-256, and keep it outside the standard GitHub/OSS release asset set unless the user separately authorizes publishing it.
7. Fetch both remotes immediately before tagging. Inspect any remote branch movement instead of overwriting or silently merging it. Confirm the working tree is clean, the candidate tag is unused locally and remotely, and the exact approved commit has not changed.
8. Only after all previous steps pass, create an annotated v${package.version} tag at the exact approved commit. Push main to origin and github, verify both branch SHAs, then push the tag to both remotes and verify each peeled tag SHA (refs/tags/<tag>^{}) equals the release commit.
9. Keep both approved language versions as the single source for the GitHub Release body and the packaged first-open release-notes modal. The modal displays the release notes matching the current interface language and contains no button linking to a full release page.
10. Observe the tag workflow through publication and complete the public verification checklist below. A successful push is not a completed release.

OSS Publication Contract

The tagged release job publishes through the GitHub Environment selected by .github/workflows/packages.yml (aliyun-oss-release) and reads the following effective GitHub Actions variables. Before a release or same-tag rerun can publish, verify that repository-, organization-, or environment-level resolution exposes:

• ALIYUN_OSS_BUCKET=goodbuddy
• ALIYUN_OSS_ENDPOINT=https://oss-cn-beijing.aliyuncs.com
• a non-empty ALIYUN_OIDC_PROVIDER_ARN matching acs:ram::*:oidc-provider/*
• a non-empty ALIYUN_ROLE_ARN matching acs:ram::*:role/*

For environment-scoped values, use the exact Environment name from the workflow; do not assume a similarly named UI environment such as Production contains the active variables.

The Bucket and Endpoint are a deployment contract, not interchangeable examples. They must stay aligned with the trusted URL checks in src/main/version-checker.ts, sites/app.js, website validation, and related tests. A host, Bucket, Region, or CDN migration must update and validate every surface together before a new release.

• Use GitHub OIDC and the RAM Role to obtain short-lived STS credentials. Never add long-lived AccessKeys to repository or environment secrets.
• Keep ossutil pinned. Its V4 signing requires the Region; derive it from the canonical Endpoint, verify that the production value resolves to cn-beijing, and pass --region to every ossutil cp, including the final latest.json update.
• Grant the RAM Role only the actions and prefixes required by the workflow. It must be able to write immutable version objects and the final latest pointer without granting unrelated administration privileges.
• Upload release assets and site-release.json under the immutable releases/<tag>/ prefix first. Verify all 14 installer URLs publicly before creating or publishing the GitHub Release. Update releases/latest.json only after the GitHub Release is public and all prior checks succeeded.
• The expected GitHub Release contains 22 assets: 14 installers (two formats for each Windows/macOS target and three formats for each Linux target), six renamed target manifests, one aggregate release-manifest.json, and one SHA256SUMS. site-release.json is an OSS publication artifact, not a GitHub Release asset.

Failed Tag Recovery

Classify a failed tag by the external side effects that completed before choosing a recovery:

• If no source or release metadata must change, correct only the external configuration and use Re-run failed jobs for the same immutable tag. Do not change, move, delete, or recreate the tag.
• If immutable OSS objects were partially uploaded but their source bytes are unchanged, a same-tag rerun may idempotently re-upload or verify them. Never point latest.json at a partially verified prefix.
• If the GitHub Release is already public but the final latest-pointer step failed, it is a published version. Keep its packaged notes and rerun the failed release job for the same tag; do not classify it as an unpublished candidate.
• If code or release metadata must change, keep the failed tag immutable, increment the patch version, obtain approval for the revised exact release commit and notes, and create a new tag. Do not reuse the failed version.

When recovering from a version tag whose workflow never published a public GitHub Release:

• If a code or metadata change requires a higher version and a new tag, carry the failed candidate's approved user-facing notes forward into the recovery version, then remove the superseded failed version's entry from resources/release-notes.json.
• The packaged first-open modal must show that carried-forward content only once under the recovery version. Never retain both the failed version and its cumulative recovery copy, because users upgrading across them would see duplicate content.
• Never remove the packaged history for a version that successfully published a GitHub Release. Verify the failed release state before treating an entry as superseded.

Post-Publication Verification

Do not report a release complete until all of the following are verified:

1. The tag workflow and all six native package jobs succeeded. Verify the recorded macOS signing mode: signed builds must pass codesign, spctl, and stapler; unsigned builds must record the Gatekeeper caveat in the Actions log and job summary. In the final release job, explicitly verify the OSS configuration, OIDC authentication, release-index generation, immutable upload, public asset check, GitHub Release publication, and latest-pointer steps.
2. The public GitHub Release is non-draft, non-prerelease, marked Latest, and uses the expected tag and title. Its body must exactly match the Markdown generated from the approved packaged bilingual notes.
3. GitHub release metadata contains exactly the expected 22 uploaded asset names, including the expected Windows x64 and arm64 assets. Do not download, hash, launch, or send individual network probes to published installers unless the user explicitly requests that additional validation.
4. The Beijing releases/latest.json returns HTTP 200, has the expected stable version, exact six targets and 14 installer entries, the trusted Beijing URLs, and the GitHub fallback URL. It must match the immutable releases/<tag>/site-release.json. Fetching and comparing these small JSON metadata files is sufficient; rely on the successful publication job for its per-asset public checks.
5. The live website successfully fetches the index and produces the 14 correct platform/architecture/format links from that metadata.
6. Both remote main refs and both peeled tag refs still equal the approved release commit, and the local working tree is clean.

Never create or push a release tag, and never push a previously created release tag, before the release-note draft has received explicit approval.

• Before a push that updates the github remote, ask whether the user wants a release tag unless they already specified that choice. A branch-only push does not require a version bump or tag. When the user requests a release, verify that package.json and package-lock.json contain the same release version, create v${package.version} at the exact commit being pushed, and push that tag so the native package matrix and GitHub Release run.
• Never move or reuse an existing release tag. If v${package.version} already exists locally or on a remote at another commit, increment the package version and create a new matching tag before the release push.
• Verified release baseline on 2026-08-18: commit 60119a4317118fa3f077db0382664f15266a6682, annotated tag v0.10.4, and GitHub Actions run 32038633609 attempt 2 succeeded through all six native packages, GitHub Release publication, Beijing OSS publication, and the final latest.json switch.