ci: automate release version from tag (#211)

.github/workflows/README.md

@@ -43,6 +43,8 @@ This workflow builds Docker images on pushes and pull requests, and pushes to Gi
 - Skips registry push for fork PRs (avoids package write permission failures)
 - Uses build caching to speed up builds
 - Creates multiple tags for each image (latest, semver, sha)
+- Auto-syncs `package.json` version from `v*` tags during release builds
+- Validates release tags use semver format before building
 
 ### Docker Security Scan (`docker-scan.yml`)
 

.github/workflows/docker-build.yml

@@ -77,13 +77,34 @@ jobs:
         id: tag_version
         run: |
           if [[ $GITHUB_REF == refs/tags/v* ]]; then
-            echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
-            echo "Using version tag: ${GITHUB_REF#refs/tags/}"
+            TAG_VERSION="${GITHUB_REF#refs/tags/}"
+            if [[ ! "$TAG_VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$ ]]; then
+              echo "::error::Release tag '${TAG_VERSION}' is invalid. Expected semver tag format like v1.2.3 or v1.2.3-rc.1"
+              exit 1
+            fi
+            APP_VERSION="${TAG_VERSION#v}"
+            echo "VERSION=${TAG_VERSION}" >> $GITHUB_OUTPUT
+            echo "APP_VERSION=${APP_VERSION}" >> $GITHUB_OUTPUT
+            echo "Using version tag: ${TAG_VERSION}"
           else
             echo "VERSION=latest" >> $GITHUB_OUTPUT
+            echo "APP_VERSION=dev" >> $GITHUB_OUTPUT
             echo "No version tag, using 'latest'"
           fi
 
+      # Keep version files aligned automatically for tag-based releases
+      - name: Sync app version from release tag
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          VERSION="${{ steps.tag_version.outputs.APP_VERSION }}"
+          echo "Syncing package.json version to ${VERSION}"
+
+          jq --arg version "${VERSION}" '.version = $version' package.json > package.json.tmp
+          mv package.json.tmp package.json
+
+          echo "Version sync diff (package.json):"
+          git --no-pager diff -- package.json
+
       # Extract metadata for Docker
       - name: Extract Docker metadata
         id: meta

docs/DEVELOPMENT_WORKFLOW.md

@@ -310,26 +310,24 @@ bunx tsc --noEmit
 
 ## Release Process
 
-1. **Update version**:
-```bash
-npm version patch  # or minor/major
-```
+1. **Choose release version** (`X.Y.Z`) and update `CHANGELOG.md`
 
-2. **Update CHANGELOG.md**
-
-3. **Build and test**:
+2. **Build and test**:
 ```bash
 bun run build
 bun test
 ```
 
-4. **Create release**:
+3. **Create release tag** (semver format required):
 ```bash
 git tag vX.Y.Z
 git push origin vX.Y.Z
 ```
 
-5. **Create GitHub release**
+4. **Create GitHub release**
+
+5. **CI version sync (automatic)**:
+- On `v*` tags, release CI updates `package.json` version in the build context from the tag (`vX.Y.Z` -> `X.Y.Z`), so Docker release images always report the correct app version.
 
 ## Contributing