Eliminate untagged versions for single-platform builds

Co-authored-by: neilime <314088+neilime@users.noreply.github.com>

Author: Copilot

.github/workflows/__test-workflow-docker-build-images.yml

@@ -164,10 +164,9 @@ jobs:
             const expectedTaggedVersions = isSigned ? 2 : 1;
 
             // Expected untagged versions:
-            // - For single platform: 1 (the digest-only push from build step)
+            // - For single platform: 0 (no untagged versions when optimized)
             // - For multi platform: number of platforms (one per platform digest-only push)
-            // Note: The build step uses push-by-digest which creates untagged versions
-            const expectedUntaggedVersions = platforms.length;
+            const expectedUntaggedVersions = isSinglePlatform ? 0 : platforms.length;
 
             assert.equal(
               taggedVersions.length,

.github/workflows/docker-build-images.yml

@@ -310,6 +310,8 @@ jobs:
                   ...image,
                   platform: platformName,
                   "runs-on": platformRunsOn,
+                  // For single-platform builds, don't use push-by-digest to avoid untagged versions
+                  "push-by-digest": platforms.length > 1,
                 };
                 imagesByPlatform.push(imageByPlatform);
               }
@@ -425,6 +427,7 @@ jobs:
           secret-envs: ${{ steps.prepare-secret-envs.outputs.secret-envs }}
           secrets: ${{ secrets.build-secrets }}
           cache-type: ${{ inputs.cache-type }}
+          push-by-digest: ${{ matrix.image.push-by-digest }}
 
       # FIXME: Set built images infos in file to be uploaded as artifacts, because github action does not handle job outputs for matrix
       # https://github.com/orgs/community/discussions/26639

actions/docker/build-image/action.yml

@@ -87,6 +87,13 @@ inputs:
       See https://docs.docker.com/build/cache/backends.
     default: "gha"
     required: false
+  push-by-digest:
+    description: |
+      Whether to push by digest only (without tags).
+      Set to false for single-platform builds to avoid creating untagged versions.
+      Set to true for multi-platform builds (required for manifest creation).
+    default: "true"
+    required: false
 
 outputs:
   built-image:
@@ -297,7 +304,7 @@ runs:
         # FIXME: Remove 'inputs.cache-type == 'gha' && steps.transform-cache-gha.outputs.cache-to ||'
         # when https://github.com/int128/docker-build-cache-config-action/pull/1213 is merged
         cache-to: ${{ inputs.cache-type == 'gha' && steps.transform-cache-gha.outputs.cache-to || steps.cache-arguments.outputs.cache-to }}
-        outputs: type=image,push-by-digest=true,name-canonical=true,push=true
+        outputs: ${{ inputs.push-by-digest == 'true' && 'type=image,push-by-digest=true,name-canonical=true,push=true' || 'type=image,push=true' }}
         labels: ${{ steps.metadata.outputs.labels }}
         annotations: ${{ steps.metadata.outputs.annotations }}
         tags: ${{ steps.metadata.outputs.image }}

actions/docker/create-images-manifests/action.yml

@@ -125,15 +125,15 @@ runs:
 
           // Helper function to tag single-platform image
           async function tagSinglePlatformImage(builtImage, imagesWithTags) {
-            core.info(`Skipping multiarch manifest creation for "${builtImage.name}" (single platform: ${builtImage.platforms[0] || 'none'})`);
+            core.info(`Tagging single-platform image "${builtImage.name}" (skipping multiarch manifest creation)`);
 
             validateImage(builtImage);
 
             const sourceImage = builtImage.images[0];
             for (const targetImage of imagesWithTags) {
               const tagCommand = `docker buildx imagetools create --tag ${targetImage} ${sourceImage}`;
               await exec.exec(tagCommand);
-              core.debug(`Tag single-platform image "${builtImage.name}" ("${tagCommand}") executed`);
+              core.debug(`Tagged single-platform image "${builtImage.name}"`);
             }
 
             builtImage.images = imagesWithTags;
@@ -173,7 +173,19 @@ runs:
             return new Promise(async (resolve, reject) => {
               try {
                 if (builtImage.platforms.length <= 1) {
-                  await tagSinglePlatformImage(builtImage, imagesWithTags);
+                  // For single-platform builds pushed with tags (not by digest),
+                  // the image reference already includes the tag, so we just need to update the images array
+                  const sourceImage = builtImage.images[0];
+                  const isPushedByDigest = sourceImage.match(/@sha256:[a-f0-9]{64}$/) && !sourceImage.match(/:[^:@]+@sha256:/);
+
+                  if (isPushedByDigest) {
+                    // Image was pushed by digest only, need to tag it
+                    await tagSinglePlatformImage(builtImage, imagesWithTags);
+                  } else {
+                    // Image was already pushed with tags, just ensure images array is updated
+                    core.info(`Single-platform image "${builtImage.name}" was already pushed with tags`);
+                    builtImage.images = imagesWithTags;
+                  }
                 } else {
                   await createMultiarchManifest(builtImage, imagesWithTags);
                 }