Update common Docker engineering infrastructure with latest

Author: dotnet-docker-bot

eng/docker-tools/CHANGELOG.md

@@ -4,6 +4,16 @@ All breaking changes and new features in `eng/docker-tools` will be documented i
 
 ---
 
+## 2026-03-04: Pre-build validation gated by `preBuildTestScriptPath` variable
+
+The `PreBuildValidation` job condition now checks the new `preBuildTestScriptPath` variable instead of `testScriptPath`.
+This allows repos to independently control whether pre-build validation runs, without affecting functional tests.
+
+The new variable defaults to `$(testScriptPath)`, so existing repos that have pre-build tests are not affected.
+Repos that do not have pre-build tests can set `preBuildTestScriptPath` to `""` to skip the job entirely.
+
+---
+
 ## 2026-02-19: Separate Registry Endpoints from Authentication
 
 - Pull request: [#1945](https://github.com/dotnet/docker-tools/pull/1945)

eng/docker-tools/DEV-GUIDE.md

@@ -180,14 +180,16 @@ The `stages` variable is a comma-separated string that controls which pipeline s
 ```yaml
 variables:
 - name: stages
-  value: "build,test,publish"    # Run all stages
+  value: "build,test,sign,publish"    # Run all stages
 ```
 
 Common patterns:
-- `"build"` - Build only, no tests or publishing
-- `"build,test"` - Build and test, but don't publish
+- `"build"` - Build only, no tests, signing, or publishing
+- `"build,test"` - Build and test, but don't sign or publish
+- `"build,test,sign"` - Build, test, and sign, but don't publish
+- `"sign"` - Sign only (when re-running failed signing from a previous build)
 - `"publish"` - Publish only (when re-running a failed publish from a previous build)
-- `"build,test,publish"` - Full pipeline
+- `"build,test,sign,publish"` - Full pipeline
 
 **Note:** The `Post_Build` stage is implicitly included whenever `build` is in the stages list. You don't need to specify it separately—it automatically runs after Build to merge image info files and consolidate SBOMs.
 
@@ -372,11 +374,13 @@ Note: For simple retries of failed jobs, use the Azure Pipelines UI "Re-run fail
 
 | Scenario | stages | sourceBuildPipelineRunId |
 |----------|--------|--------------------------|
-| Normal full build | `"build,test,publish"` | `$(Build.BuildId)` (default) |
+| Normal full build | `"build,test,sign,publish"` | `$(Build.BuildId)` (default) |
 | Re-run publish after infra fix | `"publish"` | ID of the successful build run |
 | Re-test after infra fix | `"test"` | ID of the build run to test |
+| Re-sign after infra fix | `"sign"` | ID of the build run to sign |
 | Build only (no publish) | `"build"` | `$(Build.BuildId)` (default) |
 | Test + publish (skip build) | `"test,publish"` | ID of the build run |
+| Sign + publish (skip build/test) | `"sign,publish"` | ID of the build run |
 
 **In the Azure DevOps UI:**
 

eng/docker-tools/templates/jobs/post-build.yml

@@ -3,6 +3,7 @@ parameters:
   internalProjectName: null
   publicProjectName: null
   customInitSteps: []
+  publishConfig: null
 
 jobs:
 - job: Build
@@ -18,6 +19,7 @@ jobs:
     parameters:
       dockerClientOS: linux
       customInitSteps: ${{ parameters.customInitSteps }}
+      publishConfig: ${{ parameters.publishConfig }}
   - template: /eng/docker-tools/templates/steps/download-build-artifact.yml@self
     parameters:
       targetPath: $(Build.ArtifactStagingDirectory)

eng/docker-tools/templates/jobs/sign-images.yml

@@ -0,0 +1,58 @@
+# Signs container images using ESRP/Notary v2.
+# This job downloads the merged image-info artifact and signs all images listed in it.
+parameters:
+  pool: {}
+  internalProjectName: null
+  publicProjectName: null
+  customInitSteps: []
+  publishConfig: null
+  sourceBuildPipelineRunId: ""
+
+jobs:
+- job: Sign
+  pool: ${{ parameters.pool }}
+  variables:
+    imageInfoDir: $(Build.ArtifactStagingDirectory)/image-info
+  steps:
+
+  # Install MicroBuild signing plugin for ESRP container image signing
+  - template: /eng/docker-tools/templates/steps/init-signing-linux.yml@self
+    parameters:
+      signType: ${{ parameters.publishConfig.Signing.SignType }}
+      envFileVariableName: signingEnvFilePath
+
+  # Setup docker and ImageBuilder
+  - template: /eng/docker-tools/templates/steps/init-common.yml@self
+    parameters:
+      dockerClientOS: linux
+      setupImageBuilder: true
+      customInitSteps: ${{ parameters.customInitSteps }}
+      publishConfig: ${{ parameters.publishConfig }}
+      envFilePath: $(signingEnvFilePath)
+
+  # Download merged image-info artifact from Post_Build stage (or from a previous pipeline run)
+  - template: /eng/docker-tools/templates/steps/download-build-artifact.yml@self
+    parameters:
+      targetPath: $(imageInfoDir)
+      artifactName: image-info
+      pipelineRunId: ${{ parameters.sourceBuildPipelineRunId }}
+
+  - template: /eng/docker-tools/templates/steps/run-imagebuilder.yml@self
+    parameters:
+      displayName: 🔏 Sign Container Images
+      internalProjectName: ${{ parameters.internalProjectName }}
+      args: >-
+        signImages
+        $(artifactsPath)/image-info/image-info.json
+        --registry-override ${{ parameters.publishConfig.BuildRegistry.server }}
+        --repo-prefix ${{ parameters.publishConfig.BuildRegistry.repoPrefix }}
+
+  - template: /eng/docker-tools/templates/steps/run-imagebuilder.yml@self
+    parameters:
+      displayName: ✅ Verify Container Image Signatures
+      internalProjectName: ${{ parameters.internalProjectName }}
+      args: >-
+        verifySignatures
+        $(artifactsPath)/image-info/image-info.json
+        --registry-override ${{ parameters.publishConfig.BuildRegistry.server }}
+        --repo-prefix ${{ parameters.publishConfig.BuildRegistry.repoPrefix }}

eng/docker-tools/templates/jobs/test-images-linux-client.yml

@@ -17,7 +17,7 @@ jobs:
     strategy:
       matrix: $[ ${{ parameters.matrix }} ]
   ${{ if eq(parameters.preBuildValidation, 'true') }}:
-    condition: and(succeeded(), ne(variables.testScriptPath, ''))
+    condition: and(succeeded(), ne(variables.preBuildTestScriptPath, ''))
   pool: ${{ parameters.pool }}
   timeoutInMinutes: ${{ parameters.testJobTimeout }}
   steps:

eng/docker-tools/templates/stages/build-and-test.yml

@@ -220,6 +220,33 @@ stages:
       internalProjectName: ${{ parameters.internalProjectName }}
       publicProjectName: ${{ parameters.publicProjectName }}
       customInitSteps: ${{ parameters.customInitSteps }}
+      publishConfig: ${{ parameters.publishConfig }}
+
+################################################################################
+# Sign Images
+################################################################################
+- ${{ if eq(parameters.publishConfig.Signing.Enabled, true) }}:
+  - stage: Sign
+    dependsOn: Post_Build
+    condition: "
+      and(
+        ne(stageDependencies.Post_Build.outputs['Build.MergeImageInfoFiles.noImageInfos'], 'true'),
+        and(
+          contains(variables['stages'], 'sign'),
+          or(
+            and(
+              succeeded(),
+              contains(variables['stages'], 'build')),
+            not(contains(variables['stages'], 'build')))))"
+    jobs:
+    - template: /eng/docker-tools/templates/jobs/sign-images.yml@self
+      parameters:
+        pool: ${{ parameters.linuxAmd64Pool }}
+        internalProjectName: ${{ parameters.internalProjectName }}
+        publicProjectName: ${{ parameters.publicProjectName }}
+        customInitSteps: ${{ parameters.customInitSteps }}
+        publishConfig: ${{ parameters.publishConfig }}
+        sourceBuildPipelineRunId: ${{ parameters.sourceBuildPipelineRunId }}
 
 ################################################################################
 # Test Images

eng/docker-tools/templates/stages/dotnet/publish-config-nonprod.yml

@@ -38,6 +38,11 @@ parameters:
   type: object
   default: {}
 
+# Enable container image signing
+- name: enableSigning
+  type: boolean
+  default: false
+
 
 stages:
 - template: ${{ parameters.stagesTemplate }}
@@ -103,3 +108,12 @@ stages:
         id: $(test-nonprod.serviceConnection.id)
         clientId: $(test-nonprod.serviceConnection.clientId)
         tenantId: $(testTenant)
+
+      Signing:
+        Enabled: ${{ parameters.enableSigning }}
+        ImageSigningKeyCode: $(microBuildSigningKeyCode.testing)
+        ReferrerSigningKeyCode: $(microBuildSigningKeyCode.testing)
+        # Use signType 'real' even for non-prod to actually sign with the test certificate.
+        # The 'test' signType skips signing entirely on linux; the test keycode provides a non-production certificate.
+        SignType: real
+        TrustStoreName: test

eng/docker-tools/templates/stages/dotnet/publish-config-prod.yml

@@ -38,6 +38,11 @@ parameters:
   type: object
   default: {}
 
+# Enable container image signing
+- name: enableSigning
+  type: boolean
+  default: false
+
 
 stages:
 - template: ${{ parameters.stagesTemplate }}
@@ -103,3 +108,10 @@ stages:
         id: $(test.serviceConnection.id)
         clientId: $(test.serviceConnection.clientId)
         tenantId: $(test.serviceConnection.tenantId)
+
+      Signing:
+        Enabled: ${{ parameters.enableSigning }}
+        ImageSigningKeyCode: $(microBuildSigningKeyCode.containers)
+        ReferrerSigningKeyCode: $(microBuildSigningKeyCode.attestations)
+        SignType: real
+        TrustStoreName: supplychain

eng/docker-tools/templates/stages/publish.yml

@@ -33,39 +33,36 @@ stages:
   ${{ if eq(parameters.isStandalonePublish, true) }}:
     dependsOn: []
   ${{ else }}:
-    ${{ if and(eq(variables['System.TeamProject'], parameters.internalProjectName), ne(variables['Build.Reason'], 'PullRequest')) }}:
-      dependsOn: Test
-    ${{ else }}:
-      dependsOn: Post_Build
+    dependsOn:
+    - ${{ if eq(parameters.publishConfig.Signing.Enabled, true) }}:
+      - Sign
+    - ${{ if and(eq(variables['System.TeamProject'], parameters.internalProjectName), ne(variables['Build.Reason'], 'PullRequest')) }}:
+      - Test
+    - ${{ else }}:
+      - Post_Build
+  # Run when all of the following are true:
+  # 1. The pipeline has not been canceled.
+  # 2. The stages variable includes 'publish'.
+  # 3. Either signing is not enabled, or the Sign stage succeeded.
+  # 4. Either the stages variable does not include 'build', or Post_Build succeeded.
+  # 5. Either the stages variable does not include 'test', or Test succeeded/was skipped.
   condition: "
     and(
       not(canceled()),
-      and(
-        contains(variables['stages'], 'publish'),
-        or(
-          or(
-            and(
-              and(
-                contains(variables['stages'], 'build'),
-                succeeded('Post_Build')),
-              and(
-                contains(variables['stages'], 'test'),
-                in(dependencies.Test.result, 'Succeeded', 'SucceededWithIssues', 'Skipped'))),
-            or(
-              and(
-                not(contains(variables['stages'], 'build')),
-                and(
-                  contains(variables['stages'], 'test'),
-                  in(dependencies.Test.result, 'Succeeded', 'SucceededWithIssues', 'Skipped'))),
-              and(
-                not(contains(variables['stages'], 'test')),
-                and(
-                  contains(variables['stages'], 'build'),
-                  succeeded('Post_Build'))))),
-          not(
-            or(
-              contains(variables['stages'], 'build'),
-              contains(variables['stages'], 'test'))))))"
+      contains(variables['stages'], 'publish'),
+      or(
+        ne(lower('${{ parameters.publishConfig.Signing.Enabled }}'), 'true'),
+        in(dependencies.Sign.result, 'Succeeded', 'SucceededWithIssues')
+      ),
+      or(
+        not(contains(variables['stages'], 'build')),
+        succeeded('Post_Build')
+      ),
+      or(
+        not(contains(variables['stages'], 'test')),
+        in(dependencies.Test.result, 'Succeeded', 'SucceededWithIssues', 'Skipped')
+      )
+    )"
   jobs:
   - template: /eng/docker-tools/templates/jobs/publish.yml@self
     parameters:

eng/docker-tools/templates/steps/generate-appsettings.yml

@@ -1,17 +1,31 @@
 # .NET Microsoft.Extensions.Configuration reads appsettings.json from the working directory
 # where ImageBuilder is run. Place it in the repo root so it will be available at runtime.
 parameters:
+# See:
+# - publish-config-prod.yml
+# - publish-config-nonprod.yml
+# - PublishConfiguration.cs
 - name: publishConfig
   type: object
+# This should be the path to $(Build.ArtifactStagingDirectory). It is parameterized
+# here since it is mounted into the ImageBuilder container at runtime.
+- name: artifactStagingDirectory
+  type: string
+  default: ""
 - name: condition
   type: string
   default: "true"
 
 steps:
 - powershell: |-
+    # Escape backslashes for JSON compatibility (Windows paths like D:\a\_work become D:\\a\\_work)
+    $artifactStagingDirectory = "${{ parameters.artifactStagingDirectory }}" -replace '\\', '\\'
     $appsettingsJsonContent = @"
     {
-      "PublishConfiguration": ${{ convertToJson(parameters.publishConfig) }}
+      "PublishConfiguration": ${{ convertToJson(parameters.publishConfig) }},
+      "BuildConfiguration": {
+        "ArtifactStagingDirectory": "$artifactStagingDirectory"
+      }
     }
     "@
     Set-Content -Path "appsettings.json" -Value $appsettingsJsonContent