Windows Image Updater
Automates the end-to-end workflow for migrating Windows container images (e.g., LTSC2019 → LTSC2022) in OneBranch pipeline repositories. Handles package bumping, config regeneration, build validation, and PR creation.
Triggers
update windows image: start the full migration workflow
fix ltsc2019 warning: triggered by OneBranch EOL warning
migrate onebranch image: alternative phrasing
bump AdoPipelineGeneration: package-specific trigger
windows container image update for {repo}: repo-specific trigger
Quick Reference
| Input |
Output |
Duration |
| ADO repository (URL or local path) |
Draft PR with updated pipeline ymls, passing pipelines |
30-60 min |
Prerequisites
Required Knowledge
| Term |
Definition |
| OneBranch |
Microsoft's CI/CD build platform used for official builds and releases |
| ConfigGen |
Configuration Generation tool that produces pipeline YAML files from package definitions |
| Topology project |
A .NET project in resources repos that generates pipeline configs when run |
| LTSC |
Long-Term Servicing Channel, a Windows release model (e.g., LTSC2019, LTSC2022) |
| Buddy build |
Pre-merge validation pipeline that builds and tests changes before merge |
| Buddy release |
Pre-merge pipeline that validates the release process before merge |
| CPM |
Central Package Management, a NuGet feature where all versions are in Directory.Packages.props |
Required Tools
| Tool |
Purpose |
Verify |
| Git |
Version control |
git --version |
| .NET SDK |
Build and run .NET projects |
dotnet --version |
| ADO access |
Repository write access, PR creation rights |
az repos list |
Configuration
| Parameter |
Default |
Description |
| Old image pattern |
ltsc2019 |
Pattern to detect in pipeline yml files |
| Expected new image |
ltsc2022 |
Expected replacement (for verification) |
| Package name |
ConfigurationGeneration.AdoPipelineGeneration |
NuGet package to bump |
| Branch name |
feat/windows-image-update |
Feature branch name |
| Props file |
Directory.Packages.props |
Primary package props file (fallback: Packages.props) |
Process
Phase 1: Repository Setup
Purpose: Establish a clean working environment with baseline build metrics.
Clone or navigate to the repository
git clone <repo-url>
cd <repo-name>
Ensure default branch with latest changes
git checkout main # or master, depending on repo
git pull origin main
Create feature branch
git checkout -b feat/windows-image-update
Run baseline build and record warnings
dotnet clean
dotnet build 2>&1 | tee build-baseline.log
dotnet test
Capture baseline warnings for later comparison:
dotnet build 2>&1 | Select-String "warning" | Out-File baseline-warnings.txt
Verification:
If build fails: STOP. The repository has pre-existing build issues. Report to user before proceeding.
Phase 2: Package Update
Purpose: Bump the AdoPipelineGeneration package and resolve any build conflicts.
Find the package props file in the repository root
ls Directory.Packages.props 2>$null || ls Packages.props
Locate ConfigurationGeneration.AdoPipelineGeneration in the props file
If it EXISTS: Note the current version and proceed to step 3
If it does NOT exist: You must add it. First, discover the Topology project path (see Phase 3 step 1), then:
cd <path-to-topology-project-directory>
dotnet add package ConfigurationGeneration.AdoPipelineGeneration
cd <repo-root>
This will add the package reference. Then add a corresponding <PackageVersion> entry in the props file if using Central Package Management.
Check latest available version
dotnet list package --outdated
Or check the NuGet feed directly for the latest version of ConfigurationGeneration.AdoPipelineGeneration.
Update the version in the props file to the latest version
Build and fix errors ONE AT A TIME
dotnet clean
dotnet build
CRITICAL: Incremental error resolution strategy.
Do NOT try to fix all errors at once. Fix one error at a time, then rebuild:
Loop:
1. Run dotnet build
2. If build succeeds → done, exit loop
3. Read the FIRST error in the output
4. Fix ONLY that first error (bump one package, fix one reference)
5. Go to step 1
Why one at a time? Fixing the first error (e.g., bumping one conflicting package) often resolves many transitive dependency errors downstream. If you try to fix all 20 errors at once, you may introduce new conflicts.
Common first-error fixes:
| Error |
Fix |
NU1605: Package downgrade detected |
Bump the ONE conflicting package mentioned to the required version |
NU1608: Detected package version outside of dependency constraint |
Bump the ONE package mentioned in the constraint to latest version in the props file |
NU1107: Version conflict detected |
Pin the conflicting package directly in the project (add <PackageReference>) and/or bump the constraining package |
CS0246: Type or namespace not found |
A dependent package API changed; update the code reference |
After each single fix, rebuild. The error count should decrease significantly with each iteration.
Verification:
See: references/troubleshooting.md for detailed error resolution
Phase 3: Config Generation & Verification
Purpose: Regenerate pipeline files and verify the Windows container image reference is updated.
Discover the ConfigGen/Topology project
Search for the project file:
# Look for .csproj files with Topology or ConfigurationGeneration in the name
Get-ChildItem -Recurse -Filter "*.csproj" | Where-Object { $_.Name -match "Topology|ConfigurationGeneration" }
Decision guide, how to identify repo type:
| Repo Type |
How to Identify |
Project to Run |
| Resources |
Repo name contains .resources (e.g., MyService.resources) OR folder contains .resources in name |
Topology project (e.g., *Topology*.csproj) |
| Service |
Repo name does NOT contain .resources (e.g., MyService) |
ConfigurationGeneration project (e.g., *ConfigurationGeneration*.csproj) |
| Combined |
Single repo with a folder containing .resources in its name alongside service code |
Run both if present; check which generates .pipelines/ output |
Run the ConfigGen project
dotnet run --project <path-to-discovered-csproj>
This regenerates pipeline configuration files. Expect many file changes.
If the project targets multiple frameworks, specify the framework:
dotnet run --project <path-to-csproj> --framework net8.0
If Assembly.Load fails, build first and run from the output directory:
dotnet build <path-to-csproj> --framework net8.0
Set-Location <path-to-csproj>\bin\Debug\net8.0
.\<ProjectName>.exe
Verify the image update
Check that pipeline yml files no longer reference the old image:
# Should return NO results
Get-ChildItem -Recurse -Path .pipelines -Filter "*.yml" | Select-String "ltsc2019"
Get-ChildItem -Recurse -Path .pipelines -Filter "*.yaml" | Select-String "ltsc2019"
The windowscontainerimage value should now contain ltsc2022 (or similar updated pattern).
Run final validation
dotnet clean
dotnet build 2>&1 | tee build-final.log
dotnet test
Compare warnings against Phase 1 baseline:
dotnet build 2>&1 | Select-String "warning" | Out-File final-warnings.txt
Compare-Object (Get-Content baseline-warnings.txt) (Get-Content final-warnings.txt)
Empty diff or only resolved warnings = good. Any NEW warnings must be investigated.
Verification:
If image didn't change: Verify you bumped the correct package and ran the correct ConfigGen project. Re-run Phase 2 if needed.
Phase 4: PR Creation & Pipeline Validation
Purpose: Create a draft PR, validate through pipelines, and attach results.
Stage and commit
git add -A
git commit -m "chore: update Windows container image from LTSC2019 to LTSC2022
Bumped ConfigurationGeneration.AdoPipelineGeneration to latest version
and regenerated pipeline configurations to use the updated Windows
container image, resolving the LTSC2019 end-of-life warning."
Push to origin
git push -u origin feat/windows-image-update
Create draft PR targeting the default branch
Title: chore: Update Windows container image from LTSC2019 to LTSC2022
Description template:
## Summary
Updated the Windows container image used in OneBranch pipelines from LTSC2019
(end-of-life) to LTSC2022.
## Changes
- Bumped `ConfigurationGeneration.AdoPipelineGeneration` to version X.Y.Z
- Regenerated pipeline configuration files
- Resolved package dependency conflicts (if any)
## Validation
- [x] dotnet build passes
- [x] dotnet test passes
- [x] Pipeline yml files verified, no ltsc2019 references
- [ ] PR pipeline: [link]
- [ ] Buddy build: [link]
- [ ] Buddy release: [link]
## Work Items
- AB#{work-item-id}
Attach work items (if provided by user)
Invoke pipeline-validator skill for automated pipeline validation.
After the PR is created, the pipeline-validator skill takes over to:
- Find the PR for the current branch
- Validate the PR description has required sections (Summary, Changes, Validation)
- Discover and trigger all associated pipelines (PR Build → Buddy Build → Buddy Release)
- Auto-diagnose and fix any pipeline failures (up to 3 retries per pipeline)
- Update the PR description with pipeline run links and results
- Report final status
Do not proceed manually. The pipeline-validator handles all pipeline monitoring, failure diagnosis, fix-and-retry loops, and PR description updates autonomously.
Verification:
Anti-Patterns
| Avoid |
Why |
Instead |
| Manually editing pipeline yml files |
They are generated by ConfigGen; manual edits will be overwritten |
Always use package bump → ConfigGen workflow |
| Skipping baseline build |
Cannot distinguish pre-existing vs new errors |
Always run Phase 1 baseline first |
| Ignoring package downgrade errors |
Downstream build will fail unpredictably |
Fix all NU1605/NU1608 errors before ConfigGen |
| Creating non-draft PR |
Premature review notifications before pipeline validation |
Always create as draft first |
| Fixing all errors at once |
One fix often resolves many downstream errors |
Fix FIRST error, rebuild, repeat |
| Hardcoding ltsc2022 as the target |
Next migration cycle will need different target |
Use parameterized image names |
Verification
After complete execution:
Aborting / Rollback
| Failed At |
Rollback Command |
| Phase 1-2 (not pushed) |
git checkout main && git branch -D feat/windows-image-update |
| Phase 3 (not pushed) |
git reset --hard origin/main |
| Phase 4 (pushed, PR created) |
Close the draft PR in ADO, delete the remote branch |
Extension Points
- Image name parameters: Change
--old-image for future LTSC migrations (e.g., ltsc2022 → ltsc2025)
- Package name: Update the target package if ConfigGen is renamed
- Pipeline types: Add new pipeline validation steps as OneBranch evolves
- Multi-repo batch: Extend to process multiple repositories in sequence
References
- Troubleshooting Guide: common errors and fixes during the update workflow
- Pipeline Validator Skill: automated pipeline discovery, triggering, and fix-retry loop (invoked in Phase 4)
1---2name: windows-image-updater-33description: Automates Windows container image migration for OneBranch pipelines. Bumps AdoPipelineGeneration package, regenerates pipeline configs via ConfigGen, and verifies old image reference is removed. Use for LTSC2019 to LTSC2022 migration, container image updates, OneBranch pipeline image upgrades.4metadata:5 source: https://skillmd.com/skills/rjmurillo/windows-image-updater-36---78# Windows Image Updater910Automates the end-to-end workflow for migrating Windows container images (e.g., LTSC2019 → LTSC2022) in OneBranch pipeline repositories. Handles package bumping, config regeneration, build validation, and PR creation.1112---1314## Triggers1516- `update windows image`: start the full migration workflow17- `fix ltsc2019 warning`: triggered by OneBranch EOL warning18- `migrate onebranch image`: alternative phrasing19- `bump AdoPipelineGeneration`: package-specific trigger20- `windows container image update for {repo}`: repo-specific trigger2122## Quick Reference2324| Input | Output | Duration |25|-------|--------|----------|26| ADO repository (URL or local path) | Draft PR with updated pipeline ymls, passing pipelines | 30-60 min |2728---2930## Prerequisites3132### Required Knowledge3334| Term | Definition |35|------|------------|36| **OneBranch** | Microsoft's CI/CD build platform used for official builds and releases |37| **ConfigGen** | Configuration Generation tool that produces pipeline YAML files from package definitions |38| **Topology project** | A .NET project in resources repos that generates pipeline configs when run |39| **LTSC** | Long-Term Servicing Channel, a Windows release model (e.g., LTSC2019, LTSC2022) |40| **Buddy build** | Pre-merge validation pipeline that builds and tests changes before merge |41| **Buddy release** | Pre-merge pipeline that validates the release process before merge |42| **CPM** | Central Package Management, a NuGet feature where all versions are in Directory.Packages.props |4344### Required Tools4546| Tool | Purpose | Verify |47|------|---------|--------|48| **Git** | Version control | `git --version` |49| **.NET SDK** | Build and run .NET projects | `dotnet --version` |50| **ADO access** | Repository write access, PR creation rights | `az repos list` |5152---5354## Configuration5556| Parameter | Default | Description |57|-----------|---------|-------------|58| Old image pattern | `ltsc2019` | Pattern to detect in pipeline yml files |59| Expected new image | `ltsc2022` | Expected replacement (for verification) |60| Package name | `ConfigurationGeneration.AdoPipelineGeneration` | NuGet package to bump |61| Branch name | `feat/windows-image-update` | Feature branch name |62| Props file | `Directory.Packages.props` | Primary package props file (fallback: `Packages.props`) |6364---6566## Process6768### Phase 1: Repository Setup6970**Purpose:** Establish a clean working environment with baseline build metrics.71721. **Clone or navigate** to the repository7374 ```bash75 git clone <repo-url>76 cd <repo-name>77 ```78792. **Ensure default branch** with latest changes8081 ```bash82 git checkout main # or master, depending on repo83 git pull origin main84 ```85863. **Create feature branch**8788 ```bash89 git checkout -b feat/windows-image-update90 ```91924. **Run baseline build** and record warnings9394 ```bash95 dotnet clean96 dotnet build 2>&1 | tee build-baseline.log97 dotnet test98 ```991005. **Capture baseline warnings** for later comparison:101102 ```powershell103 dotnet build 2>&1 | Select-String "warning" | Out-File baseline-warnings.txt104 ```105106**Verification:**107108- [ ] On `feat/windows-image-update` branch109- [ ] `dotnet build` exits with code 0110- [ ] `dotnet test` exits with code 0111- [ ] Baseline warnings recorded112113**If build fails:** STOP. The repository has pre-existing build issues. Report to user before proceeding.114115---116117### Phase 2: Package Update118119**Purpose:** Bump the AdoPipelineGeneration package and resolve any build conflicts.1201211. **Find the package props file** in the repository root122123 ```bash124 ls Directory.Packages.props 2>$null || ls Packages.props125 ```1261272. **Locate `ConfigurationGeneration.AdoPipelineGeneration`** in the props file128 - **If it EXISTS:** Note the current version and proceed to step 3129 - **If it does NOT exist:** You must add it. First, discover the Topology project path (see Phase 3 step 1), then:130131 ```bash132 cd <path-to-topology-project-directory>133 dotnet add package ConfigurationGeneration.AdoPipelineGeneration134 cd <repo-root>135 ```136137 This will add the package reference. Then add a corresponding `<PackageVersion>` entry in the props file if using Central Package Management.1381393. **Check latest available version**140141 ```bash142 dotnet list package --outdated143 ```144145 Or check the NuGet feed directly for the latest version of `ConfigurationGeneration.AdoPipelineGeneration`.1461474. **Update the version** in the props file to the latest version1481495. **Build and fix errors ONE AT A TIME**150151 ```bash152 dotnet clean153 dotnet build154 ```155156 **CRITICAL: Incremental error resolution strategy.**157 Do NOT try to fix all errors at once. Fix one error at a time, then rebuild:158159 ```160 Loop:161 1. Run dotnet build162 2. If build succeeds → done, exit loop163 3. Read the FIRST error in the output164 4. Fix ONLY that first error (bump one package, fix one reference)165 5. Go to step 1166 ```167168 **Why one at a time?** Fixing the first error (e.g., bumping one conflicting package) often resolves many transitive dependency errors downstream. If you try to fix all 20 errors at once, you may introduce new conflicts.169170 Common first-error fixes:171172 | Error | Fix |173 |-------|-----|174 | `NU1605: Package downgrade detected` | Bump the ONE conflicting package mentioned to the required version |175 | `NU1608: Detected package version outside of dependency constraint` | Bump the ONE package mentioned in the constraint to latest version in the props file |176 | `NU1107: Version conflict detected` | Pin the conflicting package directly in the project (add `<PackageReference>`) and/or bump the constraining package |177 | `CS0246: Type or namespace not found` | A dependent package API changed; update the code reference |178179 After each single fix, rebuild. The error count should decrease significantly with each iteration.180181**Verification:**182183- [ ] Package version updated in props file184- [ ] `dotnet build` exits with code 0185- [ ] No package downgrade warnings186187See: [references/troubleshooting.md](references/troubleshooting.md) for detailed error resolution188189---190191### Phase 3: Config Generation & Verification192193**Purpose:** Regenerate pipeline files and verify the Windows container image reference is updated.1941951. **Discover the ConfigGen/Topology project**196197 Search for the project file:198199 ```powershell200 # Look for .csproj files with Topology or ConfigurationGeneration in the name201 Get-ChildItem -Recurse -Filter "*.csproj" | Where-Object { $_.Name -match "Topology|ConfigurationGeneration" }202 ```203204 **Decision guide, how to identify repo type:**205206 | Repo Type | How to Identify | Project to Run |207 |-----------|-----------------|----------------|208 | **Resources** | Repo name contains `.resources` (e.g., `MyService.resources`) OR folder contains `.resources` in name | **Topology** project (e.g., `*Topology*.csproj`) |209 | **Service** | Repo name does NOT contain `.resources` (e.g., `MyService`) | **ConfigurationGeneration** project (e.g., `*ConfigurationGeneration*.csproj`) |210 | **Combined** | Single repo with a folder containing `.resources` in its name alongside service code | Run both if present; check which generates `.pipelines/` output |2112122. **Run the ConfigGen project**213214 ```bash215 dotnet run --project <path-to-discovered-csproj>216 ```217218 This regenerates pipeline configuration files. Expect many file changes.219220 **If the project targets multiple frameworks**, specify the framework:221222 ```bash223 dotnet run --project <path-to-csproj> --framework net8.0224 ```225226 **If Assembly.Load fails**, build first and run from the output directory:227228 ```powershell229 dotnet build <path-to-csproj> --framework net8.0230 Set-Location <path-to-csproj>\bin\Debug\net8.0231 .\<ProjectName>.exe232 ```2332343. **Verify the image update**235236 Check that pipeline yml files no longer reference the old image:237238 ```powershell239 # Should return NO results240 Get-ChildItem -Recurse -Path .pipelines -Filter "*.yml" | Select-String "ltsc2019"241 Get-ChildItem -Recurse -Path .pipelines -Filter "*.yaml" | Select-String "ltsc2019"242 ```243244 The `windowscontainerimage` value should now contain `ltsc2022` (or similar updated pattern).2452464. **Run final validation**247248 ```bash249 dotnet clean250 dotnet build 2>&1 | tee build-final.log251 dotnet test252 ```2532545. **Compare warnings** against Phase 1 baseline:255256 ```powershell257 dotnet build 2>&1 | Select-String "warning" | Out-File final-warnings.txt258 Compare-Object (Get-Content baseline-warnings.txt) (Get-Content final-warnings.txt)259 ```260261 Empty diff or only resolved warnings = good. Any NEW warnings must be investigated.262263**Verification:**264265- [ ] No `ltsc2019` references in `.pipelines/*.yml` or `.pipelines/*.yaml` files266- [ ] `dotnet build` exits with code 0267- [ ] `dotnet test` exits with code 0268- [ ] No new warnings compared to baseline269270**If image didn't change:** Verify you bumped the correct package and ran the correct ConfigGen project. Re-run Phase 2 if needed.271272---273274### Phase 4: PR Creation & Pipeline Validation275276**Purpose:** Create a draft PR, validate through pipelines, and attach results.2772781. **Stage and commit**279280 ```bash281 git add -A282 git commit -m "chore: update Windows container image from LTSC2019 to LTSC2022283284 Bumped ConfigurationGeneration.AdoPipelineGeneration to latest version285 and regenerated pipeline configurations to use the updated Windows286 container image, resolving the LTSC2019 end-of-life warning."287 ```2882892. **Push to origin**290291 ```bash292 git push -u origin feat/windows-image-update293 ```2942953. **Create draft PR** targeting the default branch296 - **Title:** `chore: Update Windows container image from LTSC2019 to LTSC2022`297 - **Description template:**298299 ```300 ## Summary301 Updated the Windows container image used in OneBranch pipelines from LTSC2019302 (end-of-life) to LTSC2022.303304 ## Changes305 - Bumped `ConfigurationGeneration.AdoPipelineGeneration` to version X.Y.Z306 - Regenerated pipeline configuration files307 - Resolved package dependency conflicts (if any)308309 ## Validation310 - [x] dotnet build passes311 - [x] dotnet test passes312 - [x] Pipeline yml files verified, no ltsc2019 references313 - [ ] PR pipeline: [link]314 - [ ] Buddy build: [link]315 - [ ] Buddy release: [link]316317 ## Work Items318 - AB#{work-item-id}319 ```3203214. **Attach work items** (if provided by user)3223235. **Invoke pipeline-validator skill** for automated pipeline validation.324325 After the PR is created, the **pipeline-validator** skill takes over to:326327 1. Find the PR for the current branch328 2. Validate the PR description has required sections (Summary, Changes, Validation)329 3. Discover and trigger all associated pipelines (PR Build → Buddy Build → Buddy Release)330 4. Auto-diagnose and fix any pipeline failures (up to 3 retries per pipeline)331 5. Update the PR description with pipeline run links and results332 6. Report final status333334 > **Do not proceed manually.** The pipeline-validator handles all pipeline monitoring, failure diagnosis, fix-and-retry loops, and PR description updates autonomously.335336**Verification:**337338- [ ] Draft PR exists targeting default branch339- [ ] pipeline-validator invoked and completed340- [ ] All pipelines pass (confirmed by pipeline-validator)341- [ ] PR description updated with pipeline links342343---344345## Anti-Patterns346347| Avoid | Why | Instead |348|-------|-----|---------|349| Manually editing pipeline yml files | They are generated by ConfigGen; manual edits will be overwritten | Always use package bump → ConfigGen workflow |350| Skipping baseline build | Cannot distinguish pre-existing vs new errors | Always run Phase 1 baseline first |351| Ignoring package downgrade errors | Downstream build will fail unpredictably | Fix all NU1605/NU1608 errors before ConfigGen |352| Creating non-draft PR | Premature review notifications before pipeline validation | Always create as draft first |353| Fixing all errors at once | One fix often resolves many downstream errors | Fix FIRST error, rebuild, repeat |354| Hardcoding ltsc2022 as the target | Next migration cycle will need different target | Use parameterized image names |355356---357358## Verification359360After complete execution:361362- [ ] `dotnet build` succeeds363- [ ] `dotnet test` succeeds364- [ ] No `ltsc2019` references in `.pipelines/` yml/yaml files365- [ ] No new warnings vs baseline366- [ ] Draft PR created with description367- [ ] pipeline-validator completed, all pipelines pass (PR, buddy build, buddy release)368- [ ] PR description updated with pipeline run links369370---371372## Aborting / Rollback373374| Failed At | Rollback Command |375|-----------|-----------------|376| Phase 1-2 (not pushed) | `git checkout main && git branch -D feat/windows-image-update` |377| Phase 3 (not pushed) | `git reset --hard origin/main` |378| Phase 4 (pushed, PR created) | Close the draft PR in ADO, delete the remote branch |379380---381382## Extension Points3833841. **Image name parameters:** Change `--old-image` for future LTSC migrations (e.g., ltsc2022 → ltsc2025)3852. **Package name:** Update the target package if ConfigGen is renamed3863. **Pipeline types:** Add new pipeline validation steps as OneBranch evolves3874. **Multi-repo batch:** Extend to process multiple repositories in sequence388389---390391## References392393- [Troubleshooting Guide](references/troubleshooting.md): common errors and fixes during the update workflow394- [Pipeline Validator Skill](../pipeline-validator/SKILL.md): automated pipeline discovery, triggering, and fix-retry loop (invoked in Phase 4)