windows-image-updater | project-toolkit

Stats

Actions

Tags

windows-image-updater | project-toolkit

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 — 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

cd
```
dotnet test
```
Common first-error fixes:

After each single fix, rebuild. The error count should decrease significantly with each iteration.

Verification:

dotnet build exits with code 0
No package downgrade warnings

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) | | Combined | Single repo with a folder containing .resources in its name alongside service code | Run both if present; check which generates .pipelines/ output |

This regenerates pipeline configuration files. Expect many file changes.
```
Set-Location <path-to-csproj>\bin\Debug\net8.0


Check that pipeline yml files no longer reference the old image:
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 test exits with code 0
No new warnings compared to baseline

Purpose: Create a draft PR, validate through pipelines, and attach results.

Stage and commit


git add -A
container image, resolving the LTSC2019 end-of-life warning."
```bash

git push -u origin feat/windows-image-update
  ## Summary
  (end-of-life) to LTSC2022.


  ## Changes
  - Resolved package dependency conflicts (if any)


  ## Validation








  - [ ] Buddy build: [link]






 Work Items

  - AB#{work-item-id}




After the PR is created, the **pipeline-validator** skill takes over to:
alidate the PR description has required sections (Summary, Changes, Validation)


 Discover and trigger all associated pipelines (PR Build → Buddy Build → Buddy Release)
 Update the PR description with pipeline run links and results

6. Report final status

Draft PR exists targeting default branch

Anti-Patterns

|-------|-----|---------|

| Manually editing pipeline yml files | They are generated by ConfigGen; manual edits will be overwritten | Always use package bump → ConfigGen workflow | | Creating non-draft PR | Premature review notifications before pipeline validation | Always create as draft first | | Hardcoding ltsc2022 as the target | Next migration cycle will need different target | Use parameterized image names |

After complete execution:

dotnet test succeeds
No ltsc2019 references in .pipelines/ yml/yaml files
Draft PR created with description
pipeline-validator completed — all pipelines pass (PR, buddy build, buddy release)
PR description updated with pipeline run links

Aborting / Rollback

|-----------|-----------------| | Phase 1-2 (not pushed) | git checkout main && git branch -D feat/windows-image-update | | 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)