docs(deployments): restructure into Concepts and Operations sections (#19699) (#19755)

- Move pages into concepts/ and operations/ (aliases preserved)
- Merge intro into the Concepts landing; rewrite to be non-marketing
- Rewrite Triggers page; make Source settings generic across VCS integrations
- Split Runners into Pulumi-managed and Customer-managed pages
- Add Deployment queue topic; remove all screenshots
- Fix code-in-notes rendering (_notes.scss)
- Sweep internal links repo-wide to new canonical paths

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jkodroff

content/docs/administration/access-identity/oidc-issuers/kubernetes-eks.md

@@ -27,7 +27,7 @@ This document outlines the steps required to configure Pulumi Cloud to accept El
 This integration is most often used to authenticate workloads that run Pulumi operations from inside an EKS cluster, without storing long-lived Pulumi access tokens. Two common scenarios:
 
 - **[Pulumi Kubernetes Operator](/docs/integrations/clouds/kubernetes/pulumi-kubernetes-operator/)** — Run Pulumi stacks as Kubernetes custom resources. The operator's workspace pods authenticate to Pulumi Cloud using the cluster's OIDC tokens instead of a static `PULUMI_ACCESS_TOKEN`.
-- **[Customer-managed deployment runners](/docs/deployments/deployments/runners/)** — Run Pulumi Deployments inside your own EKS cluster. The workflow runner fetches a Pulumi Pool token dynamically using its OIDC identity.
+- **[Customer-managed deployment runners](/docs/deployments/concepts/customer-managed-runners/)** — Run Pulumi Deployments inside your own EKS cluster. The workflow runner fetches a Pulumi Pool token dynamically using its OIDC identity.
 
 {{< notes type="info" >}}
 This guide walks through the Pulumi Cloud UI. You can also configure OIDC Issuers via the [REST API](/docs/reference/cloud-rest-api/oidc-issuers/) or the [`OidcIssuer`](https://www.pulumi.com/registry/packages/pulumiservice/api-docs/oidcissuer/) resource in the Pulumi Service provider.

content/docs/administration/access-identity/oidc-issuers/kubernetes-gke.md

@@ -25,7 +25,7 @@ See ["Bound Tokens"](https://cloud.google.com/blog/products/containers-kubernete
 This integration is most often used to authenticate workloads that run Pulumi operations from inside a GKE cluster, without storing long-lived Pulumi access tokens. Two common scenarios:
 
 - **[Pulumi Kubernetes Operator](/docs/integrations/clouds/kubernetes/pulumi-kubernetes-operator/)** — Run Pulumi stacks as Kubernetes custom resources. The operator's workspace pods authenticate to Pulumi Cloud using the cluster's OIDC tokens instead of a static `PULUMI_ACCESS_TOKEN`.
-- **[Customer-managed deployment runners](/docs/deployments/deployments/runners/)** — Run Pulumi Deployments inside your own GKE cluster. The workflow runner fetches a Pulumi Pool token dynamically using its OIDC identity.
+- **[Customer-managed deployment runners](/docs/deployments/concepts/customer-managed-runners/)** — Run Pulumi Deployments inside your own GKE cluster. The workflow runner fetches a Pulumi Pool token dynamically using its OIDC identity.
 
 {{< notes type="info" >}}
 This guide walks through the Pulumi Cloud UI. You can also configure OIDC Issuers via the [REST API](/docs/reference/cloud-rest-api/oidc-issuers/) or the [`OidcIssuer`](https://www.pulumi.com/registry/packages/pulumiservice/api-docs/oidcissuer/) resource in the Pulumi Service provider.

content/docs/administration/onboarding-guide/ways-of-working.md

@@ -91,8 +91,8 @@ It's common to give developers their own stacks for development and testing. Pul
 
 - **Individual developer stacks**: Each developer gets their own complete environment
 - **Shared infrastructure**: Developers share costly resources like databases while having their own application instances
-- **[Review stacks](/docs/deployments/deployments/review-stacks/)**: Short-lived stacks for each pull request that are automatically torn down
-- **[TTL stacks](/docs/deployments/deployments/ttl/)**: Automatically destroyed after a specified timeframe to prevent cloud waste
+- **[Review stacks](/docs/deployments/concepts/review-stacks/)**: Short-lived stacks for each pull request that are automatically torn down
+- **[TTL stacks](/docs/deployments/concepts/ttl/)**: Automatically destroyed after a specified timeframe to prevent cloud waste
 
 Use [stack references](/blog/iac-best-practices-applying-stack-references/) to factor out shared infrastructure and create flexible project architectures.
 
@@ -125,7 +125,7 @@ While most teams start by running the Pulumi CLI manually, you'll eventually wan
 
 **CI/CD platform options:**
 
-- **[Pulumi Deployments](/docs/deployments/deployments/)** (recommended): Purpose-built for IaC deployments and integrated into Pulumi Cloud
+- **[Pulumi Deployments](/docs/deployments/concepts/)** (recommended): Purpose-built for IaC deployments and integrated into Pulumi Cloud
 - **[Pulumi Kubernetes Operator](/docs/integrations/clouds/kubernetes/pulumi-kubernetes-operator/)**: Trigger deployments from within Kubernetes clusters
 - **Existing CI/CD solutions**: GitHub Actions, GitLab CI, Octopus Deploy, and [many others](/docs/iac/operations/continuous-delivery/)
 
@@ -142,7 +142,7 @@ While most teams start by running the Pulumi CLI manually, you'll eventually wan
 
 ### Guarding against drift
 
-Drift occurs when changes happen outside your IaC pipeline, causing conflicts between your last known deployment and your cloud resources' current state. This can cause security issues or outages during your next deployment. Pulumi supports [detecting and remediating drift](/docs/deployments/deployments/drift).
+Drift occurs when changes happen outside your IaC pipeline, causing conflicts between your last known deployment and your cloud resources' current state. This can cause security issues or outages during your next deployment. Pulumi supports [detecting and remediating drift](/docs/deployments/concepts/drift).
 
 ## Integrating with and extending Pulumi
 
@@ -156,7 +156,7 @@ The well-documented, powerful API that powers the CLI and cloud console experien
 **[Pulumi Automation API](/docs/iac/concepts/automation-api/)**
 Embed IaC capabilities into any software, enabling custom tools, self-serve portals, complex deployment orchestrations, and even SaaS products that provision cloud resources.
 
-**[Pulumi Cloud Webhooks](/docs/deployments/webhooks/)**
+**[Pulumi Cloud Webhooks](/docs/deployments/concepts/webhooks/)**
 React to lifecycle events in Pulumi Cloud by invoking custom REST API endpoints. Use these for posting to Slack channels, triggering test runs after deployments, and more.
 
 ### Writing your own IaC providers

content/docs/administration/self-hosting/components/api.md

@@ -468,7 +468,7 @@ scrape_configs:
 In order to enable [Pulumi Deployments](/docs/pulumi-cloud/deployments), the following must be configured:
 
 * `PULUMI_SERVICE_METADATA_BLOB_STORAGE_ENDPOINT` or `PULUMI_LOCAL_OBJECTS` [object storage](#object-storage)
-* [Customer-Managed Workflow Runners](/docs/deployments/deployments/runners/) - You also need to update the `pulumi-workflow-agent.yaml` [configuration file](/docs/deployments/deployments/runners/#configuration-reference) by setting `service_url` to `<PULUMI_API_DOMAIN>`. Example:
+* [Customer-Managed Workflow Runners](/docs/deployments/concepts/customer-managed-runners/) - You also need to update the `pulumi-workflow-agent.yaml` [configuration file](/docs/deployments/concepts/customer-managed-runners/#configuration-reference) by setting `service_url` to `<PULUMI_API_DOMAIN>`. Example:
 
     ```yaml
     token: pul-d2d2….

content/docs/administration/self-hosting/components/deployments.md

@@ -20,7 +20,7 @@ aliases:
 To manage your state with a self-managed backend, such as a cloud storage bucket, see [State and Backends](/docs/concepts/state/).
 {{< /self-hosting-trial-note >}}
 
-[Pulumi Deployments](/docs/deployments/deployments/) is fully supported in Kubernetes-managed self-hosted environments. If you're using Kubernetes to manage your self-hosted Pulumi Cloud installation, you can enable Pulumi Deployments features by configuring a Kubernetes-native workflow runner pool in Pulumi Cloud and installing one or more [customer-managed workflow runners](/docs/deployments/deployments/runners/) into your installation's Kubernetes cluster. In addition to deployments, customer-managed workflow runners also support [Insights](/docs/insights/) discovery scans and [policy evaluations](/docs/insights/policy/).
+[Pulumi Deployments](/docs/deployments/concepts/) is fully supported in Kubernetes-managed self-hosted environments. If you're using Kubernetes to manage your self-hosted Pulumi Cloud installation, you can enable Pulumi Deployments features by configuring a Kubernetes-native workflow runner pool in Pulumi Cloud and installing one or more [customer-managed workflow runners](/docs/deployments/concepts/customer-managed-runners/) into your installation's Kubernetes cluster. In addition to deployments, customer-managed workflow runners also support [Insights](/docs/insights/) discovery scans and [policy evaluations](/docs/insights/policy/).
 
 To do so, follow these steps:
 

content/docs/deployments/_index.md

@@ -27,11 +27,11 @@ sections:
   - icon: rocket-launch
     heading: Deployments
     description: Managed CI/CD platform with git integration, automated drift detection and remediation, ephemeral review stacks for pull requests, scheduled operations, and TTL-based cleanup for temporary infrastructure.
-    link: /docs/deployments/deployments/
+    link: /docs/deployments/concepts/
   - icon: bell
     heading: Webhooks
     description: Trigger external systems and workflows in response to stack updates, deployments, drift detection, and policy violations. Integrates with Slack, Microsoft Teams, or custom webhooks.
-    link: /docs/deployments/webhooks/
+    link: /docs/deployments/concepts/webhooks/
 
 - type: flat
   heading: Have questions?

content/docs/deployments/concepts/_index.md

@@ -0,0 +1,56 @@
+---
+title: Concepts
+title_tag: "Pulumi Deployments"
+h1: "Pulumi Deployments"
+meta_desc: What Pulumi Deployments is, why it exists, and an overview of its core concepts.
+meta_image: /images/docs/meta-images/docs-meta.png
+menu:
+  deployments:
+    parent: deployments-home
+    identifier: deployments-concepts
+    weight: 10
+aliases:
+- /docs/deployments/concepts/introduction/
+- /docs/deployments/deployments/
+- /docs/pulumi-cloud/deployments/
+- /docs/platform/deployments/
+- /docs/intro/pulumi-service/deployments/
+- /docs/intro/deployments/
+- /docs/intro/deployments/platform/
+- /docs/pulumi-cloud/deployments/platform/
+- /docs/pulumi-cloud/deployments/using/
+- /docs/pulumi-cloud/deployments/using-deployments/
+- /docs/deployments/deployments/reference/
+- /docs/pulumi-cloud/deployments/reference/
+- /docs/platform/deployments/reference/
+- /docs/intro/deployments/reference/
+---
+
+Pulumi Deployments is a managed service that runs Pulumi operations — `pulumi up`, `preview`, `refresh`, and `destroy` — on Pulumi-hosted or self-hosted compute rather than on a developer's machine. You configure how a stack should be deployed once, and Pulumi Cloud runs those operations for you: on demand, in response to version control events, on a schedule, or through the REST API.
+
+## Why Pulumi Deployments exists
+
+Running infrastructure updates from local machines or hand-built CI pipelines is hard to keep consistent and secure. Every engineer needs cloud credentials, the toolchain has to be installed and version-pinned, and there is no shared record of what ran or who ran it.
+
+Pulumi Deployments moves that work into a managed, isolated environment that already has the Pulumi CLI and language runtimes installed. Cloud credentials and secrets are supplied through [Pulumi ESC](/docs/pulumi-cloud/esc) and OIDC instead of living on laptops or in pipeline configuration, deployments can run automatically from your [version control system](/docs/integrations/version-control/), and every run is recorded in Pulumi Cloud. A stack's [deployment settings](/docs/deployments/concepts/settings/) capture everything a run needs — source location, credentials, environment variables, and build requirements — so the same deployment behaves the same way no matter what triggers it.
+
+## In this section
+
+- **[Deployments Settings](/docs/deployments/concepts/settings/)** — the per-stack configuration that defines how a deployment runs: source, credentials, environment variables, path and tag filters, and runner pool.
+- **[Deployment Triggers](/docs/deployments/concepts/triggers/)** — the ways a deployment is initiated, including the console's Click to Deploy, the REST API, and webhooks.
+- **[Drift Detection](/docs/deployments/concepts/drift/)** — detecting when deployed infrastructure no longer matches your Pulumi program, and optionally remediating it on a schedule.
+- **[TTL Stacks](/docs/deployments/concepts/ttl/)** — automatically destroying a stack at a set time, for temporary or ephemeral environments.
+- **[Review Stacks](/docs/deployments/concepts/review-stacks/)** — ephemeral environments stood up automatically for each pull request and torn down when it closes.
+- **[Scheduled operations](/docs/deployments/concepts/schedules/)** — running any Pulumi operation on a recurring schedule.
+- **[Pulumi-managed runners](/docs/deployments/concepts/pulumi-managed-runners/)** — the Pulumi-hosted compute that runs deployments by default, including its hardware and image.
+- **[Customer-managed runners](/docs/deployments/concepts/customer-managed-runners/)** — self-hosting that compute on your own infrastructure.
+- **[Webhooks](/docs/deployments/concepts/webhooks/)** — notifying external systems, or triggering other stacks, in response to events in your Pulumi organization.
+
+For task-oriented walkthroughs — supplying cloud credentials, building custom images, configuring OIDC, and more — see the [Deployments guides](/docs/deployments/guides/).
+
+## Getting started
+
+To start using Pulumi Deployments:
+
+1. Create a new project with the Pulumi Cloud [New Project Wizard](/docs/idp/concepts/new-project-wizard), which configures Deployments for your repository automatically, or
+1. Follow the [Getting Started guide](/docs/deployments/get-started/) to set it up on an existing project.

…/docs/deployments/deployments/runners.md …nts/concepts/customer-managed-runners.mdcontent/docs/deployments/deployments/runners.md renamed to content/docs/deployments/concepts/customer-managed-runners.md content/docs/deployments/deployments/runners.md renamed to content/docs/deployments/concepts/customer-managed-runners.md

@@ -1,39 +1,24 @@
 ---
-title: Runners
-title_tag: Deployment runners | Pulumi Deployments
-meta_desc: How Pulumi Cloud executes your deployments — Pulumi-hosted and customer-managed workflow runners, their hardware, and the full configuration reference.
+title: Customer-managed runners
+title_tag: Customer-managed runners | Pulumi Deployments
+meta_desc: Self-host Pulumi workflow runners on your own infrastructure — supplying credentials and the full configuration reference for customer-managed runner pools.
 meta_image: /images/docs/meta-images/docs-meta.png
 menu:
   deployments:
-    name: Runners
-    parent: deployments-deployments
-    identifier: deployments-deployments-runners
-    weight: 40
+    name: Customer-managed runners
+    parent: deployments-concepts
+    identifier: deployments-concepts-customer-managed-runners
+    weight: 90
 aliases:
+- /docs/deployments/concepts/runners/
+- /docs/deployments/deployments/runners/
 - /docs/pulumi-cloud/deployments/customer-managed-agents/
 - /docs/deployments/deployments/customer-managed-agents/
 - /docs/deployments/deployments/runs/customer-managed-agents/
 - /docs/deployments/deployments/runs/
 ---
 
-Every Pulumi Deployment runs in a container image on a *workflow runner* — the compute that executes your Pulumi program. Two settings control how a run works:
-
-- The [image](/docs/deployments/guides/custom-images/): a Pulumi-managed Linux image by default, or a custom image when your project needs extra tools.
-- The runner: Pulumi-hosted by default, or [customer-managed](#customer-managed-workflow-runners) when you need to run on your own infrastructure.
-
-## Hardware and operating system
-
-When a deployment runs on a Pulumi-hosted workflow runner, it executes inside a Linux container with the following resources:
-
-| Resource | Allocation |
-|---|---|
-| vCPU | 2 |
-| Memory | 8 GB |
-| Disk | A 32 GB volume, with roughly half available for your program's working files after the executor image and dependency caches |
-
-With the default executor image, the container's operating system is Debian, regardless of the operating system of the host it runs on. If you supply a [custom executor image](/docs/deployments/guides/custom-images/), the operating system is whatever that image is built on. If a deployment depends on a specific OS, package manager, or system library, match it to the image you use.
-
-These specifications apply to Pulumi-hosted workflow runners. Customer-managed workflow runners run on infrastructure you provision, so their hardware and operating system are whatever you configure.
+By default, deployments run on [Pulumi-managed runners](/docs/deployments/concepts/pulumi-managed-runners/). Customer-managed workflow runners let you self-host that compute on your own infrastructure instead — for example, to run within a private network — while supporting the same deployment triggers and workflow types.
 
 ## Customer-managed workflow runners
 
@@ -47,7 +32,7 @@ Customer-Managed Workflow Runners allow you to self-host workflow runners, bring
 
 <sup>1</sup> *Currently Linux and macOS are supported*
 
-Customer-Managed Workflow Runners support all the [deployment triggers](/docs/deployments/deployments/#deployment-triggers) currently offered by Pulumi Deployments such as click to deploy, the Pulumi Deployments REST API, git push to deploy, Review Stacks, and remote Automation API. They also support running Insights discovery scans and policy evaluations.
+Customer-Managed Workflow Runners support all the [deployment triggers](/docs/deployments/concepts/triggers/) currently offered by Pulumi Deployments such as click to deploy, the Pulumi Deployments REST API, git push to deploy, Review Stacks, and remote Automation API. They also support running Insights discovery scans and policy evaluations.
 
 {{% notes "info" %}}
 Customer-Managed Workflow Runners are available on the Business Critical edition of Pulumi Cloud. [Contact sales](/contact/?form=sales) if you are interested and want to enable Customer-Managed Workflow Runners.