Add Push and PushPrereq pipeline steps for ContainerRegistryResource

[Copilot]

Description

Adds pipeline infrastructure for pushing container images to ContainerRegistryResource instances. The registry resource now directly creates push steps for all resources that reference it.

Key changes:

• Add WellKnownPipelineSteps.Push and WellKnownPipelineSteps.PushPrereq constants
• ContainerRegistryResource registers PipelineStepAnnotation to create per-resource push steps
• ContainerRegistryResource registers PipelineConfigurationAnnotation to wire Build → Push dependencies
• Push unconditionally depends on PushPrereq to ensure annotations are set up before any push operations
• PushPrereq step automatically adds ContainerRegistryReferenceAnnotation to resources that don't have one when a single registry exists (required for correct remote image tag computation during push)
• GetResourcesToPush only includes resources with ContainerRegistryReferenceAnnotation matching the target registry
• Clear error when multiple registries exist without explicit .WithContainerRegistry() annotation

Example usage:

// Single registry - automatic selection, no annotation needed
var dockerHub = builder.AddContainerRegistry("docker-hub", "docker.io", "myusername");
var api = builder.AddProject<Projects.MyApi>("api");
// api will automatically push to docker-hub

// Multiple registries - explicit annotation required
var dockerHub = builder.AddContainerRegistry("docker-hub", "docker.io", "myuser");
var ghcr = builder.AddContainerRegistry("ghcr", "ghcr.io", "myorg");
var api = builder.AddProject<Projects.MyApi>("api")
    .WithContainerRegistry(dockerHub);  // Required when multiple registries exist

Checklist

• Is this feature complete?
  • Yes. Ready to ship.
  • No. Follow-up changes expected.
• Are you including unit tests for the changes and scenario tests if relevant?
  • Yes
  • No
• Did you add public API?
  • Yes
    • If yes, did you have an API Review for it?
      • Yes
      • No
    • Did you add <remarks /> and <code /> elements on your triple slash comments?
      • Yes
      • No
  • No
• Does the change make any security assumptions or guarantees?
  • Yes
    • If yes, have you done a threat model and had a security review?
      • Yes
      • No
  • No
• Does the change require an update in our Aspire docs?
  • Yes
    • Link to aspire-docs issue (consider using one of the following templates):
      • New (or update) doc-idea template
      • New breaking-change template
      • New diagnostic template
  • No

Original prompt

Container Registry Push Pipeline Step Plan

Overview

This plan proposes adding support for pushing container images to ContainerRegistryResource instances through a well-known pipeline step. The ContainerRegistryResource will directly register pipeline steps for all resources that reference it.

Motivation

Currently, the ContainerRegistryResource serves as a reference for container registries but doesn't participate in the deployment pipeline. To enable deployment scenarios where containers need to be pushed to external registries (Docker Hub, GHCR, private registries), we need to:

1. Add pipeline step infrastructure to push images to the registry
2. Create a well-known pipeline step constant for image push operations
3. Wire up dependencies so push happens after build and before deploy

The reference implementation from https://github.com/captainsafia/aspire-image-push demonstrates this need with a custom pipeline step that pushes images to a parameterized container registry.

Goals

1. Add WellKnownPipelineSteps.Push as a well-known pipeline step
2. Enable ContainerRegistryResource to directly create push steps for all resources that require image push
3. Provide automatic registry selection when only one registry exists (no annotation required)
4. Enforce explicit annotation requirement when multiple registries exist with clear error messages
5. Ensure proper dependency ordering: Build → Push → Deploy
6. Follow the same error handling pattern as DeploymentTargetAnnotation for consistency

API Design

1. Add Well-Known Pipeline Step

Add a new constant to WellKnownPipelineSteps.cs:

public static class WellKnownPipelineSteps
{
    // ... existing steps ...

    /// <summary>
    /// The meta-step that coordinates all push operations.
    /// All push steps should be required by this step.
    /// </summary>
    public const string Push = "push";

    /// <summary>
    /// The prerequisite step that runs before any push operations.
    /// </summary>
    public const string PushPrereq = "push-prereq";
}

2. ContainerRegistryResource Pipeline Integration

Update ContainerRegistryResource to directly create push steps for all resources that reference it:

