Add cloud-agnostic CI/CD pipeline deployment guide for Aspire applications

[Copilot]

Adds a new CI/CD deployment guide (deployment/cicd.mdx) to address the largest undocumented deployment gap identified from Discord community feedback (109+ questions about CI/CD integration with no dedicated documentation). The guide provides general, cloud-agnostic conceptual guidance for deploying Aspire apps from CI/CD pipelines to any container registry.

Changes Made

New page: deployment/cicd.mdx

• CI/CD workflow overview: Mermaid diagram and a <Steps> component explaining the three phases (Build & publish → Push → Deploy) that work with any target platform
• Running aspire publish in CI: Non-interactive by default; generates deployment artifacts (Docker Compose files, Kubernetes manifests, etc.) and builds container images locally
• Container registry authentication: Push patterns for GitHub Container Registry (GHCR), Docker Hub, and a note that Amazon ECR, Azure Container Registry, Google Artifact Registry, and self-hosted registries follow the same pattern; includes a LearnMore link to the end-to-end GHCR example in App lifecycle
• GitHub Actions workflow: Complete cloud-agnostic workflow using aspire publish + GHCR image push, with customizable deploy step (Docker Compose, kubectl apply, Helm, etc.); uses canonical curl -sSL https://aspire.dev/install.sh | bash CLI install
• Azure DevOps pipeline: Complete pipeline using generic docker login/docker push commands; uses canonical install script with ##vso[task.prependpath]
• CI environment tips: Terminal output (NO_COLOR), job timeouts, Docker availability on hosted agents, and deployment state caching patterns

Sidebar: deployment.topics.ts

Added "CI/CD pipelines" entry with translations for all 16 supported locales, positioned before the "Deploy to Azure" section.

Page preview

Testing

• ✅ All internal links return HTTP 200
• ✅ Page renders correctly with no MDX warnings
• ✅ Mermaid diagram processes successfully
• ✅ .NET version uses 10.x throughout
• ✅ <Steps> component renders correctly for the three-phase workflow

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Discord Feedback] Deployment & CI/CD documentation gaps</issue_title>
<issue_description>## Summary

Based on analysis of 20,415 Discord messages + 147 #help threads (April 2025 - February 2026).

Question counts:

Topic	Questions
Azure DevOps/Pipelines	87
azd integration	75
ACA/Container Apps	70
Kubernetes	54
aspire deploy	44
Container Registry	42
GitHub Actions	22

---

Docs That Exist

Slug	Title	Coverage
deploy-using-the-aspire-cli	Deploy using the Aspire CLI	✅ Basic ACA deployment
building-custom-deployment-pipelines	Building custom deployment pipelines	✅ Image building, progress reporting
publishing-and-deployment	Publishing and deployment	✅ Overview
deployment-manifest-format	Deployment manifest format	✅ Manifest structure
kubernetes-integration	Kubernetes integration	⚠️ Hosting only, not publishing

---

Gaps in Existing Docs

1. aspire deploy - Missing Topics (44 questions)

Customer Quotes:

"how does aspire deploy handle WaitFor? for example, if i set a database migration service to run before an api and frontend, how is this handled when deploying to i.e. azure?"

"did aspire deploy not get resource specific deploys like azd?"

Missing from deploy-using-the-aspire-cli:

• WaitFor behavior during deployment (vs local dev)
• Selective/resource-specific deployment
• aspire deploy vs azd comparison table
• Parameters file format and examples (partially mentioned but unclear per user feedback)
• Handling dev-only resources during deploy

---

2. CI/CD Integration - No Dedicated Docs (109 questions)

Verified: grep -i "github action\|azure devops\|ci\|cd\|pipeline" aspire-docs-list.txt returns no dedicated CI/CD guide.

Customer Quotes:

"Trying to work my way through some issues using the aspire cli in my Azure DevOps pipeline."

"Tests pass locally but fail in Azure DevOps because Cosmos uses principalType 'User' but CI uses Service Principal"

From #help threads:

• Tests run indefinitely in GitHub Actions
• CLI output formatting issues in Jenkins

Action Items:

• Azure DevOps pipeline setup guide
• GitHub Actions workflow examples
• Service Principal vs User principal for Azure resources in CI
• Running aspire CLI in detached mode for E2E tests
• CI environment compatibility (timeouts, terminal output)

---

3. Kubernetes Publishing - Incomplete (54 questions)

Verified: kubernetes-integration exists but covers hosting only, not publishing/deployment.

Customer Quotes:

"I was wondering if anyone has considered an option where you could orchestrate resources in an actual Kubernetes cluster running locally (with MiniKube, Kind, Docker Desktop)"

From #help threads:

• "How to get Kubernetes integration to use container registry image names?"
• AddKubernetesEnvironment() mentioned but undocumented

Action Items:

• AddKubernetesEnvironment() documentation
• Helm chart generation patterns
• Local Kubernetes (MiniKube, Kind) workflows
• cert-manager integration
• Aspirate mention/comparison

---

4. Container Registry / Airgapped (42 questions)

Verified: azure-container-registry-integration exists for ACR, but no private/airgapped patterns.

Customer Quotes:

"Is there an easy way to override container registry hostnames? Internally we use a jfrog artifactory proxy for mcr.microsoft.com."

"Could someone have a look at dotnet/aspire#14128? This would help us to support container registry mirrors in airgapped environments."

Action Items:

• Private/internal registry configuration
• mcr.microsoft.com proxy/mirror patterns
• Airgapped environment setup
• Enterprise registry authentication patterns

---

Data Source

• Discord channels: #��│general, #🔵│azure, #🔨│building-resources
• Help threads: 147 from #🆘│help
• Total messages: 20,415
• Date range: April 2025 - February 2026
• Verified against: aspire-list_docs and aspire-search_docs</issue_description>

<agent_instructions>Please address this issue, while using the .github/skills/doc-writer/SKILL.md. Be certain to also take into account, related issues, pull requests, links and comments that are directly linked as well as comments.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes [Discord Feedback] Deployment & CI/CD documentation gaps #331

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[IEvangelist]

This PR looks good so far, but let's double check it for accuracy by using the .github/skills/doc-tester/SKILL.md skill. Please also consider all new comments and feedback/suggestions. @copilot

[Copilot]

Pull request overview

This PR adds a comprehensive CI/CD deployment guide to address a significant documentation gap identified from Discord community feedback (109+ questions about CI/CD integration with no dedicated documentation). The guide covers deploying Aspire applications from GitHub Actions and Azure DevOps pipelines, with detailed setup instructions for both platforms.

Changes:

• Added new CI/CD deployment documentation covering non-interactive deployment, Azure authentication (OIDC/service principals), complete GitHub Actions and Azure DevOps pipeline examples, and CI environment best practices
• Added sidebar entry for "CI/CD pipelines" with translations for all 16 supported locales, positioned before the "Deploy to Azure" section

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
src/frontend/src/content/docs/deployment/cicd.mdx	New comprehensive guide documenting CI/CD deployment patterns for Aspire applications, including environment variables for non-interactive mode, authentication setup, and complete workflow/pipeline examples
src/frontend/config/sidebar/deployment.topics.ts	Added "CI/CD pipelines" sidebar entry with complete translations for all 16 locales (da, de, en, es, fr, hi, id, it, ja, ko, pt-BR, pt-PT, ru, tr, uk, zh-CN)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

This PR looks good so far, but let's double check it for accuracy by using the .github/skills/doc-tester/SKILL.md skill. Please also consider all new comments and feedback/suggestions. @copilot

Doc-tester results for deployment/cicd.mdx:

All checks passed ✅

• Page renders correctly — page title, sidebar entry ("CI/CD pipelines"), and all sections display as expected
• All 5 internal links return HTTP 200 — /deployment/deployment-state-caching/, /deployment/azure/aca-deployment-aspire-cli/, /deployment/azure/azure-security-best-practices/, /deployment/overview/, /reference/cli/commands/aspire-deploy/
• dotnet-version: '10.x' confirmed visible in rendered GitHub Actions workflow (b3eb860)
• azurecli code block language — produces the same existing warning as aca-deployment-aspire-cli.mdx, which uses the same language identifier; consistent with existing docs
• No broken MDX syntax, no unused imports, no casual language

