@@ -0,0 +1,213 @@
+name: Release
+
+# Triggered ONLY on annotated tag push matching `v*.*.*`. The
+# expected sequence is:
+#
+#   1. Commit + push CHANGELOG bump on main (manual).
+#   2. `git tag -a vX.Y.Z -m "..."` against that commit (manual).
+#   3. `git push origin vX.Y.Z` — this workflow fires.
+#
+# We do NOT re-run unit tests here; the tag must already point at a
+# commit that's green on the `ci.yml` workflow. Re-testing would
+# double the wall-clock for tag bumps without catching anything CI
+# wouldn't.
+on:
+  push:
+    tags: ['v*.*.*']
+
+# The GITHUB_TOKEN needs explicit write scopes for the publish steps —
+# the default is read-only. `packages: write` is for ghcr.io; `contents:
+# write` is for the Release entry.
+permissions:
+  contents: write
+  packages: write
+
+jobs:
+  # -------------------------------------------------------------------
+  # Docker images — server + web in parallel via matrix
+  # -------------------------------------------------------------------
+  build-images:
+    name: Image · ${{ matrix.component }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        component: [server, web]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Reclaim runner disk
+        # `Dockerfile.server` links 40+ test binaries + ships a stripped
+        # release build; the default ubuntu-latest ~14 GiB freespace is
+        # not enough. Mirror what ci.yml's rust job does — drop the
+        # preinstalled CodeQL / dotnet / Android toolchains before
+        # buildx allocates layers.
+        run: |
+          sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc \
+                      /opt/hostedtoolcache/CodeQL /usr/local/.ghcup
+          df -h /
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Resolve version + image metadata
+        id: meta
+        run: |
+          set -eu
+          VERSION="${GITHUB_REF_NAME#v}"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          # Lowercase repo owner — GHCR rejects mixed case. This
+          # matches the default in the project's Helm values
+          # (`ghcr.io/thinkwatch/...`) so a tag bump publishes to the
+          # repo Helm already points at.
+          OWNER="$(echo "${{ github.repository_owner }}" | tr '[:upper:]' '[:lower:]')"
+          echo "image=ghcr.io/$OWNER/think-watch-${{ matrix.component }}" >> "$GITHUB_OUTPUT"
+          # Tag `:latest` ONLY for stable releases — anything that
+          # looks like a pre-release (`0.x.y`, `-rc`, `-beta`, `-alpha`)
+          # stays version-pinned. Operators chase `:latest` at their
+          # own risk; betas don't get to surprise them.
+          PRERELEASE=false
+          case "$GITHUB_REF_NAME" in
+            v0.*|*-rc.*|*-beta.*|*-alpha.*) PRERELEASE=true ;;
+          esac
+          echo "prerelease=$PRERELEASE" >> "$GITHUB_OUTPUT"
+
+      - name: Build & push image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: deploy/docker/Dockerfile.${{ matrix.component }}
+          platforms: linux/amd64,linux/arm64
+          push: true
+          # Always publish the version tag; only publish `:latest`
+          # for stable releases. The `if:` on the latter would
+          # require splitting the step — `cat <<EOF` form keeps it
+          # in one place and lets buildx skip the empty tag silently.
+          tags: |
+            ${{ steps.meta.outputs.image }}:${{ steps.meta.outputs.version }}
+            ${{ steps.meta.outputs.prerelease == 'false' && format('{0}:latest', steps.meta.outputs.image) || '' }}
+          # GHCR-side OCI labels — what `helm install` / `docker scout`
+          # surface in cluster inventories. Pull the source / version /
+          # license / authors from the tag rather than the Dockerfile
+          # so they stay in lockstep with the GitHub Release.
+          labels: |
+            org.opencontainers.image.source=https://github.com/${{ github.repository }}
+            org.opencontainers.image.version=${{ steps.meta.outputs.version }}
+            org.opencontainers.image.revision=${{ github.sha }}
+            org.opencontainers.image.licenses=BUSL-1.1
+          cache-from: type=gha,scope=${{ matrix.component }}
+          cache-to: type=gha,scope=${{ matrix.component }},mode=max
+
+  # -------------------------------------------------------------------
+  # Helm chart — packaged with the same version as the tag
+  # -------------------------------------------------------------------
+  package-helm:
+    name: Helm chart
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: azure/setup-helm@v4
+        with:
+          version: latest
+      - name: Resolve version
+        id: meta
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+      - name: Package chart
+        # `--app-version` is the image tag the chart's deployment
+        # templates reach for by default (via `tw.imageTag`). Pinning
+        # it here keeps a fresh `helm install think-watch-X.Y.Z.tgz`
+        # pointing at the matching image bundle from the build-images
+        # job above.
+        run: |
+          helm package deploy/helm/think-watch \
+            --version "${{ steps.meta.outputs.version }}" \
+            --app-version "${{ steps.meta.outputs.version }}" \
+            --destination .
+      - name: Upload chart artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: helm-chart
+          path: think-watch-*.tgz
+          retention-days: 30
+
+  # -------------------------------------------------------------------
+  # GitHub Release — attaches the Helm chart, links the images
+  # -------------------------------------------------------------------
+  create-release:
+    name: GitHub Release
+    needs: [build-images, package-helm]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Download Helm chart artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: helm-chart
+          path: .
+      - name: Extract release notes from CHANGELOG
+        id: notes
+        # awk-based section extraction so we don't pull in another
+        # dep just for `## [X.Y.Z]` markdown chunking. If the
+        # CHANGELOG doesn't carry an entry for this tag, fail loudly
+        # — releasing without notes hides what changed from operators.
+        run: |
+          set -eu
+          VERSION="${GITHUB_REF_NAME#v}"
+          awk -v ver="$VERSION" '
+            /^## \[/{
+              if ($0 ~ "^## \\[" ver "\\]") { found=1; next }
+              else if (found) { exit }
+            }
+            found
+          ' CHANGELOG.md > release-notes.md
+          if [ ! -s release-notes.md ]; then
+            echo "::error::No CHANGELOG entry for $VERSION — refusing to publish a release without notes."
+            exit 1
+          fi
+          # Add a leading reference to the GHCR images so users on the
+          # Release page can copy-paste them without hunting through
+          # the chart values.
+          OWNER="$(echo "${{ github.repository_owner }}" | tr '[:upper:]' '[:lower:]')"
+          {
+            echo "## Images"
+            echo ""
+            echo "- \`ghcr.io/$OWNER/think-watch-server:$VERSION\`"
+            echo "- \`ghcr.io/$OWNER/think-watch-web:$VERSION\`"
+            echo ""
+            echo "## Helm"
+            echo ""
+            echo '```bash'
+            echo "helm install think-watch ./think-watch-$VERSION.tgz \\"
+            echo "  --namespace thinkwatch --create-namespace"
+            echo '```'
+            echo ""
+            echo "---"
+            echo ""
+            cat release-notes.md
+          } > release-body.md
+      - name: Detect pre-release flag
+        id: meta
+        run: |
+          PRERELEASE=false
+          case "$GITHUB_REF_NAME" in
+            v0.*|*-rc.*|*-beta.*|*-alpha.*) PRERELEASE=true ;;
+          esac
+          echo "prerelease=$PRERELEASE" >> "$GITHUB_OUTPUT"
+      - name: Create release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: ThinkWatch ${{ github.ref_name }}
+          body_path: release-body.md
+          prerelease: ${{ steps.meta.outputs.prerelease }}
+          files: |
+            think-watch-*.tgz