feat: Add version format validation and multi-architecture verification

newbe36524 · claude · newbe36524 · commit 3f6bf4a14644 · 2026-02-28T13:20:00.000+08:00
This change implements automatic validation for version numbers and ensures
all published Docker images contain both amd64 and arm64 architectures.

## Version Format Validation
- Add `IsValidVersionFormat()` method in Build.Targets.VersionMonitor.cs
- Validate versions start with a digit (no 'v' prefix allowed)
- Validate versions contain only letters, numbers, dots, hyphens, underscores
- Skip invalid versions with warning logs in Version Monitor
- Add version format validation in Docker Build workflow with error messages

## Multi-Architecture Verification
- Verify all published images contain both linux/amd64 and linux/arm64
- Check Azure ACR images in "Verify Images in Registry" step
- Check Aliyun ACR images in "Verify Images in Aliyun ACR" step
- Fail workflow with clear error if either architecture is missing
- Verify all tags: version, major.minor, major, and latest (if stable)

## Documentation
- Update AGENTS.md with version format requirements and examples
- Update README.md with multi-architecture build notes
- Add detailed comments in workflow for validation behavior

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/.github/workflows/docker-build.yml b/.github/workflows/docker-build.yml
@@ -128,6 +128,18 @@ jobs:
           fi
           echo "version=${VERSION}" >> $GITHUB_OUTPUT
 
+          # Version format validation (skip for 'latest')
+          if [ "${VERSION}" != "latest" ]; then
+            # Version must start with a digit and contain only letters, numbers, dots, hyphens, or underscores
+            if ! [[ "${VERSION}" =~ ^[0-9][0-9A-Za-z._-]*$ ]]; then
+              echo "::error::Invalid version format '${VERSION}'"
+              echo "Version must start with a digit and only contain letters, numbers, dots, hyphens, or underscores."
+              echo "Example: 1.2.3, 1.2.3-beta.1"
+              exit 1
+            fi
+            echo "✓ Version format validated: ${VERSION}"
+          fi
+
           # Determine platform - default to 'all' if not specified
           if [ -z "${{ inputs.platform }}" ]; then
             # When platform is not specified or empty, default to 'all'
@@ -216,7 +228,7 @@ jobs:
         if: steps.config.outputs.version != 'latest'
         run: |
           VERSION="${{ steps.config.outputs.version }}"
-          # Remove v prefix for Docker image tags
+          # Remove v prefix for Docker image tags (for backward compatibility with tag push trigger)
           CLEAN_VERSION="${VERSION#v}"
           PLATFORM="${{ steps.config.outputs.platform }}"
           IMAGE_NAME="hagicode"
@@ -271,7 +283,7 @@ jobs:
         if: steps.config.outputs.version != 'latest' && (inputs.dry_run != 'true')
         run: |
           VERSION="${{ steps.config.outputs.version }}"
-          # Remove v prefix for tag operations
+          # Remove v prefix for tag operations (for backward compatibility with tag push trigger)
           CLEAN_VERSION="${VERSION#v}"
           IMAGE_NAME="hagicode"
           REGISTRY="${{ secrets.AZURE_ACR_REGISTRY }}"
@@ -310,8 +322,66 @@ jobs:
 
           echo "Verifying images in registry..."
 
