You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: eng/docker-tools/DEV-GUIDE.md
+25-2Lines changed: 25 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -143,6 +143,7 @@ Build Stage
143
143
▼
144
144
Post_Build Stage
145
145
├── Merge image info files
146
+
├── Create multi-arch manifests
146
147
└── Consolidate SBOMs
147
148
│
148
149
▼
@@ -191,13 +192,35 @@ Common patterns:
191
192
- `"publish"` - Publish only (when re-running a failed publish from a previous build)
192
193
- `"build,test,sign,publish"` - Full pipeline
193
194
194
-
**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.
195
+
**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, create and validate multi-arch manifests, and consolidate SBOMs.
195
196
196
197
The stages variable is useful for:
197
198
- Re-running just the publish stage after fixing a transient failure
198
199
- Skipping tests during initial development
199
200
- Running isolated stages for debugging
200
201
202
+
### Decoupling build OS from the base image OS
203
+
204
+
By default, a platform's `osVersion` represents the base image OS version, but also determines what
205
+
build leg an image is built in. This can cause problems when build image and base image don't match
206
+
up. For example, building a .NET app on Windows Server 2025 and copying the artifacts into a
207
+
Windows Server 2019 base image won't work, because the build matrix generation will attempt to
208
+
build the image on the Server 2019 build leg (which can't run Server 2025 images).
209
+
210
+
To fix this, set the optional `buildOsVersion` field in order to override only the OS used in the
211
+
build matrix generation. Here is an example of building a Windows Server 2019 image using Windows
212
+
Server 2025:
213
+
214
+
```jsonc
215
+
{
216
+
// ...
217
+
"os": "windows",
218
+
"osVersion": "windowsservercore-ltsc2019",
219
+
"buildOsVersion": "windowsservercore-ltsc2025"
220
+
// ...
221
+
}
222
+
```
223
+
201
224
### Image Info Files: The Build's Memory
202
225
203
226
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:
@@ -458,7 +481,7 @@ If the Dockerfile is in the manifest but you don't see a build job for it, the b
0 commit comments