mirror of
https://github.com/Shik3i/KoalaSync.git
synced 2026-08-30 12:29:27 +00:00
KoalaDev
77 lines
3.3 KiB
Markdown
77 lines
3.3 KiB
Markdown
# 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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
git tag -a v2.5.1 -m "Release v2.5.1"
|
|
```
|
|
3. Verify the tag target, then push it once:
|
|
```bash
|
|
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.
|