-          docker manifest inspect ${REGISTRY}/${IMAGE_NAME}:${VERSION} || echo "Warning: Failed to verify version tag"
-          docker manifest inspect ${REGISTRY}/${IMAGE_NAME}:latest || echo "Warning: Failed to verify latest tag"
+          # Parse version parts for tag verification
+          MAJOR=$(echo ${VERSION} | cut -d. -f1)
+          MINOR=$(echo ${VERSION} | cut -d. -f2)
+
+          # Multi-architecture verification requirements:
+          # - All published images MUST contain both linux/amd64 and linux/arm64 architectures
+          # - Verification is done for each tag: version, major.minor, major, and latest (if stable)
+          # - If either architecture is missing, the workflow fails with a clear error message
+          # - This ensures users on both AMD64 and ARM64 platforms can pull compatible images
+
+          # Verify image architectures for each tag
+          for TAG in "${VERSION}" "${MAJOR}.${MINOR}" "${MAJOR}"; do
+            echo "Verifying tag: ${TAG}"
+
+            # Extract architecture list from manifest using jq
+            # jq is required for parsing the JSON output of docker manifest inspect
+            ARCHITECTURES=$(docker manifest inspect ${REGISTRY}/${IMAGE_NAME}:${TAG} 2>/dev/null | jq -r '.[].Platform[].architecture' 2>/dev/null || echo "")
+
+            if [ -z "${ARCHITECTURES}" ]; then
+              echo "::error::Failed to inspect manifest for tag ${TAG}"
+              exit 1
+            fi
+
+            echo "Found architectures for tag ${TAG}: ${ARCHITECTURES}"
+
+            # Check if amd64 is present (required for AMD64/x86_64 platforms)
+            if ! echo "${ARCHITECTURES}" | grep -q "amd64"; then
+              echo "::error::Tag ${TAG} does not contain amd64 architecture"
+              exit 1
+            fi
+
+            # Check if arm64 is present (required for ARM64/AArch64 platforms)
+            if ! echo "${ARCHITECTURES}" | grep -q "arm64"; then
+              echo "::error::Tag ${TAG} does not contain arm64 architecture"
+              exit 1
+            fi
+
+            echo "✓ Tag ${TAG} contains both amd64 and arm64 architectures"
+          done
+
+          # Verify latest tag only for stable releases
+          if [[ ! ${VERSION} =~ ^(rc|beta|alpha|preview|dev)[0-9]*$ ]] && [[ ! ${VERSION} =~ -(rc|beta|alpha|preview|dev) ]]; then
+            echo "Verifying tag: latest"
+            ARCHITECTURES=$(docker manifest inspect ${REGISTRY}/${IMAGE_NAME}:latest 2>/dev/null | jq -r '.[].Platform[].architecture' 2>/dev/null || echo "")
+
+            if [ -z "${ARCHITECTURES}" ]; then
+              echo "::warning::Failed to inspect manifest for tag latest (may not exist)"
+            else
+              echo "Found architectures for tag latest: ${ARCHITECTURES}"
+
+              if ! echo "${ARCHITECTURES}" | grep -q "amd64" || ! echo "${ARCHITECTURES}" | grep -q "arm64"; then
+                echo "::error::Tag latest does not contain both amd64 and arm64 architectures"
+                exit 1
+              fi
+
+              echo "✓ Tag latest contains both amd64 and arm64 architectures"
+            fi
+          fi
+
+          echo "All image tags verified successfully!"
 
       - name: Post Login to Edge ACR
         if: steps.config.outputs.version != 'latest' && (inputs.dry_run != 'true')
@@ -334,7 +404,7 @@ jobs:
         if: steps.config.outputs.version != 'latest' && (inputs.dry_run != 'true')
         run: |
           VERSION="${{ steps.config.outputs.version }}"
-          # Remove v prefix for Docker image tags
+          # Remove v prefix for Docker image tags (for backward compatibility with tag push trigger)
           CLEAN_VERSION="${VERSION#v}"
           IMAGE_NAME="hagicode"
           AZURE_REGISTRY="${{ secrets.AZURE_ACR_REGISTRY }}"
@@ -408,27 +478,45 @@ jobs:
 
           echo "Verifying images in Aliyun ACR..."
 
-          # Verify base image
-          echo "Checking base image..."
-          docker manifest inspect ${ALIYUN_IMAGE_NAME}:base || echo "Warning: Failed to verify base tag"
+          # Multi-architecture verification for Aliyun ACR:
+          # - Same requirements as Azure ACR: both amd64 and arm64 must be present
+          # - Verified for all pushed tags: version, major.minor, major, and latest (if stable)
+          # - Ensures Aliyun ACR images are also multi-arch compatible
 
-          # Verify version tag
-          echo "Checking version tag..."
-          docker manifest inspect ${ALIYUN_IMAGE_NAME}:${CLEAN_VERSION} || echo "Warning: Failed to verify version tag"
+          # Define tags to verify
+          TAGS=("${CLEAN_VERSION}" "${MAJOR}.${MINOR}" "${MAJOR}")
+          if [ "$IS_STABLE" = "true" ]; then
+            TAGS+=("latest")
+          fi
 
-          # Verify major.minor tag
-          echo "Checking major.minor tag..."
-          docker manifest inspect ${ALIYUN_IMAGE_NAME}:${MAJOR}.${MINOR} || echo "Warning: Failed to verify major.minor tag"
+          # Verify each tag's architectures
+          for TAG in "${TAGS[@]}"; do
+            echo "Verifying tag: ${TAG}"
 