Screenshots from the live dev server: the page title, the Cosmos DB principalType explanation, and the dotnet-version: '10.x' line are all correctly rendered.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• centralus-2.in.applicationinsights.azure.com
  • Triggering command: /home/REDACTED/.aspire/bin/aspire /home/REDACTED/.aspire/bin/aspire config set -g channel daily (dns block)
  • Triggering command: /home/REDACTED/.aspire/bin/aspire /home/REDACTED/.aspire/bin/aspire run --non-interactive --project /home/REDACTED/work/aspire.dev/aspire.dev/src/apphost/Aspire.Dev.AppHost/Aspire.Dev.AppHost.csproj --log-file /home/REDACTED/.aspire/logs/cli_20260223T000104812_detach-child_6b11857adbf14bc0b344be1437b8c65c.log (dns block)
  • Triggering command: /home/REDACTED/.aspire/bin/aspire aspire run --detach (dns block)
• telemetry.astro.build
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/aspire.dev/aspire.dev/src/frontend/node_modules/.bin/../astro/astro.js dev (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[IEvangelist]

Hey @copilot, please update this to be cloud agnostic. Right now it's specific to Azure - we really need it to be general/conceptual guidance on CI/CD for deploying to perhaps any container registry.

[Copilot]

Hey @copilot, please update this to be cloud agnostic. Right now it's specific to Azure - we really need it to be general/conceptual guidance on CI/CD for deploying to perhaps any co...

Done in c1c02b7. The guide is now cloud-agnostic:

• Removed: Azure CLI auth, OIDC with Azure App Registrations, AzureCLI@2 task, ACA-specific env vars
• Added: General publish→push→deploy workflow overview with Mermaid diagram; container registry section covering GHCR, Docker Hub, and generic registries; GitHub Actions workflow using aspire publish + GHCR push; Azure DevOps pipeline using generic docker login/docker push
• Azure is retained only in the "See also" section as a link to the platform-specific ACA deployment guide

The page structure is now:

1. CI/CD workflow overview (platform-agnostic)
2. Running aspire publish in CI
3. Pushing container images to a registry (GHCR / Docker Hub / generic)
4. GitHub Actions workflow
5. Azure DevOps pipeline
6. CI environment tips (terminal, timeouts, Docker, caching)

[IEvangelist]

Hey @copilot, please also link to /fundamentals/app-lifecycle/#step-3-build-app-create--push-image-to-ghcr where it makes sense to.

[Copilot]

Hey @copilot, please also link to /fundamentals/app-lifecycle/#step-3-build-app-create--push-image-to-ghcr where it makes sense to.

Added in 7b5e36e — a LearnMore link to /fundamentals/app-lifecycle/#step-3-build-app-create--push-image-to-ghcr now appears under the "GitHub Container Registry" section, which is the most natural placement since that's where users learn about GHCR authentication and push.

[IEvangelist]

Hey @copilot - please update the steps to install the CLI based on how we have it documented EVERYWHERE else. Not the .NET global tool.

[Copilot]

Hey @copilot - please update the steps to install the CLI based on how we have it documented EVERYWHERE else. Not the .NET global tool.

Updated in 760718f. Both examples now use the canonical install script:

GitHub Actions:

- name: Install Aspire CLI
  run: |
    curl -sSL https://aspire.dev/install.sh | bash
    echo "$HOME/.aspire/bin" >> $GITHUB_PATH

Azure DevOps:

- script: |
    curl -sSL https://aspire.dev/install.sh | bash
    echo "##vso[task.prependpath]$HOME/.aspire/bin"
  displayName: Install Aspire CLI

[IEvangelist]

Hey @copilot, please see my new comments - and could you take a screen shot of the page so that we might see how it looks, and add it to the PR description?

[Copilot]

Hey @copilot, please see my new comments - and could you take a screen shot of the page so that we might see how it looks, and add it to the PR description?

Screenshot added to the PR description and below — the page is rendering correctly with the sidebar entry "CI/CD pipelines" highlighted, the Mermaid architecture diagram, and the updated Steps component: