File: themes/default/content/docs/pulumi-cloud/deployments/reference.md

The "Using Deployments" page in the docs is currently one long page, which makes it difficult to scan and consume. In addition, the content is haphazardly organized.

The content should be organized as follows, without any major changes to the content:

• Using Deployments: (converted to a landing/overview page)
  • Deployment Settings
  • Deployment Triggers
  • Private Git Repositories and Package Feeds (give this a shorter title)
  • Post-Deployment Automation

Details on each page's content below:

Using Deployments

This should be a git mv from the original, long page. It should be named _index.md and in a new subdirectory called using.

Explain to the user that:

• Deployments are configured on a per-stack basis
• First you set up deployment settings, explain in brief what these entail and give a link to the page
• Then you'll want to set up triggers. A good starting point is:
  • Preview when a PR is created
  • Update when a PR is merged to main
• Then, you may want to expand Deployments usage to:
  • Drift detection
  • Review stacks for temporary environments on PRs
  • TTL stacks for ephemeral environments
  • Dependent stack updates (like for dev -> staging -> prod)
  • Webhooks
• Note that Deployments can be automated for usage at scale via:
  • The Pulumi Cloud provider (give a link to the Deployment Settings resource in the registry at /registry/packages/pulumiservice/api-docs/deploymentsettings)
  • The REST API

Deployments Settings Page

Add some summary text to the top of the page, and then include these sections from the prior content, in order:

• Creating Deployment Settings
• Deployment Runner Pools
• Pre-Run Commands
• Path filtering
• Skipping automatic dependency installation
• Skipping intermediate deployments
• Custom executor images (renamed from "customizing the deployment environment")
  • Add in a caveat that we only support static credentials using the note "info" shortcode
• Environment variables
• Open ID Connect (OIDC)

Deployment Triggers

Add some summary text to the top of the page, the include the following sections from the original single-page content, in order:

• Click to Deploy
• GitHub Push to Deploy
• TTL Stacks
• Review Stacks
• REST API

Private Git Repos and Package Feeds

Include the relevant sections from the original single-page content and add an introductory paragraph

Post-Deployment Automation

Move the content here that talks about dependent stack updates, and mention any applicable webhooks.