-          # Verify major tag
-          echo "Checking major tag..."
-          docker manifest inspect ${ALIYUN_IMAGE_NAME}:${MAJOR} || echo "Warning: Failed to verify major tag"
+            # Extract architecture list from manifest using jq
+            ARCHITECTURES=$(docker manifest inspect ${ALIYUN_IMAGE_NAME}:${TAG} 2>/dev/null | jq -r '.[].Platform[].architecture' 2>/dev/null || echo "")
 
-          # Verify latest tag (only for stable releases)
-          if [ "$IS_STABLE" = "true" ]; then
-            echo "Checking latest tag..."
-            docker manifest inspect ${ALIYUN_IMAGE_NAME}:latest || echo "Warning: Failed to verify latest tag"
-          fi
+            if [ -z "${ARCHITECTURES}" ]; then
+              echo "::error::Failed to inspect manifest for tag ${TAG} in Aliyun ACR"
+              exit 1
+            fi
+
+            echo "Found architectures for tag ${TAG}: ${ARCHITECTURES}"
+
+            # Check if amd64 is present (required for AMD64/x86_64 platforms)
+            if ! echo "${ARCHITECTURES}" | grep -q "amd64"; then
+              echo "::error::Tag ${TAG} in Aliyun ACR does not contain amd64 architecture"
+              exit 1
+            fi
+
+            # Check if arm64 is present (required for ARM64/AArch64 platforms)
+            if ! echo "${ARCHITECTURES}" | grep -q "arm64"; then
+              echo "::error::Tag ${TAG} in Aliyun ACR does not contain arm64 architecture"
+              exit 1
+            fi
+
+            echo "✓ Tag ${TAG} contains both amd64 and arm64 architectures"
+          done
 
           echo "Aliyun ACR image verification completed!"
 
diff --git a/AGENTS.md b/AGENTS.md
@@ -111,6 +111,49 @@ AI agents are available in all Docker images pushed to registries, enabling:
 - Spec-driven workflows for changes
 - Multi-architecture support for AI tools
 
+## Version Format Requirements
+
+**Version Format Validation**: This repository enforces strict version number formatting to ensure consistency across the release pipeline.
+
+### Required Version Format
+
+All version numbers must:
+- **Start with a digit** (no "v" prefix allowed)
+- **Contain only** alphanumeric characters, dots (.), hyphens (-), or underscores (_)
+- **Follow semantic versioning** (semver) convention (e.g., `1.2.3`)
+
+### Valid Examples
+- `1.2.3` - Standard semver
+- `0.1.0` - Leading zero allowed
+- `1.2.3-beta.1` - Pre-release identifier
+- `1.2.3-rc.1` - Release candidate
+- `1.0.0-alpha` - Alpha release
+
+### Invalid Examples (will be rejected)
+- `v1.2.3` - v prefix is NOT allowed
+- `1.2.3 beta` - Contains space
+- `1.2.3@feature` - Contains special character @
+- `1/2/3` - Contains slash
+- `` - Empty string
+
+### Validation Points
+
+1. **Version Monitor** (`Build.Targets.VersionMonitor.cs`)
+   - Validates versions from Azure Blob Storage
+   - Skips invalid versions with warning logs
+
+2. **Docker Build Workflow** (`.github/workflows/docker-build.yml`)
+   - Validates version format in "Determine Version and Platform" step
+   - Fails workflow with clear error message if format is invalid
+
+### Error Message Example
+
+```
+Error: Invalid version format 'v1.2.3'
+Version must start with a digit and only contain letters, numbers, dots, hyphens, or underscores.
+Example: 1.2.3, 1.2.3-beta.1
+```
+
 ## Troubleshooting
 
 ### Claude Code Not Working
diff --git a/README.md b/README.md
@@ -22,6 +22,7 @@ The HagiCode release repository manages:
 - Azure Blob Storage access (SAS URL)
 - GitHub personal access token (PAT)
 - Edge ACR credentials (username, password, registry)
+- jq (for JSON parsing in multi-arch verification)
 
 ### Building Locally
 
@@ -30,7 +31,7 @@ The HagiCode release repository manages:
 git clone https://github.com/your-org/hagicode-release.git
 cd hagicode-release
 
-# Run Nuke build
+# Run Nuke build (use version without v prefix)
 ./build.sh DockerRelease \
   --ReleaseVersion "1.2.3" \
   --AzureBlobSasUrl "https://..." \
