Document deployment state caching

[Copilot]

• Create new article about deployment state caching at deployment/aspire-deploy/local-deployment-state.md
• Update table of contents (toc.yml) to include new article
• Update aca-deployment-aspire-cli.md to reference new article and remove note about unsupported deployment state
• Document deployment state caching behavior including:
  • Default behavior (first and subsequent deployments)
  • Environment-specific deployments
  • Cache management with --clear-cache flag
  • File storage location
  • Security considerations based on comments
• Update aspire-deploy CLI reference to document --environment and --clear-cache flags
• Test markdown linting - all files pass validation
• Verify all relative links are correct
• Address feedback from @IEvangelist:
  • Add introductory paragraphs to major sections
  • Clarify "first time" to include environment context
  • Italicize file paths instead of code blocks
  • Add proper punctuation to bullet lists
  • Add GitHub Actions CI/CD example for caching deployment state
  • Move documentation out of Azure TOC section (not Azure-specific)
  • Rename file, H1, and TOC entry to "Deployment state caching"
  • Update all references and add redirect for old URL
  • Clarify that actions/cache automatically saves deployment state after deploy

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/deployment-state-caching.md	docs/deployment/deployment-state-caching
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

[IEvangelist]

Hey @copilot please move this out of the Azure TOC section, as it's not specific to Azure. Also, please rename the doc, the H1 and the TOC entry to Deployment state caching.

[Copilot]

Hey @copilot please move this out of the Azure TOC section, as it's not specific to Azure. Also, please rename the doc, the H1 and the TOC entry to Deployment state caching.

Moved the documentation out of the Azure TOC section to sit directly under "Publish and Deploy" in commit 5ab8d29. Also renamed:

• File: local-deployment-state.md → deployment-state-caching.md
• Location: deployment/aspire-deploy/ → deployment/
• Title/H1: "Local deployment state" → "Deployment state caching"
• TOC entry: "Local deployment state" → "Deployment state caching"

Updated all references and added a redirect for the old URL.

[IEvangelist]

Hey @copilot do we need to also cache the deployment state after the deploy here too?

[Copilot]

The actions/cache@v4 action automatically saves the cache after the job completes successfully - no additional step needed. Updated the explanation in commit 2d0bdce to explicitly mention that the cache is automatically saved after the deployment step runs.