[main] Update common Docker engineering infrastructure with latest (#7098)

Author: dotnet-docker-bot

eng/docker-tools/CHANGELOG.md

@@ -4,6 +4,17 @@ All breaking changes and new features in `eng/docker-tools` will be documented i
 
 ---
 
+## 2026-03-18: CG build template supports skipping .NET SDK installation
+
+- Issue: [#2029](https://github.com/dotnet/docker-tools/issues/2029)
+
+`cg-build-projects.yml` now accepts `skipDotNetInstall` (boolean, default `false`) and
+`initSteps` (stepList, default `[]`) parameters. Setting `skipDotNetInstall: true` skips
+the built-in SDK installation. Setting `initSteps` will execute those custom steps
+at the beginning of the job.
+
+---
+
 ## 2026-03-12: Service connection OIDC changes
 
 - Pull request: [#2013](https://github.com/dotnet/docker-tools/pull/2013)

eng/docker-tools/DEV-GUIDE.md

@@ -171,7 +171,7 @@ The `generateBuildMatrix` command is key to understanding how builds are paralle
 1. **Reads the manifest.json** - Understands which images exist
 2. **Builds a dependency graph** - Knows that `runtime-deps` must build before `runtime`
 3. **Groups by platform** - Creates jobs for each OS/Architecture combo
-4. **Optimizes with caching** - Can detect and exclude unchanged images
+4. **Optimizes with caching** - Can detect and exclude unchanged images (see [Image Caching](#image-caching) below)
 
 ### Controlling Which Build Stages Run
 
@@ -338,6 +338,34 @@ The `autobuilder` label is how the infrastructure tracks that the failure cycle
 
 ---
 
+### Image Caching
+
+The infrastructure includes caching to avoid rebuilding images that haven't changed. Caching operates at two levels:
+
+**1. Matrix Trimming (job-level caching)**
+
+When `trimCachedImagesForMatrix` is enabled, the `generateBuildMatrix` command excludes platforms from the build matrix if they would result in cache hits. This means no build job is even created for those platforms—they're completely skipped.
+
+**2. Build-time Caching**
+
+Even if a platform isn't trimmed from the matrix, the `build` command checks each image against the cache before building. If the image is cached, it outputs `CACHE HIT`, pulls the previously-built image from the registry, and skips the actual Docker build.
+
+#### Cache Conditions
+
+An image is considered cached when **both** of the following conditions are true:
+
+1. **Base image digest is unchanged** — The digest of the base image (FROM image) matches the digest recorded in the image info file from the last successful publish. If the upstream base image has been updated, this condition fails and the image will be rebuilt.
+
+2. **Dockerfile commit is unchanged** — The git commit URL for the Dockerfile matches the commit URL recorded in the image info file. If you've modified the Dockerfile, this condition fails and the image will be rebuilt.
+
+Caching compares against the published image info stored in the [versions repo](https://github.com/dotnet/versions). This means caching compares against what's been officially published, not what's in your current branch.
+
+#### Disabling Caching
+
+To force a rebuild regardless of cache state, set the `noCache` parameter to `true` when queuing the build. This disables both matrix trimming and build-time caching.
+
+---
+
 ## Common Customization Patterns
 
 ### Pattern: Adding Build Arguments
@@ -389,3 +417,59 @@ When you queue a new run, you can override these as runtime parameters:
 2. Set `sourceBuildPipelineRunId` to the run ID containing the artifacts you need (find the build ID in the URL when viewing a pipeline run, e.g., `buildId=123456`)
 
 This avoids the multi-hour rebuild cycle when you just need to retry a failed operation.
+
+---
+
+## Troubleshooting
+
+### Why isn't my Dockerfile being built?
+
+When you trigger a pipeline run, you might find that your Dockerfile isn't being built.
+
+#### Symptom 1: The Dockerfile isn't included in any build job
+
+If your Dockerfile doesn't appear in any build job, first verify the Dockerfile is included in the manifest file.
+
+**How to verify:** Check `manifest.json` to ensure your Dockerfile path is defined under the appropriate repo and image. You can also run `generateBuildMatrix` locally to see which Dockerfiles are included:
+
+```powershell
+./eng/docker-tools/Invoke-ImageBuilder.ps1 "generateBuildMatrix --manifest manifest.json --type platformDependencyGraph"
+```
+
+**How to fix:** Add the Dockerfile to `manifest.json` under the correct repo, image, and platform configuration.
+
+#### Symptom 2: The pipeline job isn't running at all
+
+If the Dockerfile is in the manifest but you don't see a build job for it, the build matrix was likely trimmed due to [matrix trimming](#image-caching).
+
+**How to verify:** Look at the "Generate platformDependencyGraph Matrix" step output in the `GenerateBuildMatrix` job. This is an example of what the output in that step looks like:
+
+```yaml
+windowsLtsc2025Amd64:
+  src-windowsservercore-ltsc2025-helix-graph:
+    imageBuilderPaths: --path src/windowsservercore/ltsc2025/helix/amd64 --path src/windowsservercore/ltsc2025/helix/webassembly-net8/amd64 --path src/windowsservercore/ltsc2025/helix/webassembly/amd64
+    legName: windows-ltsc2025amd64src-windowsservercore-ltsc2025-helix-graph
+    osType: windows
+    architecture: amd64
+    osVersions: --os-version windowsservercore-ltsc2025
+```
+
+If your Dockerfile path doesn't appear in any of the matrix legs, it was trimmed.
+
+**How to fix:** Set the `noCache` parameter to `true` when queuing the build.
+
+#### Symptom 3: The build output shows `CACHE HIT`
+
+If your build job runs but you see `CACHE HIT` in the output of the `Build Images` step and the Dockerfile isn't actually built, the [build-time caching](#image-caching) determined that the image doesn't need to be rebuilt. This is an example of what the output in that step looks like:
+
+```
+Image info's Dockerfile commit: https://github.com/dotnet/dotnet-buildtools-prereqs-docker/blob/aa85f0dcc3b3d6757c80dc8c2a6f38c290b372cc/src/windowsservercore/ltsc2025/helix/amd64/Dockerfile
+Latest Dockerfile commit: https://github.com/dotnet/dotnet-buildtools-prereqs-docker/blob/aa85f0dcc3b3d6757c80dc8c2a6f38c290b372cc/src/windowsservercore/ltsc2025/helix/amd64/Dockerfile
+Dockerfile commits match: True
+
+CACHE HIT
+
+-- EXECUTING: docker pull mcr.microsoft.com/dotnet-buildtools/prereqs@sha256:40d36a0aab610f4d513ed7c7300a5d962968a547ffe8a859a0e599691b74b77f
+```
+
+**How to fix:** Set the `noCache` parameter to `true` when queuing the build.

eng/docker-tools/Install-DotNetSdk.ps1

@@ -27,7 +27,7 @@ Set-StrictMode -Version Latest
 $ErrorActionPreference = 'Stop'
 
 if (!(Test-Path "$InstallPath")) {
-    mkdir "$InstallPath" | Out-Null
+    New-Item -ItemType Directory -Path "$InstallPath" -Force | Out-Null
 }
 
 $IsRunningOnUnix = $PSVersionTable.contains("Platform") -and $PSVersionTable.Platform -eq "Unix"

eng/docker-tools/templates/jobs/cg-build-projects.yml

@@ -7,11 +7,20 @@ parameters:
   type: boolean
   default: false
   displayName: CG Dry Run
+# When true, the job skips the .NET SDK installation.
+- name: skipDotNetInstall
+  type: boolean
+  default: false
+  displayName: Skip .NET SDK Installation
 # See https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-install-script#options for possible Channel values
 - name: dotnetVersionChannel
   type: string
   default: '9.0'
   displayName: .NET Version
+# Additional steps to run before building projects (e.g. custom SDK installation).
+- name: initSteps
+  type: stepList
+  default: []
 
 jobs:
 - job: BuildProjects
@@ -21,9 +30,12 @@ jobs:
     image: $(default1ESInternalPoolImage)
     os: linux
   steps:
-  - powershell: >
-      ./eng/docker-tools/Install-DotNetSdk.ps1 -Channel ${{ parameters.dotnetVersionChannel }} -InstallPath "$(Build.SourcesDirectory)/.dotnet"
-    displayName: Run Dotnet Install Script
+  - ${{ each step in parameters.initSteps }}:
+    - ${{ step }}
+  - ${{ if eq(parameters.skipDotNetInstall, false) }}:
+    - powershell: >
+        ./eng/docker-tools/Install-DotNetSdk.ps1 -Channel ${{ parameters.dotnetVersionChannel }} -InstallPath "$(Build.SourcesDirectory)/.dotnet"
+      displayName: Install .NET SDK
   - script: >
       find . -name '*.csproj' | grep $(cgBuildGrepArgs) | xargs -n 1 $(Build.SourcesDirectory)/.dotnet/dotnet build
     displayName: Build Projects

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

@@ -15,20 +15,20 @@ jobs:
     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
+  # Setup docker and ImageBuilder (checkout must happen before init-signing
+  # so that the Install-DotNetSdk.ps1 script is available)
   - template: /eng/docker-tools/templates/steps/init-common.yml@self
     parameters:
       dockerClientOS: linux
       setupImageBuilder: true
       customInitSteps: ${{ parameters.customInitSteps }}
       publishConfig: ${{ parameters.publishConfig }}
-      envFilePath: $(signingEnvFilePath)
+
+  # 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 }}
+      dockerRunOptionsVariableName: signingDockerRunOptions
 
   - template: /eng/docker-tools/templates/steps/reference-service-connections.yml@self
     parameters:
@@ -47,6 +47,7 @@ jobs:
     parameters:
       displayName: 🔏 Sign Container Images
       internalProjectName: ${{ parameters.internalProjectName }}
+      linuxOnlyExtraDockerRunArgs: $(signingDockerRunOptions)
       args: >-
         signImages
         $(artifactsPath)/image-info/image-info.json
@@ -57,6 +58,7 @@ jobs:
     parameters:
       displayName: ✅ Verify Container Image Signatures
       internalProjectName: ${{ parameters.internalProjectName }}
+      linuxOnlyExtraDockerRunArgs: $(signingDockerRunOptions)
       args: >-
         verifySignatures
         $(artifactsPath)/image-info/image-info.json

eng/docker-tools/templates/steps/clean-acr-images.yml

@@ -3,7 +3,7 @@ parameters:
   acr: null
   action: null
   age: null
-  customArgs: "--dry-run"
+  customArgs: ''
   internalProjectName: null
 steps:
   - template: /eng/docker-tools/templates/steps/run-imagebuilder.yml@self
@@ -23,3 +23,4 @@ steps:
         --action ${{ parameters.action }}
         --age ${{ parameters.age }}
         ${{ parameters.customArgs }}
+        $(dryRunArg)

eng/docker-tools/templates/steps/init-common.yml

@@ -53,12 +53,6 @@ parameters:
   type: string
   default: "versions"
 
-# Path to an env file for docker --env-file.
-# Passed through to init-imagebuilder.yml.
-- name: envFilePath
-  type: string
-  default: ""
-
 steps:
 # Repository Checkout
 # Multi-repo checkout is used when a versions repository is needed for caching.
@@ -251,4 +245,3 @@ steps:
       publishConfig: ${{ parameters.publishConfig }}
       condition: ${{ parameters.condition }}
       customInitSteps: ${{ parameters.customInitSteps }}
-      envFilePath: ${{ parameters.envFilePath }}

eng/docker-tools/templates/steps/init-imagebuilder.yml

@@ -21,13 +21,6 @@ parameters:
   type: stepList
   default: []
 
-# Path to an env file for docker --env-file.
-# When set, --env-file is added to the docker run commands so the container
-# receives the environment variables defined in the file.
-- name: envFilePath
-  type: string
-  default: ""
-
 steps:
 # Custom ImageBuilder setup (e.g., bootstrap from source)
 - ${{ if gt(length(parameters.customInitSteps), 0) }}:
@@ -106,21 +99,25 @@ steps:
           "$(imageBuilderDockerRunExtraOptions)"
         )
 
-        $envFilePath = "${{ parameters.envFilePath }}"
-        if ($envFilePath) {
-          $dockerRunArgs += "--env-file $envFilePath"
-        }
-
         $authedDockerRunArgs = @(
           "-e", 'SYSTEM_ACCESSTOKEN'
           "-e", 'SYSTEM_OIDCREQUESTURI'
         )
 
-        $dockerRunCmd = $dockerRunBaseCmd + $dockerRunArgs + @("$(imageNames.imageBuilder.withrepo)")
-        $authedDockerRunCmd = $dockerRunBaseCmd + $authedDockerRunArgs + $dockerRunArgs + @("$(imageNames.imageBuilder.withrepo)")
+        $dockerRunCmd = $dockerRunBaseCmd + $dockerRunArgs
+        $authedDockerRunCmd = $dockerRunBaseCmd + $authedDockerRunArgs + $dockerRunArgs
+
+        # Base commands without image name for templates that need to insert
+        # extra docker run args before the image name (e.g. signing)
+        $runImageBuilderBaseCmd = $($dockerRunCmd -join ' ')
+        $runAuthedImageBuilderBaseCmd = $($authedDockerRunCmd -join ' ')
+
+        Write-Host "##vso[task.setvariable variable=runImageBuilderBaseCmd]$runImageBuilderBaseCmd"
+        Write-Host "##vso[task.setvariable variable=runAuthedImageBuilderBaseCmd]$runAuthedImageBuilderBaseCmd"
 
-        $runImageBuilderCmd = $($dockerRunCmd -join ' ')
-        $runAuthedImageBuilderCmd = $($authedDockerRunCmd -join ' ')
+        # Full commands with image name for direct invocation by other templates
+        $runImageBuilderCmd = "$runImageBuilderBaseCmd $imageBuilderImageName"
+        $runAuthedImageBuilderCmd = "$runAuthedImageBuilderBaseCmd $imageBuilderImageName"
 
         Write-Host "##vso[task.setvariable variable=runImageBuilderCmd]$runImageBuilderCmd"
         Write-Host "##vso[task.setvariable variable=runAuthedImageBuilderCmd]$runAuthedImageBuilderCmd"
@@ -138,3 +135,12 @@ steps:
         $runImageBuilderCmd = "$(Build.BinariesDirectory)\.Microsoft.DotNet.ImageBuilder\Microsoft.DotNet.ImageBuilder.exe"
         Write-Host "##vso[task.setvariable variable=runImageBuilderCmd]$runImageBuilderCmd"
         Write-Host "##vso[task.setvariable variable=runAuthedImageBuilderCmd]$runImageBuilderCmd"
+        # On Windows the base commands are the same as the full commands since
+        # there is no container image name to append
+        Write-Host "##vso[task.setvariable variable=runImageBuilderBaseCmd]$runImageBuilderCmd"
+        Write-Host "##vso[task.setvariable variable=runAuthedImageBuilderBaseCmd]$runImageBuilderCmd"
+        # Set imageBuilderImageName to empty - on Windows there is no container image
+        # since ImageBuilder runs as a native exe. run-imagebuilder.yml appends this
+        # variable to the command line, so it must be defined (but empty) to avoid
+        # leaving an unexpanded $(imageBuilderImageName) literal in the script.
+        Write-Host "##vso[task.setvariable variable=imageBuilderImageName]"