feat(workflows): validate latest source branches

.github/workflows/_publish_image_reusable.yml

@@ -19,6 +19,11 @@ on:
         description: "source branch name"
         required: true
         type: string
+      validation_only:
+        description: "build without image or cache writes"
+        required: false
+        default: false
+        type: boolean
       build_matrix_json:
         description: "build matrix JSON array"
         required: true
@@ -74,6 +79,7 @@ jobs:
       source_sha: ${{ steps.prepare.outputs.source_sha }}
       checkout_ref: ${{ steps.prepare.outputs.checkout_ref }}
       version_tag: ${{ steps.prepare.outputs.version_tag }}
+      publish_images: ${{ steps.prepare.outputs.publish_images }}
     steps:
     - name: Resolve mode and source ref
       id: prepare
@@ -82,6 +88,7 @@ jobs:
         REPOSITORY_URL: ${{ inputs.repository_url }}
         BRANCH: ${{ inputs.branch }}
         ENABLE_HASH_GATE: ${{ inputs.enable_hash_gate }}
+        VALIDATION_ONLY: ${{ inputs.validation_only }}
         LAST_HASH_VALUE: ${{ inputs.last_hash_value }}
       run: |
         set -euo pipefail
@@ -98,6 +105,10 @@ jobs:
         fi
 
         checkout_ref="$source_sha"
+        publish_images="true"
+        if [ "$VALIDATION_ONLY" = "true" ]; then
+          publish_images="false"
+        fi
 
         if [ "$MODE" = "latest" ]; then
           version_tag="latest"
@@ -118,6 +129,7 @@ jobs:
           echo "source_sha=$source_sha"
           echo "checkout_ref=$checkout_ref"
           echo "version_tag=$version_tag"
+          echo "publish_images=$publish_images"
           echo "need_update=$need_update"
         } >> "$GITHUB_OUTPUT"
 
@@ -142,6 +154,7 @@ jobs:
         PLATFORMS_LATEST: ${{ matrix.platforms_latest }}
         PLATFORMS_RELEASE: ${{ matrix.platforms_release }}
         REGISTRY_CACHE_IMAGE: ${{ matrix.registry_cache_image || '' }}
+        PUBLISH_IMAGES: ${{ needs.prepare.outputs.publish_images }}
       run: |
         set -euo pipefail
 
@@ -172,6 +185,11 @@ jobs:
           cache_backend="gha"
         fi
 
+        if [ "$PUBLISH_IMAGES" != "true" ]; then
+          cache_to_min=""
+          cache_to_max=""
+        fi
+
         {
           echo "image_url=$image_url"
           echo "platforms=$platforms"
@@ -188,6 +206,8 @@ jobs:
           echo "| Image | Platforms | Cache backend | Cache reference |"
           echo "| --- | --- | --- | --- |"
           echo "| \`${image_url}\` | \`${platforms}\` | \`${cache_backend}\` | \`${REGISTRY_CACHE_IMAGE:-$cache_scope}\` |"
+          echo
+          echo "- Publish images: \`${PUBLISH_IMAGES}\`"
         } >> "$GITHUB_STEP_SUMMARY"
 
     - name: Checkout source (${{ matrix.module }})
@@ -262,7 +282,7 @@ jobs:
         context: ${{ matrix.context }}
         file: ${{ matrix.dockerfile }}
         platforms: ${{ steps.params.outputs.platforms }}
-        push: true
+        push: ${{ needs.prepare.outputs.publish_images == 'true' }}
         tags: ${{ steps.params.outputs.image_url }}
         cache-from: ${{ steps.params.outputs.cache_from }}
         cache-to: ${{ steps.params.outputs.cache_to_max }}
@@ -275,14 +295,14 @@ jobs:
         context: ${{ matrix.context }}
         file: ${{ matrix.dockerfile }}
         platforms: ${{ steps.params.outputs.platforms }}
-        push: true
+        push: ${{ needs.prepare.outputs.publish_images == 'true' }}
         tags: ${{ steps.params.outputs.image_url }}
         cache-from: ${{ steps.params.outputs.cache_from }}
         cache-to: ${{ steps.params.outputs.cache_to_max }}
 
   update_latest_hash:
     needs: [prepare, publish]
-    if: ${{ inputs.mode == 'latest' && inputs.enable_hash_gate && needs.prepare.outputs.need_update == 'true' && needs.publish.result == 'success' }}
+    if: ${{ inputs.mode == 'latest' && !inputs.validation_only && inputs.enable_hash_gate && needs.prepare.outputs.need_update == 'true' && needs.publish.result == 'success' }}
     runs-on: ubuntu-latest
     steps:
     - name: Validate hash update inputs

.github/workflows/_publish_pd_store_server_reusable.yml

@@ -71,6 +71,8 @@ jobs:
       need_update: ${{ steps.prepare.outputs.need_update }}
       source_sha: ${{ steps.prepare.outputs.source_sha }}
       version_tag: ${{ steps.prepare.outputs.version_tag }}
+      cache_channel: ${{ steps.prepare.outputs.cache_channel }}
+      publish_images: ${{ steps.prepare.outputs.publish_images }}
       build_matrix_json: ${{ steps.prepare.outputs.build_matrix_json }}
     steps:
     - name: Resolve mode and source ref
@@ -96,7 +98,24 @@ jobs:
         fi
 
         if [ "$MODE" = "latest" ]; then
-          version_tag="latest"
+          if [ "$BRANCH" = "master" ]; then
+            version_tag="latest"
+            publish_images="true"
+          else
+            safe_branch="$(
+              printf '%s' "$BRANCH" \
+              | tr '[:upper:]' '[:lower:]' \
+              | sed -E 's/[^a-z0-9_.-]+/-/g; s/^[.-]+//; s/[.-]+$//' \
+              | cut -c1-110
+            )"
+            if [ -z "$safe_branch" ]; then
+              echo "Failed to derive an image tag from branch: $BRANCH"
+              exit 1
+            fi
+            version_tag="branch-${safe_branch}"
+            publish_images="false"
+          fi
+          cache_channel="latest"
           need_update="true"
           if [ "$ENABLE_HASH_GATE" = "true" ] && [ "$source_sha" = "$LAST_HASH_VALUE" ]; then
             need_update="false"
@@ -108,11 +127,15 @@ jobs:
             exit 1
           fi
           need_update="true"
+          cache_channel="release"
+          publish_images="true"
         fi
 
         {
           echo "source_sha=$source_sha"
           echo "version_tag=$version_tag"
+          echo "cache_channel=$cache_channel"
+          echo "publish_images=$publish_images"
           echo "need_update=$need_update"
           echo "build_matrix_json<<EOF"
           cat <<'JSON'
@@ -148,19 +171,25 @@ jobs:
 
     - name: Summarize build cache strategy
       env:
-        MODE: ${{ inputs.mode }}
+        CACHE_CHANNEL: ${{ steps.prepare.outputs.cache_channel }}
+        PUBLISH_IMAGES: ${{ steps.prepare.outputs.publish_images }}
       run: |
         {
           echo "## PD / Store / Server image build"
           echo
           echo "- Cache backend: Docker Hub registry (BuildKit, mode=max)"
-          echo "- Cache channel: \`$MODE\`"
-          echo "- Cache writers: integration precheck and amd64 publish jobs"
+          echo "- Cache channel: \`$CACHE_CHANNEL\`"
+          echo "- Publish images: \`$PUBLISH_IMAGES\`"
+          if [ "$PUBLISH_IMAGES" = "true" ]; then
+            echo "- Cache writers: integration precheck and amd64 publish jobs"
+          else
+            echo "- Cache policy: read-only validation (no registry exports)"
+          fi
           echo "- Cache reader: arm64 publish jobs"
-          echo "- PD: \`hugegraph/pd:buildcache-$MODE\`"
-          echo "- Store: \`hugegraph/store:buildcache-$MODE\`"
-          echo "- Server (HStore): \`hugegraph/server:buildcache-$MODE\`"
-          echo "- Server (standalone): \`hugegraph/hugegraph:buildcache-$MODE\`"
+          echo "- PD: \`hugegraph/pd:buildcache-$CACHE_CHANNEL\`"
+          echo "- Store: \`hugegraph/store:buildcache-$CACHE_CHANNEL\`"
+          echo "- Server (HStore): \`hugegraph/server:buildcache-$CACHE_CHANNEL\`"
+          echo "- Server (standalone): \`hugegraph/hugegraph:buildcache-$CACHE_CHANNEL\`"
         } >> "$GITHUB_STEP_SUMMARY"
 
   integration_precheck:
@@ -211,8 +240,8 @@ jobs:
         platforms: linux/amd64
         load: true
         tags: hg-ci/pd:precheck
-        cache-from: type=registry,ref=hugegraph/pd:buildcache-${{ inputs.mode }}
-        cache-to: type=registry,ref=hugegraph/pd:buildcache-${{ inputs.mode }},mode=max
+        cache-from: type=registry,ref=hugegraph/pd:buildcache-${{ needs.prepare.outputs.cache_channel }}
+        cache-to: ${{ needs.prepare.outputs.publish_images == 'true' && format('type=registry,ref=hugegraph/pd:buildcache-{0},mode=max', needs.prepare.outputs.cache_channel) || '' }}
         build-args: ${{ env.MVN_ARGS }}
 
     - name: Build x86 Store image for integration check
@@ -223,8 +252,8 @@ jobs:
         platforms: linux/amd64
         load: true
         tags: hg-ci/store:precheck
-        cache-from: type=registry,ref=hugegraph/store:buildcache-${{ inputs.mode }}
-        cache-to: type=registry,ref=hugegraph/store:buildcache-${{ inputs.mode }},mode=max
+        cache-from: type=registry,ref=hugegraph/store:buildcache-${{ needs.prepare.outputs.cache_channel }}
+        cache-to: ${{ needs.prepare.outputs.publish_images == 'true' && format('type=registry,ref=hugegraph/store:buildcache-{0},mode=max', needs.prepare.outputs.cache_channel) || '' }}
         build-args: ${{ env.MVN_ARGS }}
 
     - name: Build x86 Server(hstore) image for integration check
@@ -235,8 +264,8 @@ jobs:
         platforms: linux/amd64
         load: true
         tags: hg-ci/server:precheck
-        cache-from: type=registry,ref=hugegraph/server:buildcache-${{ inputs.mode }}
-        cache-to: type=registry,ref=hugegraph/server:buildcache-${{ inputs.mode }},mode=max
+        cache-from: type=registry,ref=hugegraph/server:buildcache-${{ needs.prepare.outputs.cache_channel }}
+        cache-to: ${{ needs.prepare.outputs.publish_images == 'true' && format('type=registry,ref=hugegraph/server:buildcache-{0},mode=max', needs.prepare.outputs.cache_channel) || '' }}
         build-args: ${{ env.MVN_ARGS }}
 
     - name: Start compose stack with local images
@@ -307,15 +336,15 @@ jobs:
       SOURCE_SHA: ${{ needs.prepare.outputs.source_sha }}
       VERSION_TAG: ${{ needs.prepare.outputs.version_tag }}
       MVN_ARGS: ${{ inputs.mvn_args }}
-      MODE: ${{ inputs.mode }}
+      CACHE_CHANNEL: ${{ needs.prepare.outputs.cache_channel }}
     steps:
     - name: Resolve tags (${{ matrix.module }})
       id: tags
       env:
         IMAGE_REPO: ${{ matrix.image_repo }}
       run: |
         image_amd64="${IMAGE_REPO}:${VERSION_TAG}-amd64"
-        module_cache_ref="${IMAGE_REPO}:buildcache-${MODE}"
+        module_cache_ref="${IMAGE_REPO}:buildcache-${CACHE_CHANNEL}"
 
         {
           echo "image_amd64=$image_amd64"
@@ -350,7 +379,7 @@ jobs:
         load: true
         tags: ${{ steps.tags.outputs.image_amd64 }}
         cache-from: type=registry,ref=${{ steps.tags.outputs.module_cache_ref }}
-        cache-to: type=registry,ref=${{ steps.tags.outputs.module_cache_ref }},mode=max
+        cache-to: ${{ needs.prepare.outputs.publish_images == 'true' && format('type=registry,ref={0},mode=max', steps.tags.outputs.module_cache_ref) || '' }}
         build-args: ${{ env.MVN_ARGS }}
 
     - name: Build and push amd64 image (${{ matrix.module }})
@@ -360,10 +389,10 @@ jobs:
         context: .
         file: ${{ matrix.dockerfile }}
         platforms: linux/amd64
-        push: true
+        push: ${{ needs.prepare.outputs.publish_images == 'true' }}
         tags: ${{ steps.tags.outputs.image_amd64 }}
         cache-from: type=registry,ref=${{ steps.tags.outputs.module_cache_ref }}
-        cache-to: type=registry,ref=${{ steps.tags.outputs.module_cache_ref }},mode=max
+        cache-to: ${{ needs.prepare.outputs.publish_images == 'true' && format('type=registry,ref={0},mode=max', steps.tags.outputs.module_cache_ref) || '' }}
         build-args: ${{ env.MVN_ARGS }}
 
     - name: Smoke test standalone server amd64
@@ -380,7 +409,7 @@ jobs:
         curl -fsS http://127.0.0.1:18080 >/dev/null || exit 1
 
     - name: Push tested amd64 image (${{ matrix.module }})
-      if: ${{ matrix.smoke_test }}
+      if: ${{ matrix.smoke_test && needs.prepare.outputs.publish_images == 'true' }}
       env:
         IMAGE_URL: ${{ steps.tags.outputs.image_amd64 }}
       run: |
@@ -404,15 +433,15 @@ jobs:
       SOURCE_SHA: ${{ needs.prepare.outputs.source_sha }}
       VERSION_TAG: ${{ needs.prepare.outputs.version_tag }}
       MVN_ARGS: ${{ inputs.mvn_args }}
-      MODE: ${{ inputs.mode }}
+      CACHE_CHANNEL: ${{ needs.prepare.outputs.cache_channel }}
     steps:
     - name: Resolve tags (${{ matrix.module }})
       id: tags
       env:
         IMAGE_REPO: ${{ matrix.image_repo }}
       run: |
         image_arm64="${IMAGE_REPO}:${VERSION_TAG}-arm64"
-        module_cache_ref="${IMAGE_REPO}:buildcache-${MODE}"
+        module_cache_ref="${IMAGE_REPO}:buildcache-${CACHE_CHANNEL}"
 
         {
           echo "image_arm64=$image_arm64"
@@ -446,14 +475,14 @@ jobs:
         context: .
         file: ${{ matrix.dockerfile }}
         platforms: linux/arm64
-        push: true
+        push: ${{ needs.prepare.outputs.publish_images == 'true' }}
         tags: ${{ steps.tags.outputs.image_arm64 }}
         cache-from: type=registry,ref=${{ steps.tags.outputs.module_cache_ref }}
         build-args: ${{ env.MVN_ARGS }}
 
   publish_manifest:
     needs: [prepare, publish_amd64, publish_arm64]
-    if: ${{ needs.prepare.outputs.need_update == 'true' && needs.publish_amd64.result == 'success' && needs.publish_arm64.result == 'success' }}
+    if: ${{ needs.prepare.outputs.need_update == 'true' && needs.prepare.outputs.publish_images == 'true' && needs.publish_amd64.result == 'success' && needs.publish_arm64.result == 'success' }}
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -579,7 +608,7 @@ jobs:
 
   update_latest_hash:
     needs: [prepare, publish_manifest]
-    if: ${{ inputs.mode == 'latest' && inputs.enable_hash_gate && needs.prepare.outputs.need_update == 'true' && needs.publish_manifest.result == 'success' }}
+    if: ${{ inputs.mode == 'latest' && inputs.branch == 'master' && inputs.enable_hash_gate && needs.prepare.outputs.need_update == 'true' && needs.publish_manifest.result == 'success' }}
     runs-on: ubuntu-latest
     steps:
     - name: Validate hash update inputs

.github/workflows/publish_latest_ai_image.yml

@@ -4,6 +4,11 @@ on:
   schedule:
     - cron: '0 23 * * *'
   workflow_dispatch:
+    inputs:
+      latest_source_branch:
+        required: false
+        default: 'main'
+        description: 'source branch; non-main branches run read-only validation'
 
 jobs:
   publish:
@@ -12,7 +17,8 @@ jobs:
       mode: latest
       component: ai
       repository_url: apache/hugegraph-ai
-      branch: main
+      branch: ${{ github.event.inputs.latest_source_branch || 'main' }}
+      validation_only: ${{ github.event_name == 'workflow_dispatch' && (github.event.inputs.latest_source_branch || 'main') != 'main' }}
       # IMPORTANT:
       # - Keep ARM enabled for normal RAG image (Dockerfile.llm).
       # - Keep rag-bin (Dockerfile.nk) on amd64 only due to arm incompatibility.
@@ -24,6 +30,7 @@ jobs:
             "dockerfile": "./docker/Dockerfile.llm",
             "image_repo_latest": "hugegraph/rag",
             "image_repo_release": "hugegraph/rag",
+            "registry_cache_image": "hugegraph/rag:buildcache-latest",
             "platforms_latest": "linux/amd64,linux/arm64",
             "platforms_release": "linux/amd64,linux/arm64",
             "smoke_test": false
@@ -34,12 +41,13 @@ jobs:
             "dockerfile": "./docker/Dockerfile.nk",
             "image_repo_latest": "hugegraph/rag-bin",
             "image_repo_release": "hugegraph/rag-bin",
+            "registry_cache_image": "hugegraph/rag-bin:buildcache-latest",
             "platforms_latest": "linux/amd64",
             "platforms_release": "linux/amd64",
             "smoke_test": false
           }
         ]
-      enable_hash_gate: true
+      enable_hash_gate: ${{ github.event_name != 'workflow_dispatch' || (github.event.inputs.latest_source_branch || 'main') == 'main' }}
       last_hash_value: ${{ vars.LAST_AI_HASH }}
       last_hash_name: LAST_AI_HASH
       hash_repo_owner: hugegraph

.github/workflows/publish_latest_hubble_image.yml

@@ -5,6 +5,10 @@ on:
     - cron: '0 23 * * *'
   workflow_dispatch:
     inputs:
+      latest_source_branch:
+        required: false
+        default: 'master'
+        description: 'source branch; non-master branches run read-only validation'
       mvn_args:
         required: false
         default: ''
@@ -17,7 +21,8 @@ jobs:
       mode: latest
       component: hubble
       repository_url: apache/hugegraph-toolchain
-      branch: master
+      branch: ${{ github.event.inputs.latest_source_branch || 'master' }}
+      validation_only: ${{ github.event_name == 'workflow_dispatch' && (github.event.inputs.latest_source_branch || 'master') != 'master' }}
       build_matrix_json: |
         [
           {
@@ -34,7 +39,7 @@ jobs:
         ]
       use_mvn_args: true
       mvn_args: ${{ github.event.inputs.mvn_args || '' }}
-      enable_hash_gate: true
+      enable_hash_gate: ${{ github.event_name != 'workflow_dispatch' || (github.event.inputs.latest_source_branch || 'master') == 'master' }}
       last_hash_value: ${{ vars.LAST_HUBBLE_HASH }}
       last_hash_name: LAST_HUBBLE_HASH
       hash_repo_owner: hugegraph