@@ -40,6 +41,17 @@ cd hagicode-release
   --DockerPlatform "all"
 ```
 
+### Version Format Requirements
+
+**Important**: Version numbers must NOT include a "v" prefix.
+
+- **Correct**: `1.2.3`, `1.2.3-beta.1`
+- **Incorrect**: `v1.2.3`, `1.2.3 beta`
+
+Version format is validated automatically in:
+1. Version Monitor (skips invalid versions with warning)
+2. Docker Build workflow (fails with error message)
+
 ## Build Targets
 
 ### Available Targets
@@ -366,7 +378,22 @@ docker run -v ~/claude-config:/claude-mount hagicode.azurecr.io/hagicode:1.2.3
 4. **App Dockerfile Generation**: Generate Dockerfile from template with version injection
 5. **Application Image Build**: Build application image with base image
 6. **Edge ACR Push**: Push images to registry with version tags
-7. **Verification**: Verify images are available in registry
+7. **Multi-Architecture Verification**: Verify images contain both amd64 and arm64 architectures
+8. **Aliyun ACR Sync**: Replicate images to Aliyun Container Registry with verification
+
+### Multi-Architecture Verification
+
+All published Docker images are verified to contain both linux/amd64 and linux/arm64 architectures:
+
+- **Azure ACR**: After push, `Verify Images in Registry` step checks manifest for both architectures
+- **Aliyun ACR**: After sync, `Verify Images in Aliyun ACR` step verifies all pushed tags
+
+If either architecture is missing, the workflow fails with a clear error message:
+```
+Error: Tag 1.2.3 does not contain amd64 architecture
+```
+
+This ensures users on both AMD64 and ARM64 platforms can pull compatible images.
 
 ### Version Tagging Strategy
 
diff --git a/nukeBuild/Build.Targets.VersionMonitor.cs b/nukeBuild/Build.Targets.VersionMonitor.cs
@@ -5,6 +5,7 @@
 using System.Diagnostics;
 using System.Linq;
 using System.Text.Json;
+using System.Text.RegularExpressions;
 
 /// <summary>
 /// Version Monitor target - monitors Azure Blob Storage for new versions and triggers GitHub releases
@@ -153,13 +154,47 @@ List<string> GetGitHubReleases(string token, string repository)
         }
     }
 
+    /// <summary>
+    /// Validates version format to ensure it conforms to Docker tag naming conventions.
+    /// Valid versions must start with a digit and contain only alphanumeric characters, dots, hyphens, or underscores.
+    /// This ensures version numbers do not have a "v" prefix which would cause inconsistencies in the build workflow.
+    /// </summary>
+    /// <param name="version">The version string to validate</param>
+    /// <returns>True if the version format is valid, false otherwise</returns>
+    bool IsValidVersionFormat(string version)
+    {
+        // Docker tag specification: only allows letters, numbers, dots, hyphens, underscores
+        // Must start with a digit (to ensure no "v" prefix)
+        if (string.IsNullOrWhiteSpace(version))
+            return false;
+
+        // Trim whitespace
+        var trimmedVersion = version.Trim();
+
+        // Must start with a digit (ensures no "v" prefix)
+        if (!char.IsDigit(trimmedVersion[0]))
+            return false;
+
+        // Allowed characters: numbers, letters, dots, hyphens, underscores
+        var allowedPattern = @"^[0-9A-Za-z._-]+$";
+        return Regex.IsMatch(trimmedVersion, allowedPattern);
+    }
+
     List<string> FindNewVersions(List<string> azureVersions, List<string> githubReleases)
     {
         var newVersions = new List<string>();
 
         foreach (var version in azureVersions)
         {
+            // Validate version format before processing
+            if (!IsValidVersionFormat(version))
+            {
+                Log.Warning("Skipping invalid version format: {Version} (must start with digit and contain only letters, numbers, dots, hyphens, or underscores)", version);
+                continue;
+            }
+
             // Check if this version (with or without 'v' prefix) exists in GitHub releases
+            // This is for backward compatibility with existing releases that may have v-prefixed tags
             var versionWithV = $"v{version}";
             var hasVersion = githubReleases.Contains(version, StringComparer.OrdinalIgnoreCase) ||
                            githubReleases.Contains(versionWithV, StringComparer.OrdinalIgnoreCase);
