videorc-release

# Videorc release Ship one new numeric desktop version on both supported tracks: - macOS arm64 Beta: `<version>-beta.<N>`; - Windows 11 x64 Alpha: `<version>-alpha.1`. Target both platforms unless the user explicitly requests a platform-only release. Do not silently skip Windows because macOS can be released locally. Before acting, read both sources of truth in full: - `docs/releases/release-runbook.md` for macOS, shared versioning, and rollback; - `docs/releases/windows-alpha-runbook.md` for Windows signing, candidate, physical acceptance, pilot, public promotion, and rollback. Keep this skill as the executable coordinator. Do not weaken or duplicate the runbooks' detailed gates. ## Completion contract - Prepare both release IDs from one strictly higher three-part numeric package version. Record the exact macOS source commit and the later Windows candidate source commit separately. If a rejected Windows candidate must roll forward after macOS is live, allow the platform versions to diverge rather than republishing macOS merely for version parity. - Publish and verify the macOS Beta independently of the Windows Alpha gates. - Build Windows only from current protected `main`; never release a PR artifact, locally signed substitute, or rebuilt post-acceptance installer. - Call the coordinated release complete only after macOS is live and verified and the exact Windows candidate has passed physical acceptance, pilot, public promotion, and production smoke. - If an external Windows gate cannot be completed, preserve the candidate and report the release as partial with the exact missing gate. Never describe a private candidate or pilot pointer as a public Windows release. - Keep the web Windows state `disabled` until public promotion and production smoke succeed. Never change macOS availability while gating Windows. ## Prerequisites ### Shared - Use a clean checkout based on current protected `main`. - Confirm GitHub access can dispatch and inspect Actions workflows. - Confirm storage credentials are scoped as documented (R2 per platform prefix; Neon and Hetzner per dedicated release-only project). Never run the local macOS upload concurrently with Windows public promotion because both may update the merged global changelog. A pending Windows Alpha changelog entry on `main` does not block macOS uploads: each uploader only introduces entries for its own platform, and logs the ones it withholds. - Name release, Windows acceptance, support, and rollback owners before starting. ### macOS - Load `APPLE_ID` and `APPLE_APP_SPECIFIC_PASSWORD` from `~/.videorc-release.env`. - Load the allow-listed X OAuth consumer key and secret required by the packaged backend from the same file. Do not reintroduce the paused YouTube OAuth secret unless the runbook explicitly restores that requirement. - Verify the Developer ID identity `Uros Miric (C2PA37RB58)` is available in the keychain, or provide the documented `CSC_LINK` alternative. - Load `VIDEORC_RELEASE_UPLOAD_NEON_S3_*`, `VIDEORC_RELEASE_UPLOAD_HETZNER_S3_*` and `VIDEORC_DOWNLOAD_STORAGE_PRIMARY` from `~/.videorc-release.env` (whichever origins are still configured). The upload publishes to **every configured** storage origin, mirrors first, primary last. Target: Neon is the single origin; Hetzner and R2 stay read-only until the soak ends, and `VIDEORC_DOWNLOAD_STORAGE_PRIMARY=hetzner` in videorc-web is the rollback. - Only while R2 is still an origin: load `VIDEORC_DOWNLOAD_S3_*` from `~/projects/videorcweb/.env` and normalize the upload endpoint to the bucket-less R2 account host. A Neon-only setup needs no R2 env. - Every Neon release credential needs both `storage:read` and `storage:write`; a write-only key gets 403 on the uploader's HEAD/GET checks. - Read "Storage origins" in the release runbook: a blocked mirror degrades the release and leaves a pending record to replay with `pnpm release:sync:origins -- --pending`; a blocked primary stops it unless `VIDEORC_RELEASE_ALLOW_MIRROR_ONLY=1`. ### Windows - Verify the protected `windows-alpha-release` environment, required reviewers, protected-main deployment rule, GitHub OIDC federation, Azure Trusted Signing publisher/profile values, and least-privilege candidate/promotion storage credentials (including the `VIDEORC_RELEASE_UPLOAD_NEON_S3_*` origin) are configured. - Verify a named operator has clean physical Windows 11 x64 hardware, private candidate-read access, a release secret channel, and the acceptance template. - Verify the web pilot bearer secret and the disabled/pilot/public release-state values are ready. Do not place Windows signing or storage credentials in a local release env file. ## 1. Freeze the numeric version and macOS source 1. Bump `apps/desktop/package.json` to a strictly higher numeric version. 2. Choose the macOS Beta number and derive `<version>-beta.<N>`. 3. Derive the Windows release ID as exactly `<version>-alpha.1`. A correction requires another numeric version bump; never issue same-version `alpha.2`. 4. Write `changelog/<version>-beta.<N>.md` with `channel: beta` and `platforms: [macos]`. 5. Run `pnpm changelog:check`, commit the version and macOS entry, push through a reviewed PR, and merge to protected `main`. Record the full lowercase 40-character macOS source commit. The Windows Alpha changelog entry may be added before or after the macOS upload: `release:upload:macos` withholds Windows-only entries that are not public yet, so a held Windows release is never disclosed by a macOS upload. Confirm the `withholding <releaseId>` line in the upload log. ## 2. Publish and verify macOS Beta Follow `docs/releases/release-runbook.md`. For the established local keychain path, load release secrets, set `APPLE_TEAM_ID=C2PA37RB58`, set the exact Beta number, and normalize every origin endpoint to its host-only form before running: ```sh pnpm package:backend:macos && pnpm ffmpeg:build:macos \ && pnpm package:preflight:macos \ && pnpm --filter @videorc/desktop dist:release \ && pnpm release:manifest:macos \ && pnpm release:validate:macos ``` This local path intentionally bypasses `release:preflight:macos`, whose `CSC_LINK` requirement does not apply to the keychain identity. Do not bypass artifact validation, signing, notarization, stapling, changelog, or upload preflight behavior. Complete the macOS clean-machine acceptance template, required real-device screen/camera/microphone gates, installed-app checks, and strict provider readiness with an overall `PASS`. Only then publish: ```sh pnpm release:upload:preflight:macos && pnpm release:upload:macos ``` Follow the redirects and verify: ```sh curl -sL https://www.videorc.com/api/updates/latest-mac.yml | head curl -s -o /dev/null -w '%{http_code}\n' -L \ https://www.videorc.com/api/updates/Videorc-<version>-mac-arm64.zip ``` Also verify the signed-in macOS download page shows the exact new version and checksum. The stable manifest must remain `releases/macos/latest/release.json`; never pin the web environment to one versioned object. ## 3. Build the private Windows Alpha candidate After the macOS upload and verification succeed: 1. Add `changelog/<version>-alpha.1.md` with `channel: alpha` and `platforms: [windows]` on top of current `main`. 2. State only Windows capabilities that the acceptance plan can prove. Keep internal gate details out of the public entry. 3. Run `pnpm changelog:check`, push through a reviewed PR, and merge to protected `main` without changing the numeric package version. 4. Record this new full lowercase 40-character Windows candidate source commit. From the current protected-main Windows source commit, dispatch the exact release ID: ```sh gh workflow run release-windows-alpha.yml --ref main \ -f release_id=<version>-alpha.1 ``` Wait for both trust-separated jobs. The unprivileged job builds and hashes the unsigned handoff; only the protected OIDC job may sign, validate, and upload the immutable private candidate. Record the workflow URL, release ID, source commit, installer SHA-256, exact publisher, and candidate prefix. Any stale-main, signing, timestamp, publisher, manifest, feed, checksum, or immutable-object failure blocks the release. A transient retry may reuse the same release ID only when the source commit and all candidate bytes are unchanged. Any source or candidate correction must remove the abandoned, unpublished Windows changelog entry from current `main`, bump the numeric package version, add the replacement `<new-version>-alpha.1` entry, and begin a new candidate. Keep the already-published macOS release; do not republish it merely to restore version parity. Never mutate or bless failed bytes. If the rejected candidate reached pilot, keep the web state `disabled`, rotate the pilot bearer token immediately, and use the named release-owner rollback procedure to restore the last accepted pilot pointer only when that recovery is supported and verified. Otherwise, including the first pilot, leave the rejected immutable objects preserved but make the pilot route inaccessible until a replacement is authorized. If an out-of-order upload already exposed the abandoned Windows changelog entry, stop and treat it as a content incident. The normal macOS and Windows uploaders merge remote entries additively, so deleting the file from Git does not retract the published entry. Preserve the current object/version, use a release-owner approved full-document recovery path to replace `changelog/changelog.json`, and verify the website and installed-app changelog before continuing. Never use an ad-hoc unvalidated object edit or the changelog skip escape as a purge mechanism. ## 4. Accept and promote Windows Follow every command and evidence rule in `docs/releases/windows-alpha-runbook.md`: 1. Download and verify the exact private candidate on clean physical Windows 11 x64 hardware. 2. Strip all storage, signing, and Azure authority before launching candidate code. 3. Run installed-app acceptance with the expected executable hash and complete every required install, sign-in, capture, recording, GPU, process-cleanup, Defender, signature, timestamp, updater, and uninstall row. 4. Promote the exact identity to the isolated pilot lane: ```sh gh workflow run promote-windows-alpha.yml --ref main \ -f release_id=<releaseId> \ -f source_commit=<40-character-source-commit> \ -f installer_sha256=<64-character-installer-sha256> \ -f stage=pilot ``` 5. Verify the authenticated account download and bearer-protected pilot updater round trip. Clear the pilot token from the operator environment afterward. 6. Commit the strict sanitized PASS record at `docs/acceptance/windows-alpha/<releaseId>.json`. Use a commit-pinned GitHub URL; never publish private evidence. 7. Promote the same candidate identity to public: ```sh gh workflow run promote-windows-alpha.yml --ref main \ -f release_id=<releaseId> \ -f source_commit=<40-character-source-commit> \ -f installer_sha256=<64-character-installer-sha256> \ -f stage=public \ -f acceptance_record_url=<commit-pinned-github-record-url> ``` Never rebuild between acceptance and either promotion. Never substitute CI, VM-only, file-size, branch URL, or mutable-tag evidence for the exact physical record. ## 5. Verify the coordinated production release - Verify the signed-in Windows download returns the accepted installer and visible SHA-256. - Verify the Windows public `latest.yml`, installer, and blockmap resolve through the production updater route and update the prior accepted Alpha. - Recheck the Windows Authenticode publisher, valid status, timestamp, and downloaded SHA-256. - Verify the macOS DMG, checksum, `latest-mac.yml`, zip, and blockmap still point to the macOS release prepared above. - Authorize the web Windows `public` state only after those checks pass, deploy, and rerun the two-platform smoke matrix. - Update `docs/releases/<version>.md` with both platform outcomes, workflow and evidence links, rollback status, and any explicitly incomplete external gate. - Render/send announcements from the exact platform changelog entry only after that platform is live. Preview with `pnpm release:notify:discord <releaseId> --dry-run`, then send with `pnpm release:notify:discord <releaseId>`. Hold all Windows announcements until public promotion. ## Hard-won rules - Use a bucket-less (host-only) endpoint for every origin, R2 account host or Neon `<branch-id>.storage.c-<N>.<region>.aws.neon.tech`. A bucket suffix causes doubled keys that upload successfully and then 404. - Do not source process substitution under macOS Bash 3.2; write filtered env lines to a temporary file and source that file, or run the documented command under zsh. - Follow every web redirect to the final storage response; a `302` alone is not proof. Verify the mirror route `/api/updates/mirror/` too: while a mirror is configured its final host differs from the primary's; with Neon as the single origin it serves the primary, never a 5xx. - A forged TLS issuer on a storage host is a network block (Spain, matchday evenings), not an outage. Never bypass TLS; publish around it. - Keep presigned updater redirects short-lived; never restore immutable caching. - macOS updater order uses the numeric package version, not the Beta release ID. - Windows updater order also uses the numeric package version; this is why every Alpha correction must bump it and return to `alpha.1`. - Keep all macOS and Windows release, updater, pilot, and candidate prefixes isolated. A Windows action must never move a macOS pointer. - Roll forward installed clients with a higher numeric version. Disable or restore web pointers for rollback; never overwrite immutable release bytes.