Document deployment state caching for local deployments

[Copilot]

Overview

This PR adds comprehensive documentation for the deployment state caching feature introduced in Aspire 13, addressing issue #5187. The aspire deploy command now caches deployment state locally to streamline repeated deployments by preserving provisioning settings and parameters.

Changes

New Documentation

Local deployment state article (docs/deployment/aspire-deploy/local-deployment-state.md)

• Documents how deployment state is managed through cached configuration files stored in ~/.aspire/deployments/{AppHostSha}/{environment}.json
• Explains default behavior for first and subsequent deployments
• Covers environment-specific deployments using the --environment flag
• Details cache management with the --clear-cache flag
• Includes security considerations addressing community concerns about plain text storage of secrets, following the same pattern as .NET's user secrets manager
• Provides GitHub Actions CI/CD example demonstrating how to cache deployment state across pipeline runs using actions/cache
• Includes introductory paragraphs for each major section to provide context and improve readability

Updated CLI Reference

aspire deploy command reference (docs/cli-reference/aspire-deploy.md)

• Added documentation for --environment flag: specifies the deployment environment name (defaults to production)
• Added documentation for --clear-cache flag: clears cached deployment state before deploying without persisting new values
• Included practical examples demonstrating both flags
• Added cross-reference to the deployment state article

Updated Deployment Guide

Azure Container Apps deployment guide (docs/deployment/aspire-deploy/aca-deployment-aspire-cli.md)

• Removed outdated note stating deployment state is not supported
• Added reference to the new deployment state documentation

Navigation

Table of contents (docs/toc.yml)

• Added the new article to the "Azure deployment with Aspire" section
• Positioned logically after deployment guides and before security best practices
• Included relevant display name keywords for discoverability

Key Features Documented

• Caching behavior: Deployment settings are saved locally after first deployment and automatically loaded on subsequent deployments with user confirmation
• Environment isolation: Each environment (production, staging, etc.) maintains its own isolated deployment state
• Cache management: Users can clear cached state using --clear-cache flag for one-time deployments without persistence
• Security: Clear guidance on how secrets are stored locally outside source control, similar to .NET user secrets
• CI/CD integration: Practical GitHub Actions workflow example showing how to persist deployment state across pipeline runs

Closes #5187

Original prompt

Please create a PR to work on @dotnet/docs-aspire/issues/5187. The issue description has tons of great details to start with and the comments in the issue are good at helping inform you of how to phrase and message this to avoid confusion.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

---

Internal previews

📄 File	🔗 Preview link
docs/cli-reference/aspire-deploy.md	docs/cli-reference/aspire-deploy
docs/deployment/aspire-deploy/aca-deployment-aspire-cli.md	docs/deployment/aspire-deploy/aca-deployment-aspire-cli
docs/deployment/aspire-deploy/local-deployment-state.md	docs/deployment/aspire-deploy/local-deployment-state
docs/toc.yml	docs/toc

[IEvangelist]

This is a great start, @copilot please address all feedback.

[IEvangelist]

Please add an introductory sentence, or short paragraph to describe this section.

[Copilot]

Added introductory paragraph to the "Default behavior" section in commit 4ed162e.

[IEvangelist]

For the first time, or for the first time in a target --environment.

[Copilot]

Updated to clarify "for the first time, or for the first time in a target --environment" in commit 4ed162e.

[IEvangelist]

References to files should be italicized, not code blocks.

[Copilot]

Changed file references to italics throughout the document in commit 4ed162e.

[IEvangelist]

Again, please add an intro paragraph here. Perhaps use this opportunity to explain why environment-specific deploys are important.

[Copilot]

Added introductory paragraph explaining the importance of environment-specific deployments in commit 4ed162e.

[IEvangelist]

Please add a brief introduction here.

[Copilot]

Added brief introduction to the "Cache management" section in commit 4ed162e.

[IEvangelist]

Italic for files and paths. Also, need proper punctuation on all bullet lists.

Suggested change

	- **Path pattern:** `~/.aspire/deployments/{AppHostSha}/{environment}.json`
	- **Default environment:** `production`
	- **AppHostSha:** A hash value representing the application host configuration, ensuring deployment states are specific to each application configuration.
	- **Path pattern:** _~/.aspire/deployments/{AppHostSha}/{environment}.json_.
	- **Default environment:** `production`.
	- **AppHostSha:** A hash value representing the application host configuration, ensuring deployment states are specific to each application configuration.

[Copilot]

Applied formatting changes: italicized file paths and added proper punctuation to all bullet lists in commit 4ed162e.

[IEvangelist]

It might be really nice to include a simple GitHub example, that conceptually describes and shows how to persist the local state using @actions/cache or something like that.

[Copilot]

Added a complete "Use deployment state in CI/CD pipelines" section with a GitHub Actions example showing how to cache deployment state using actions/cache in commit 4ed162e. The example includes cache key strategies and a security caution about managing sensitive values.

[Copilot]

This is a great start, @copilot please address all feedback.

All feedback has been addressed in commit 4ed162e.

[IEvangelist]

Thoughts on this @captainsafia