public class ContainerRegistryResource : Resource, IContainerRegistry
{
    public ContainerRegistryResource(string name, ReferenceExpression endpoint, ReferenceExpression? repository = null)
        : base(name)
    {
        ArgumentNullException.ThrowIfNull(endpoint);

        _registryName = ReferenceExpression.Create($"{name}");
        _endpoint = endpoint;
        _repository = repository;

        Annotations.Add(new PipelineStepAnnotation(factoryContext =>
        {
            var model = factoryContext.PipelineContext.Model;
            var steps = new List<PipelineStep>();

            var allRegistries = model.Resources.OfType<IContainerRegistry>().ToArray();
            var hasMultipleRegistries = allRegistries.Length > 1;

            foreach (var resource in model.Resources)
            {
                if (!resource.RequiresImageBuildAndPush())
                {
                    continue;
                }

                var targetRegistry = GetTargetRegistryForResource(resource, this, allRegistries, hasMultipleRegistries);
                if (targetRegistry is null || !ReferenceEquals(targetRegistry, this))
                {
                    continue;
                }

                var pushStep = new PipelineStep
                {
                    Name = $"push-{resource.Name}",
                    Action = async ctx =>
                    {
                        var containerImageManager = ctx.Services.GetRequiredService<IResourceContainerImageManager>();
                        await containerImageManager.PushImageAsync(resource, ctx.CancellationToken).ConfigureAwait(false);
                    },
                    Tags = [WellKnownPipelineTags.PushContainerImage],
                    RequiredBySteps = [WellKnownPipelineSteps.Push],
                    Resource = resource
                };

                steps.Add(pushStep);
            }

            return steps;
        }));

        Annotations.Add(new PipelineConfigurationAnnotation(context =>
        {
            foreach (var resource in context.Model.Resources)
            {
                if (!resource.RequiresImageBuildAndPush())
                {
                    continue;
                }

                var allRegistries = context.Model.Resources.OfType<IContainerRegistry>().ToArray();
                var hasMultipleRegistries = allRegistries.Length > 1;

                var targetRegistry = GetTargetRegistryForResource(resource, this, allRegistries, hasMultipleRegistries);
                if (targetRegistry is null || !ReferenceEquals(targetRegistry, this))
                {
                    continue;
                }

                var buildSteps = context.GetSteps(resour...

</details>



<!-- START COPILOT CODING AGENT TIPS -->
---

✨ Let Copilot coding agent [set things up for you](https://github.com/dotnet/aspire/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo.

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 13306

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 13306"

[captainsafia]

@copilot Bleh, we need to have the ContainerRegistryReferenceAnnotation on all resources so that we can correctly compute the remote image tag during the push phase. Add a PushPrereq step that will add the ContainerRegistryReferenceAnnotation to resources that don't already have it when a single container registry exists in the app model. When multiple registries exist, throw an exception that the user must call WithContainerRegistry explicitly.

[Copilot]

@copilot Bleh, we need to have the ContainerRegistryReferenceAnnotation on all resources so that we can correctly compute the remote image tag during the push phase. Add a PushPrereq step that will ad...

Done in ed1e587. The PushPrereq step now adds ContainerRegistryReferenceAnnotation to resources that don't have it when a single container registry exists. When multiple registries exist, it throws an InvalidOperationException requiring the user to call WithContainerRegistry explicitly.

[davidfowl]

Does this break when you have 2 compute environments now?

[captainsafia]

Does this break when you have 2 compute environments now?

Probably, lol. TBH, I haven't gotten that far. I'm just trying to get the end-to-end over in aspire-image-push working before layering on things.

My intuition tells me that as a fall out of this PR we'll need to model the Azure Container Registry that is implicitly in the compute environments as an explicit thing and always model the push steps on a resource that implements IContainerRegistry instead of within the compute environments.

[captainsafia]

@copilot We need to make sure that the PushPrereq runs unconditionally on compute resources that need a push. Currently, GetResourcesToPush introduces a gap in the implementation because we will never wire up the PipelineStepConfiguration for the PushPrereq if there isn't already a ContainerRegistryReferenceAnnotation set (which is done by the PushPrereq).

[Copilot]

@copilot We need to make sure that the PushPrereq runs unconditionally on compute resources that need a push. Currently, GetResourcesToPush introduces a gap in the implementation because we will never...

Fixed in 335a826. Refactored GetResourcesToPush to include resources without ContainerRegistryReferenceAnnotation when a single registry exists, ensuring PipelineConfigurationAnnotation correctly wires up the PushPrereq dependency even before the annotation is added at runtime.

[davidfowl]

CreateDefaultAzureContainerRegistry

[captainsafia]

OK, I tested the changes in 9c45f96 against the following scenarios.

1. Clean aspire do push with a single registry
2. Clean aspire deploy with a single ACA compute environment
3. aspire do push on deployment state from Step 2
4. Clean aspire do push with a single ACA compute environment
5. Clean aspire do push with multiple registries
6. Clean aspire deploy with multiple compute environments

[davidfowl]

21:58:04 (push-prereq) → Starting push-prereq...
21:58:04 (push-prereq) ✗ [ERR] Step 'push-prereq' failed.
21:58:04 (push-prereq) ✗ Step 'push-prereq' failed: Resource 'server' requires image push but no container registry is available. Please add a container
registry using 'builder.AddContainerRegistry(...)' or specify one with '.WithContainerRegistry(registryBuilder)'.
21:58:04 (pipeline-execution) ✗ [ERR] Step 'push-prereq' failed: Resource 'server' requires image push but no container registry is available. Please add a
container registry using 'builder.AddContainerRegistry(...)' or specify one with '.WithContainerRegistry(registryBuilder)'.
21:58:04 (pipeline-execution) ✗ Failed

[davidfowl]

This fails without .WithContainerRegistry(acr);

var builder = DistributedApplication.CreateBuilder(args);

var acr = builder.AddAzureContainerRegistry("acr");

var cache = builder.AddRedis("cache");

#pragma warning disable ASPIRECOMPUTE003 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.

var server = builder.AddProject<Projects.FeBackend_Server>("server")
    .WithReference(cache)
    .WaitFor(cache)
    .WithHttpHealthCheck("/health");

var webfrontend = builder.AddViteApp("webfrontend", "../frontend")
    .WithReference(server)
    .WaitFor(server)
    .WithExternalHttpEndpoints();

server.PublishWithContainerFiles(webfrontend, "wwwroot");

builder.Build().Run();

[captainsafia]

@davidfowl Yeah, we're currently only setting the RegistryTargetAnnotation when you call AddContainerRegistry. Should be easy to fix though...