vsadov/satori/update-os-coverage

Update OS Coverage

Update OS version references in Helix queue definition files. These files control which operating system versions are used for CI/CD testing via Helix.

Prerequisites

Baseline build not required: This skill is for YAML/docs-style queue and image reference updates, not product code changes. Do not start with the repo-wide baseline build workflow from the build-and-test skill unless the task expands beyond image / queue metadata into code changes that actually need build or test validation.

When to use

• An OS version is approaching or has reached EOL and should be replaced
• A new OS version is released and should be added to Helix testing for coverage
• We take a more proactive approach on main. If a distro version will be EOL before our annual November release, we should update it to a newer version. If a distro version is expected to ship within one quarter (3 months) and a prereqs container image already exists, we should add it to Helix testing.
• The availability of an image in the prereqs container repo is a strong signal that the OS version is approved for Helix testing, at least on main.
• Helix coverage does not match the supported-os matrix (for example, the relevant release-notes/<dotnet-version>/supported-os.json file in dotnet/core).
• Upgrading "oldest" or "latest" version slots for a distro

For servicing / release/* branches, be more conservative: only update to GA and already-supported distro versions unless the user explicitly asks for a forward-looking change.

When NOT to use

• Creating new container images → file an issue or PR at dotnet-buildtools-prereqs-docker
• Updating supported-os.json / supported-os.md → file an issue in dotnet/core
• Adding entirely new distros or architectures to Helix (requires pipeline template changes beyond version bumps)
• Requesting new Helix VM queues → file an issue at dotnet/dnceng
• Updating Windows or macOS Helix queues — these use VM-based queues with a simpler format (e.g. Windows.11.Amd64.Client.Open) and version updates typically require dnceng coordination

Key files

OS version references appear in these pipeline files:

The OS onboarding guide is the authoritative reference for how OS versions are managed in this repo. Read it if more context is needed on our policies.

helix-platforms.yml structure

Many Linux container-backed entries in this file use a pattern like:

# <Distro> <arch>
# Latest: <distro-version>
- name: helix_linux_x64_<distro>_latest
  value: (<QueueName>)<HostQueue>@mcr.microsoft.com/dotnet-buildtools/prereqs:<image-tag>

Where <QueueName> is the Helix queue identifier (e.g. Fedora.44.Amd64.Open), <HostQueue> is the physical host queue (e.g. AzureLinux.3.Amd64.Open), and <image-tag> is the container image tag (e.g. fedora-44-helix-amd64).

Other entries in the same file are plain queue values (for example Windows, macOS, and some Linux VM queues) rather than (<QueueName>)<HostQueue>@<image>. When the target entry is queue-only, preserve that format and update only the versioned queue string.

Some platform variables have _internal counterparts (e.g. helix_linux_x64_oldest_internal, helix_linux_musl_arm32_latest_internal) that use the same queue/image but drop the .Open suffix. When an _internal counterpart exists, update both the .Open and _internal entries.

helix-queues-setup.yml files

These files reference OS versions directly (not via variables) in conditional blocks per platform. Most Linux container-backed inline references follow the (<QueueName>)<HostQueue>@<image> format, while a few entries are plain queue values (for example, some AzureLinux-only queues). Preserve the existing format for the specific entry you are updating.

Inputs

The user provides one or more of:

• Distro and version — e.g. "Update Fedora to 44", "Replace Alpine 3.20 with 3.22"
• Slot — whether to update latest, oldest, or both
• Branch — defaults to current branch; may also need release branch updates
• Audit mode — "check all OS versions against supported-os.json"

If the user provides only a distro name without specifying slots, either ask or determine with basic logic which slots to update (for example, if the current latest is EOL, update latest; if the current oldest is EOL, update oldest).

Process

Use the repo tools that fit the environment. The shell snippets below are reference commands, not a required literal script; equivalent gh, git, or search-based workflows are fine.

1. Verify container image availability

Before making any changes, confirm the exact target container tag exists by querying the MCR registry directly. The registry is the ground truth for published dotnet-buildtools/prereqs tags:

TARGET_TAG="<exact-image-tag>"
curl -s https://mcr.microsoft.com/v2/dotnet-buildtools/prereqs/tags/list \
  | jq -e --arg tag "$TARGET_TAG" 'any(.tags[]; . == $tag)'

⚠️ This is in flux. Image-info publishing is mid-transition. The image-info JSON in dotnet/versions was historically the source of truth, but it is published by committing back to dotnet/versions and can be stale or unavailable when branch protection blocks that automated push. The fix in flight (dotnet/docker-tools#2142) moves image-info to an ORAS-based OCI artifact published to the registry alongside the images. Until that lands, trust the registry tag list (above) as the source of truth and treat the image-info JSON only as a possibly-stale cross-check. Revisit this step once the ORAS solution ships.

If the exact tag is not found in the registry, stop and inform the user. The image must be created first at dotnet/dotnet-buildtools-prereqs-docker. Check if an open issue or PR already exists, for example:

gh search issues "<distro> <distro-version>" --repo dotnet/dotnet-buildtools-prereqs-docker --state open

2. Check support policy first, then EOL dates if needed

First, inspect the relevant supported-os.json entry in dotnet/core to see whether the distro/version is already supported for the target release and to find its official lifecycle link:

curl -sL https://github.com/dotnet/core/raw/refs/heads/main/release-notes/<dotnet-version>/supported-os.json \
  | jq '.families[] | select(.name == "Linux") | .distributions[] | select(.id == "<distro-id>") | {name, lifecycle, supportedVersions: ."supported-versions", unsupportedVersions: ."unsupported-versions"}'

If the target distro version is already listed in supportedVersions, that is the primary signal that the change is appropriate for the corresponding release line. On servicing branches, prefer versions that are already GA and present there.

If you need an independent lifecycle check, or if supported-os.json does not yet reflect the situation clearly, use endoflife.date as a fallback:

curl -s https://endoflife.date/api/<distro-id>.json | jq '.[] | select(.cycle == "<distro-version>") | {cycle, eol, releaseDate}'

The <distro-id> values typically match across both sources (e.g. fedora, alpine, debian, opensuse, ubuntu, centos-stream).

3. Scan current references

Search for all current references to the distro being updated. For example:

grep -rn -i "<distro>" \
  eng/pipelines/helix-platforms.yml \
  eng/pipelines/libraries/helix-queues-setup.yml \
  eng/pipelines/coreclr/templates/helix-queues-setup.yml \
  eng/pipelines/installer/helix-queues-setup.yml \
  eng/pipelines/common/templates/pipeline-with-resources.yml \
  docs/workflow/using-docker.md

Note every occurrence — the same distro may appear in multiple sections (x64, arm32, arm64) and in multiple files.

4. Apply changes

For each reference found in step 3:

1. Start with `helix-platforms.yml` — it is a convenient central catalog for many Linux container-backed entries, but it is not the source of truth by itself

• Update the version comment (e.g. # Latest: 43 → # Latest: 44)
• Update the variable value — adjust the queue name and image tag to use the new version when the entry uses the container-backed format
• Preserve the existing host queue (e.g. AzureLinux.3.Amd64.Open) — this does not change with distro version updates
• Then continue through the other files until every matching reference is updated consistently

1. Update `helix-queues-setup.yml` files — libraries, coreclr, and installer templates

• Search for inline references to the old version and update them
• These are direct queue strings, not variable references

1. Version naming conventions — follow existing patterns exactly:

For Alpine edge queues, the casing of edge is not consistent across the repo (Alpine.edge.Amd64.Open in helix-platforms.yml vs Alpine.Edge.Amd64.Open in libraries/helix-queues-setup.yml). When updating queue strings, preserve the existing casing used in each file rather than normalizing to a single pattern.

AzureLinux (e.g. AzureLinux.3.Amd64.Open) appears as both a standalone VM queue and the primary host queue for container-based distros. It does not follow the container image pattern above.

Architecture suffixes vary: Amd64, Arm64, ArmArch, Arm32 for queue names; amd64, arm64v8, arm32v7 for image tags.

When both generic and processor-specific aliases exist in the registry (for example, ubuntu-26.04-helix-webassembly and ubuntu-26.04-helix-webassembly-amd64), prefer the processor-specific tag when the queue/environment is processor-specific:

• ...Amd64... queue → prefer *-amd64
• ...Arm64... / ...ArmArch... queue → prefer *-arm64v8
• ...Arm32... queue → prefer *-arm32v7