Merge remote-tracking branch 'origin/main' into copilot/fix-image-builder-host-management

# Conflicts:
#	src/ImageBuilder/ImageBuilder.cs

Author: Copilot

eng/docker-tools/DEV-GUIDE.md

@@ -198,6 +198,28 @@ The stages variable is useful for:
 - Skipping tests during initial development
 - Running isolated stages for debugging
 
+### Decoupling build OS from the base image OS
+
+By default, a platform's `osVersion` represents the base image OS version, but also determines what
+build leg an image is built in. This can cause problems when build image and base image don't match
+up. For example, building a .NET app on Windows Server 2025 and copying the artifacts into a
+Windows Server 2019 base image won't work, because the build matrix generation will attempt to
+build the image on the Server 2019 build leg (which can't run Server 2025 images).
+
+To fix this, set the optional `buildOsVersion` field in order to override only the OS used in the
+build matrix generation. Here is an example of building a Windows Server 2019 image using Windows
+Server 2025:
+
+```jsonc
+{
+  // ...
+  "os": "windows",
+  "osVersion": "windowsservercore-ltsc2019",
+  "buildOsVersion": "windowsservercore-ltsc2025"
+  // ...
+}
+```
+
 ### Image Info Files: The Build's Memory
 
 Image info files (defined by [`ImageArtifactDetails`](https://github.com/dotnet/docker-tools/blob/main/src/ImageBuilder/Models/Image/ImageArtifactDetails.cs)) are the mechanism that tracks what was built:

eng/pipelines/renovate.yml

@@ -1,3 +1,6 @@
+# Renovate Dependency Update Pipeline
+# This pipeline runs Renovate to automatically create PRs for dependency updates.
+
 trigger: none
 pr: none
 
@@ -21,16 +24,13 @@ parameters:
   default: false
 
 variables:
-- template: /eng/docker-tools/templates/variables/sdl-pool.yml@self
+- name: gitHubRepo
+  value: 'dotnet/docker-tools'
 
 extends:
-  template: /eng/docker-tools/templates/1es.yml@self
+  template: /eng/common/core-templates/stages/renovate.yml@self
   parameters:
-    stages:
-    - stage: Renovate
-      jobs:
-      - template: /eng/pipelines/templates/jobs/renovate.yml
-        parameters:
-          gitHubRepo: dotnet/docker-tools
-          dryRun: ${{ parameters.dryRun }}
-          forceRecreatePR: ${{ parameters.forceRecreatePR }}
+    dryRun: ${{ parameters.dryRun }}
+    forceRecreatePR: ${{ parameters.forceRecreatePR }}
+    gitHubRepo: ${{ variables.gitHubRepo }}
+    renovateConfigPath: eng/renovate.json

eng/pipelines/templates/jobs/renovate.yml

@@ -4,6 +4,11 @@
 
 namespace Microsoft.DotNet.ImageBuilder.Models.Manifest;
 
+/// <summary>
+/// The generic operating system family of an image. Serialized to the manifest as a lowercase
+/// string (e.g. "linux", "windows"). The specific OS version is captured separately by
+/// <see cref="Platform.OsVersion"/> (e.g. "azurelinux3.0", "windowsservercore-ltsc2025").
+/// </summary>
 public enum OS
 {
     Linux,

eng/renovate.env

@@ -41,19 +41,32 @@ public class Platform
     public string? DockerfileTemplate { get; set; }
 
     [Description(
-        "The generic name of the operating system associated with the image."
+        "The generic name of the operating system associated with the image. " +
+        "Examples: linux, windows."
         )]
     [JsonConverter(typeof(StringEnumConverter))]
     [JsonProperty(Required = Required.Always)]
     public OS OS { get; set; }
 
     [Description(
-        "The specific version of the operating system associated with the image. " +
-        "Examples: alpine3.9, bionic, nanoserver-1903."
+        "The specific version of the operating system that this platform targets. This is " +
+        "metadata used to filter which platforms are built (--os-version), recorded in the " +
+        "image-info output, used to derive the OS display name in generated readmes, and " +
+        "(unless overridden by BuildOsVersion) to select the build host." +
+        "Examples: alpine3.2X, jammy, noble, trixie, nanoserver-1809, nanoserver-ltsc2025, " +
+        "windowsservercore-ltsc2025."
         )]
     [JsonProperty(Required = Required.Always)]
     public string OsVersion { get; set; } = string.Empty;
 
+    [Description(
+        "Overrides the operating system version used to select the build host/agent without " +
+        "affecting the --os-version filter or image-info. This allows platforms that target " +
+        "different OS versions to be built together on a single build host. Uses the same value " +
+        "format as OsVersion. When omitted, the build host is selected based on OsVersion."
+        )]
+    public string? BuildOsVersion { get; set; }
+
     [Description(
         "The set of platform-specific tags associated with the image."
         )]