feat: create initial release workflow for automated pypi publishing

.github/workflows/docker-publish.yaml

@@ -1,13 +1,21 @@
 name: Build and Push Docker Image
 
 on:
-  push:
-    tags:
-      - "v*.*.*"
   pull_request:
     branches:
       - main
   workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version/tag to build and push (e.g. 0.1.0). Leave blank to build without pushing.'
+        required: false
+        type: string
+  workflow_call:
+    inputs:
+      version:
+        description: 'Release version/tag to build (used for image tags and checkout ref).'
+        required: true
+        type: string
 
 env:
   REGISTRY: ghcr.io
@@ -24,6 +32,33 @@ jobs:
 
     steps:
       - uses: actions/checkout@v7
+        with:
+          ref: ${{ inputs.version || github.ref }}
+
+      - name: Parse version
+        id: ver
+        run: |
+          set -euo pipefail
+          V="${{ inputs.version }}"
+          STABLE=false
+          MAJOR_MINOR=""
+          MAJOR=""
+          # A stable release is exactly X.Y.Z. RC/pre-release versions (X.Y.ZrcN)
+          # only get the exact-version tag, never the moving major/minor/latest tags.
+          if [[ "$V" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            STABLE=true
+            MAJOR_MINOR=$(echo "$V" | cut -d. -f1,2)
+            MAJOR=$(echo "$V" | cut -d. -f1)
+          fi
+          echo "stable=$STABLE" >> "$GITHUB_OUTPUT"
+          echo "major_minor=$MAJOR_MINOR" >> "$GITHUB_OUTPUT"
+          echo "major=$MAJOR" >> "$GITHUB_OUTPUT"
+          # Push only when we have a concrete version to publish and it's not a PR.
+          if [[ "${{ github.event_name }}" != "pull_request" && -n "$V" ]]; then
+            echo "push=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "push=false" >> "$GITHUB_OUTPUT"
+          fi
 
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v4
@@ -32,7 +67,7 @@ jobs:
         uses: docker/setup-buildx-action@v4
 
       - name: Log in to GHCR
-        if: github.event_name != 'pull_request'
+        if: steps.ver.outputs.push == 'true'
         uses: docker/login-action@v4
         with:
           registry: ${{ env.REGISTRY }}
@@ -44,28 +79,30 @@ jobs:
         uses: docker/metadata-action@v6
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          # Release versions are PEP 440 (e.g. 0.1.0rc1), which is not valid SemVer,
+          # so tags are built with type=raw from the parsed version instead of type=semver.
           tags: |
-            type=semver,pattern={{version}}
-            type=semver,pattern={{major}}.{{minor}}
-            type=semver,pattern={{major}}
-            type=raw,value=latest,enable=${{ github.ref_type == 'tag' && !contains(github.ref_name, '-') }}
+            type=raw,value=${{ inputs.version }},enable=${{ inputs.version != '' }}
+            type=raw,value=${{ steps.ver.outputs.major_minor }},enable=${{ steps.ver.outputs.stable == 'true' }}
+            type=raw,value=${{ steps.ver.outputs.major }},enable=${{ steps.ver.outputs.stable == 'true' }}
+            type=raw,value=latest,enable=${{ steps.ver.outputs.stable == 'true' }}
 
       - name: Build and push
         id: build
         uses: docker/build-push-action@v7
         with:
           context: .
           platforms: linux/amd64,linux/arm64
-          push: ${{ github.event_name != 'pull_request' }}
+          push: ${{ steps.ver.outputs.push == 'true' }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
-          build-args: VERSION=${{ steps.meta.outputs.version }}
+          build-args: VERSION=${{ inputs.version }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
 
       - name: Scan image for critical CVEs (Trivy)
+        if: steps.ver.outputs.push == 'true'
         uses: aquasecurity/trivy-action@master
-        if: github.event_name != 'pull_request'
         with:
           image-ref: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@${{ steps.build.outputs.digest }}
           format: table