From ca4a55312f49d89e00ac90c8311228ce185ea892 Mon Sep 17 00:00:00 2001
From: l5y <220195275+l5yth@users.noreply.github.com>
Date: Fri, 21 Nov 2025 17:09:23 +0100
Subject: [PATCH] Handle pre-release Docker tagging (#486)

---
 .github/workflows/docker.yml | 58 ++++++++++++++++++++++++++++++------
 DOCKER.md                    | 15 ++++++----
 2 files changed, 58 insertions(+), 15 deletions(-)

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index fff2fa0..68f5581 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -82,6 +82,29 @@ jobs:
         echo "raw_version=$RAW_VERSION" >> $GITHUB_OUTPUT
         echo "Published version: $STRIPPED_VERSION"
 
+    - name: Determine tagging strategy
+      id: tagging
+      env:
+        EVENT_NAME: ${{ github.event_name }}
+        PUBLISH_ALL_VARIANTS: ${{ github.event.inputs.publish_all_variants || 'false' }}
+      run: |
+        VERSION="${{ steps.version.outputs.version }}"
+
+        if echo "$VERSION" | grep -E -- '-(rc|beta|alpha|dev)'; then
+          IS_PRERELEASE=true
+        else
+          IS_PRERELEASE=false
+        fi
+
+        if [ "$IS_PRERELEASE" = "false" ] && { [ "$EVENT_NAME" = "push" ] || [ "$PUBLISH_ALL_VARIANTS" = "true" ]; }; then
+          INCLUDE_LATEST=true
+        else
+          INCLUDE_LATEST=false
+        fi
+
+        echo "is_prerelease=$IS_PRERELEASE" >> $GITHUB_OUTPUT
+        echo "include_latest=$INCLUDE_LATEST" >> $GITHUB_OUTPUT
+
     - name: Build and push ${{ matrix.service }} for ${{ matrix.architecture.name }}
       uses: docker/build-push-action@v5
       with:
@@ -91,9 +114,9 @@ jobs:
         platforms: ${{ matrix.architecture.platform }}
         push: true
         tags: |
-          ${{ env.REGISTRY }}/${{ env.IMAGE_PREFIX }}-${{ matrix.service }}-${{ matrix.architecture.name }}:latest
           ${{ env.REGISTRY }}/${{ env.IMAGE_PREFIX }}-${{ matrix.service }}-${{ matrix.architecture.name }}:${{ steps.version.outputs.version }}
           ${{ env.REGISTRY }}/${{ env.IMAGE_PREFIX }}-${{ matrix.service }}-${{ matrix.architecture.name }}:${{ steps.version.outputs.version_with_v }}
+          ${{ steps.tagging.outputs.include_latest == 'true' && format('{0}/{1}-{2}-{3}:latest', env.REGISTRY, env.IMAGE_PREFIX, matrix.service, matrix.architecture.name) || '' }}
         labels: |
           org.opencontainers.image.source=https://github.com/${{ github.repository }}
           org.opencontainers.image.description=PotatoMesh ${{ matrix.service == 'web' && 'Web Application' || 'Python Ingestor' }} for ${{ matrix.architecture.label }}
@@ -136,6 +159,19 @@ jobs:
         echo "version=$STRIPPED_VERSION" >> $GITHUB_OUTPUT
         echo "version_with_v=v$STRIPPED_VERSION" >> $GITHUB_OUTPUT
 
+    - name: Detect pre-release tag
+      id: tagging
+      run: |
+        VERSION="${{ steps.version.outputs.version }}"
+
+        if echo "$VERSION" | grep -E -- '-(rc|beta|alpha|dev)'; then
+          INCLUDE_LATEST=false
+        else
+          INCLUDE_LATEST=true
+        fi
+
+        echo "include_latest=$INCLUDE_LATEST" >> $GITHUB_OUTPUT
+
     - name: Test web application (Linux AMD64)
       run: |
         docker pull ${{ env.REGISTRY }}/${{ env.IMAGE_PREFIX }}-web-linux-amd64:${{ steps.version.outputs.version }}
@@ -184,15 +220,19 @@ jobs:
         
         # Web images
         echo "### 🌐 Web Application" >> $GITHUB_STEP_SUMMARY
-        echo "- \`${{ env.REGISTRY }}/${{ env.IMAGE_PREFIX }}-web-linux-amd64:latest\` - Linux x86_64" >> $GITHUB_STEP_SUMMARY
-        echo "- \`${{ env.REGISTRY }}/${{ env.IMAGE_PREFIX }}-web-linux-arm64:latest\` - Linux ARM64" >> $GITHUB_STEP_SUMMARY
-        echo "- \`${{ env.REGISTRY }}/${{ env.IMAGE_PREFIX }}-web-linux-armv7:latest\` - Linux ARMv7" >> $GITHUB_STEP_SUMMARY
-        echo "" >> $GITHUB_STEP_SUMMARY
+        if [ "${{ steps.tagging.outputs.include_latest }}" = "true" ]; then
+          echo "- \`${{ env.REGISTRY }}/${{ env.IMAGE_PREFIX }}-web-linux-amd64:latest\` - Linux x86_64" >> $GITHUB_STEP_SUMMARY
+          echo "- \`${{ env.REGISTRY }}/${{ env.IMAGE_PREFIX }}-web-linux-arm64:latest\` - Linux ARM64" >> $GITHUB_STEP_SUMMARY
+          echo "- \`${{ env.REGISTRY }}/${{ env.IMAGE_PREFIX }}-web-linux-armv7:latest\` - Linux ARMv7" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+        fi
 
         # Ingestor images
         echo "### 📡 Ingestor Service" >> $GITHUB_STEP_SUMMARY
-        echo "- \`${{ env.REGISTRY }}/${{ env.IMAGE_PREFIX }}-ingestor-linux-amd64:latest\` - Linux x86_64" >> $GITHUB_STEP_SUMMARY
-        echo "- \`${{ env.REGISTRY }}/${{ env.IMAGE_PREFIX }}-ingestor-linux-arm64:latest\` - Linux ARM64" >> $GITHUB_STEP_SUMMARY
-        echo "- \`${{ env.REGISTRY }}/${{ env.IMAGE_PREFIX }}-ingestor-linux-armv7:latest\` - Linux ARMv7" >> $GITHUB_STEP_SUMMARY
-        echo "" >> $GITHUB_STEP_SUMMARY
+        if [ "${{ steps.tagging.outputs.include_latest }}" = "true" ]; then
+          echo "- \`${{ env.REGISTRY }}/${{ env.IMAGE_PREFIX }}-ingestor-linux-amd64:latest\` - Linux x86_64" >> $GITHUB_STEP_SUMMARY
+          echo "- \`${{ env.REGISTRY }}/${{ env.IMAGE_PREFIX }}-ingestor-linux-arm64:latest\` - Linux ARM64" >> $GITHUB_STEP_SUMMARY
+          echo "- \`${{ env.REGISTRY }}/${{ env.IMAGE_PREFIX }}-ingestor-linux-armv7:latest\` - Linux ARMv7" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+        fi
         
diff --git a/DOCKER.md b/DOCKER.md
index b82e525..837825f 100644
--- a/DOCKER.md
+++ b/DOCKER.md
@@ -15,13 +15,16 @@ will pull the latest release images for you.
 
 | Service  | Image                                                                                                         |
 |----------|---------------------------------------------------------------------------------------------------------------|
-| Web UI   | `ghcr.io/l5yth/potato-mesh-web-linux-amd64:<tag>` (e.g. `latest`, `3.0`, or `v3.0`)                           |
-| Ingestor | `ghcr.io/l5yth/potato-mesh-ingestor-linux-amd64:<tag>` (e.g. `latest`, `3.0`, or `v3.0`)                      |
+| Web UI   | `ghcr.io/l5yth/potato-mesh-web-linux-amd64:<tag>` (e.g. `latest`, `3.0`, `v3.0`, or `3.1.0-rc1`)              |
+| Ingestor | `ghcr.io/l5yth/potato-mesh-ingestor-linux-amd64:<tag>` (e.g. `latest`, `3.0`, `v3.0`, or `3.1.0-rc1`)         |
 
-Images are published for every tagged release. Each build receives both semantic
-version tags (for example `3.0`) and a matching `v`-prefixed tag (for example
-`v3.0`). `latest` always points to the newest release, so pin one of the version
-tags when you need a specific build.
+Images are published for every tagged release. Stable builds receive both
+semantic version tags (for example `3.0`) and a matching `v`-prefixed tag (for
+example `v3.0`), plus a `latest` tag that tracks the newest stable release.
+Pre-release tags (for example `-rc`, `-beta`, `-alpha`, or `-dev` suffixes) are
+published only with their explicit version strings (`3.1.0-rc1` and `v3.1.0-rc1`
+in this example) and do **not** advance `latest`. Pin the versioned tags when
+you need a specific build.
 
 ## Configure environment