KoalaSync/docs/devops.md

DevOps Release Workflow

This document describes the deployment and release process for KoalaSync.

Tag-Based Releases

KoalaSync uses an automated release pipeline triggered by immutable annotated Git tags.

Important

DO NOT edit individual version files before tagging. The workflow extracts the exact SemVer version from the tag and updates every release-version source atomically. Markdown-only changes do not require browser or release gates.

How it Works

When an annotated tag matching exact vMAJOR.MINOR.PATCH is pushed, the GitHub Actions workflow performs these ordered gates:

1. Validates that the tag is an annotated exact vMAJOR.MINOR.PATCH tag, points at current origin/main, and has successful verify, node20, and e2e checks. Invalid tags are rejected before any write.
2. Extracts the validated version and uses the tagged commit timestamp so repeated preparation is deterministic.
3. Updates and validates all version sources: extension/manifest.base.json, shared/constants.js, package.json, root metadata in package-lock.json, website/version.json, website/template.html, website/llms.txt, and both the README badge and release banner.
4. Creates chore(release): update versions to vX.Y.Z [skip ci] and pushes it directly to main. A failed push stops every dependent release job.
5. Checks out that exact prepared commit for full verification, cross-browser E2E, the unpublished relay health smoke, Chrome/Firefox/AMO/checksum/archive validation, website output, and the relay container build.
6. Creates an attested draft GitHub Release after extension checks pass.
7. Publishes the canonical lowercase image ghcr.io/shik3i/koalasync, then verifies both platforms, attestation identity, digest, tag source, and a running health check.
8. Makes the GitHub Release public only after every preceding job succeeds.

---

Steps to Deploy a New Release

To release a new version (e.g., v2.5.1), follow these steps:

1. Fast-forward local main, confirm a clean tree at exact origin/main, and wait for verify, node20, and e2e on that commit:

   git checkout main
   git pull --ff-only origin main
   test -z "$(git status --porcelain=v1)"
   test "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)"
   

2. Create an annotated exact SemVer tag on that commit. Do not run prepare:release; the tag workflow owns version updates:

   git tag -a v2.5.1 -m "Release v2.5.1"
   

3. Verify the tag target, then push it once:

   test "$(git rev-parse v2.5.1^{commit})" = "$(git rev-parse origin/main)"
   git push origin v2.5.1
   

Never reuse or move a published tag. Monitor every release job and verify both the public GitHub assets and GHCR digest before calling the release complete.

npm run release:gate -- MAJOR.MINOR.PATCH [--candidate] remains an optional Linux/AMD64 parity diagnostic when release code changes. It prepares the target version only inside an isolated clone. It is not required for Markdown-only changes and does not replace the tag workflow's own gates.

The relay registry reference is always the canonical lowercase ghcr.io/shik3i/koalasync. Docker repository names reject uppercase characters; release:gate rejects workflows that derive this reference from the case-preserving ${{ github.repository }} value.