ci: add semantic-release workflow and docs

.github/workflows/container-image.yml

@@ -1,21 +1,19 @@
 name: Container Image
-run-name: ${{ github.event_name == 'workflow_run' && format('Image - {0} ({1})', github.event.workflow_run.head_commit.message, github.event.workflow_run.head_branch) || format('Image - {0}', github.ref_name) }}
+run-name: >-
+  ${{ github.event_name == 'workflow_run' && format('Image - {0} ({1})', github.event.workflow_run.head_commit.message, github.event.workflow_run.head_branch) || github.event_name == 'pull_request' && format('Image check - PR #{0}', github.event.pull_request.number) || format('Image - {0}', github.ref_name) }}
 
 on:
+  pull_request:
+    branches: [main]
   # Break-glass: bypasses CI/E2E gate. Use only when CI is broken and a hotfix image is urgently needed.
   workflow_dispatch:
   workflow_run:
     workflows: ["CI"]
     types: [completed]
     branches: [main]
-  push:
-    tags:
-      - "v*"
 
 concurrency:
-  # Use the commit SHA across all trigger types so a workflow_run completion and a
-  # simultaneous tag push for the same commit share one concurrency slot and cancel correctly.
-  group: ${{ github.workflow }}-${{ github.event_name == 'workflow_run' && github.event.workflow_run.head_sha || github.sha }}
+  group: ${{ github.workflow }}-${{ github.event_name == 'workflow_run' && github.event.workflow_run.head_sha || github.event_name == 'pull_request' && format('pr-{0}', github.event.pull_request.number) || github.sha }}
   cancel-in-progress: true
 
 permissions:
@@ -28,10 +26,11 @@ env:
 
 jobs:
   image:
-    name: Build and Push Image
+    name: ${{ github.event_name == 'pull_request' && 'Build and Scan Image' || 'Build and Push Image' }}
     if: >
-      github.event_name != 'workflow_run' ||
-      (github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'push')
+      github.event_name == 'pull_request' ||
+      github.event_name == 'workflow_dispatch' ||
+      (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'push')
     runs-on: ubuntu-latest
     timeout-minutes: 45
     permissions:
@@ -48,7 +47,6 @@ jobs:
           GH_SHA: ${{ github.sha }}
           WORKFLOW_RUN_HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
         run: |
-          # SHA resolution mirrors the concurrency group logic at the top of this workflow.
           if [[ "$EVENT_NAME" == "workflow_dispatch" && "$GH_REF" != "refs/heads/main" ]]; then
             echo "workflow_dispatch is only supported from main."
             exit 1
@@ -63,41 +61,28 @@ jobs:
           SHORT_SHA="${SHA:0:12}"
           IMAGE="$REGISTRY/$IMAGE_NAME"
 
-          PRIMARY_TAG="$GH_REF_NAME"
-
           echo "checkout_ref=${SHA}" >> "$GITHUB_OUTPUT"
           echo "image=${IMAGE}" >> "$GITHUB_OUTPUT"
           echo "scan_tag=${IMAGE}:sha-${SHORT_SHA}" >> "$GITHUB_OUTPUT"
-          echo "tags<<EOF" >> "$GITHUB_OUTPUT"
-          echo "${IMAGE}:${PRIMARY_TAG}" >> "$GITHUB_OUTPUT"
-          echo "${IMAGE}:sha-${SHORT_SHA}" >> "$GITHUB_OUTPUT"
-          echo "EOF" >> "$GITHUB_OUTPUT"
+
+          if [[ "$EVENT_NAME" == "pull_request" ]]; then
+            echo "should_push=false" >> "$GITHUB_OUTPUT"
+            echo "tags<<EOF" >> "$GITHUB_OUTPUT"
+            echo "${IMAGE}:sha-${SHORT_SHA}" >> "$GITHUB_OUTPUT"
+            echo "EOF" >> "$GITHUB_OUTPUT"
+          else
+            echo "should_push=true" >> "$GITHUB_OUTPUT"
+            echo "tags<<EOF" >> "$GITHUB_OUTPUT"
+            echo "${IMAGE}:${GH_REF_NAME}" >> "$GITHUB_OUTPUT"
+            echo "${IMAGE}:sha-${SHORT_SHA}" >> "$GITHUB_OUTPUT"
+            echo "EOF" >> "$GITHUB_OUTPUT"
+          fi
 
       - name: Checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           ref: ${{ steps.vars.outputs.checkout_ref }}
 
-      - name: Verify CI succeeded for tag commit
-        if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
-        shell: bash
-        env:
-          GH_TOKEN: ${{ github.token }}
-          COMMIT_SHA: ${{ github.sha }}
-          GH_REPO: ${{ github.repository }}
-        run: |
-          set -euo pipefail
-          echo "Checking CI status for commit ${COMMIT_SHA}..."
-          success_count=$(gh api --paginate \
-            "repos/${GH_REPO}/actions/workflows/ci.yml/runs?head_sha=${COMMIT_SHA}&status=completed&event=push&branch=main" \
-            --jq '[.workflow_runs[] | select(.conclusion == "success")] | length' \
-            | awk '{sum += $1} END {print sum}')
-          if [[ "${success_count:-0}" -lt 1 ]]; then
-            echo "No successful CI run found for tag commit ${COMMIT_SHA}. Refusing to publish image."
-            exit 1
-          fi
-          echo "CI verification passed: ${success_count} successful run(s) found."
-
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
 
@@ -124,6 +109,7 @@ jobs:
           exit-code: "1"
 
       - name: Log in to GHCR
+        if: steps.vars.outputs.should_push == 'true'
         uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
         with:
           registry: ${{ env.REGISTRY }}
@@ -131,6 +117,7 @@ jobs:
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Push image
+        if: steps.vars.outputs.should_push == 'true'
         shell: bash
         run: |
           while IFS= read -r tag; do