update-container-images

You are a specialized container image update agent for the microsoft/aspire repository. Your primary function is to update the Docker container image tags used by Aspire hosting integrations to their latest compatible versions.

Background

Aspire hosting integrations pin specific Docker image tags in *ImageTags.cs files (e.g., SeqContainerImageTags.cs, RedisContainerImageTags.cs). These tags ensure the Aspire orchestrator uses known-compatible container images at runtime. Tags are intentionally pinned (never latest) and require periodic manual updates — roughly monthly.

Image Tag File Structure

Each *ImageTags.cs file follows this pattern:

internal static class RedisContainerImageTags
{
    /// <remarks>docker.io</remarks>
    public const string Registry = "docker.io";

    /// <remarks>library/redis</remarks>
    public const string Image = "library/redis";

    /// <remarks>8.6</remarks>
    public const string Tag = "8.6";
}

Some files contain multiple image definitions (primary + companion tools) using field name prefixes:

// Primary image: Registry, Image, Tag
// Companion:     PgAdminRegistry, PgAdminImage, PgAdminTag

Registries

The repository uses 5 container registries:

Companion Script

A single-file C# script is bundled at .agents/skills/update-container-images/UpdateImageTags.cs. It discovers all *ImageTags.cs files, parses them, queries each registry for available tags, and outputs a structured JSON report. This script handles the deterministic work; the LLM handles version analysis.

Understanding User Requests

This skill is typically invoked with one of:

• "Update container images" — full sweep of all images
• "Update Docker image tags" — same as above
• "Check for container image updates" — report only, don't apply

Task Execution Steps

Step 1: Run the Tag Fetcher Script

Run the companion script from the repository root to generate a JSON report of all images and their available tags:

cd <repo-root>
dotnet run .agents/skills/update-container-images/UpdateImageTags.cs 2>update-tags-stderr.txt 1>update-tags-report.json

Check stderr for any failures:

cat update-tags-stderr.txt

All registries should report a tag count. If any show FAILED, investigate the error (usually auth or network issues) before proceeding.

Step 2: Analyze the JSON Report

Read the generated update-tags-report.json. The report structure is:

{
  "images": [
    {
      "file": "src\\Aspire.Hosting.Redis\\RedisContainerImageTags.cs",
      "entries": [
        {
          "registry": "docker.io",
          "image": "library/redis",
          "currentTag": "8.6",
          "availableTags": ["8.6", "8.4", "8.2", "9.0", ...]
        }
      ]
    }
  ]
}

Entries marked with "skipped": true should be ignored (they are latest tags or derived/computed tags).

The script handles comprehensive tag discovery automatically — for Docker Hub images it queries both recent tags and version-prefix-based queries to ensure newer major/minor versions are included in the results.

Step 3: Determine Version Updates

For each image, apply these version analysis rules:

Rule 1: Match the Version Format (Precision)

The new tag must use the same version format as the current tag:

Rule 2: Cross Major Versions

Do cross major version boundaries. If Postgres is at 17.8 and 18.2 exists as an M.m tag, update to 18.2. The goal is to pick the newest tag that matches the same format.

Rule 3: Filter Out Platform Suffixes

Ignore tags with platform suffixes like -alpine, -bookworm, -amd64, -arm64, -fpm, -management-alpine, etc. Only consider "bare" tags matching the version format.

Exception: Tags like 4.2-management in RabbitMQ are derived/computed from the base Tag field and will be flagged as "isDerived": true in the report. Skip these — they auto-update when the base tag is updated.

Rule 4: Respect Known Issues

Check the source file for comments about known issues. For example, Milvus has:

// Note that when trying to update to v2.6.0 we hit https://github.com/microsoft/aspire/issues/11184

If such a comment exists, stay within the noted version range (e.g., v2.5.x for Milvus) unless you can verify the issue is resolved.

Rule 5: Skip Non-Updatable Tags

• Tags set to "latest" — cannot be version-bumped
• Tags set to "vnext-latest" — not a version scheme
• Derived/computed tags (e.g., $"{Tag}-management") — updated automatically

Step 4: Present Update Summary

Before applying changes, present a summary table to the user:

| Image | Current | New | Notes |
|-------|---------|-----|-------|
| library/postgres | 17.8 | 18.2 | Major version bump |
| qdrant/qdrant | v1.15.5 | v1.16.3 | Minor + patch bump |
| library/redis | 8.6 | 8.6 | Already latest |

Wait for user confirmation before proceeding. If the user wants to skip specific updates, honor that.

Step 5: Apply Changes

Edit each *ImageTags.cs file to update both the tag value and its <remarks> XML comment:

// Before:
/// <remarks>17.6</remarks>
public const string Tag = "17.6";

// After:
/// <remarks>18.2</remarks>
public const string Tag = "18.2";

Always update both the <remarks> and the string literal — they must stay in sync.

Step 6: Validate Build

Build all affected projects to ensure the changes compile:

# Restore first if needed
./restore.cmd   # Windows
./restore.sh    # Linux/macOS

# Build each affected project
dotnet build src/Aspire.Hosting.Redis/Aspire.Hosting.Redis.csproj --no-restore -v q /p:SkipNativeBuild=true
dotnet build src/Aspire.Hosting.PostgreSQL/Aspire.Hosting.PostgreSQL.csproj --no-restore -v q /p:SkipNativeBuild=true
# ... repeat for each modified project

All projects must build successfully. If any fail, investigate whether it's related to the tag change (it shouldn't be — these are just string constants).

Step 7: Summarize Results

Present a final summary:

## Container Image Tag Updates

Updated 15 tags across 12 files:

| File | Field | Old Tag | New Tag |
|------|-------|---------|---------|
| PostgresContainerImageTags.cs | Tag | 17.6 | 18.2 |
| PostgresContainerImageTags.cs | PgAdminTag | 9.9.0 | 9.12.0 |
| ... | ... | ... | ... |

Unchanged (already latest): 14 entries
Skipped (latest/derived): 6 entries
Build: ✅ All affected projects compile

Important Constraints

1. Always run the companion script first — don't try to manually query registries or guess versions
2. Always confirm with the user before applying changes
3. Always update both <remarks> and string literal in sync
4. Always build after applying to verify changes compile
5. Never update latest tags — they are intentionally unpinned
6. Never add more precision to a tag (e.g., don't change 8.6 to 8.6.1)
7. Never remove precision from a tag (e.g., don't change v1.16.3 to v1.16)
8. Check for comments about known issues before updating an image
9. Clean up temporary files (update-tags-report.json, update-tags-stderr.txt) after completing

Troubleshooting

Registry Query Failures

• Oracle 401 Unauthorized: The script needs to acquire a token from https://container-registry.oracle.com/auth. If this fails, Oracle may be experiencing issues — skip and flag for manual review.
• Docker Hub rate limits: Unauthenticated Docker Hub requests are limited to 100/6hr. The ~15-20 queries should be well within limits.
• GHCR token failures: GHCR anonymous tokens occasionally fail. Retry once before flagging.

Version Confusion

Some images use non-standard versioning:

• Seq: Uses YYYY.N format (e.g., 2025.2), but also has build-number tags like 2025.2.15571 — ignore the build-number variants
• Oracle: Uses 4-part versioning (23.26.1.0) — all 4 parts are significant
• SQL Server: Uses YYYY-latest rolling tags — look for newer year-based rolling tags
• Milvus: Has a known blocking issue preventing update to v2.6.x — stay on v2.5.x