Deployments

Returns the current execution status of a Pulumi Deployments run. This endpoint is used by self-hosted deployment agents running in agent pools to check whether a deployment is still active. Authenticated using an agent pool secret rather than a user access token.

Request Parameters

• deploymentId string path required
  The deployment identifier

Responses

Streams the Linux/AMD64 Pulumi Deployments executor binary to the requester. The executor is the component that runs inside a deployment container and executes the actual Pulumi operations. The binary is retrieved from the Docker image/filesystem and proxied through the service to control access. This API is for internal use by workflow runners and requires valid credentials.

Responses

Polls the Pulumi Deployments queue for available work to execute. This endpoint is used by self-hosted deployment agents running in agent pools to pick up queued deployment jobs. Returns 200 with the next available deployment’s workflow definition if work is available, or 204 No Content if the queue is empty. Agents should poll this endpoint repeatedly. Authenticated using an agent pool secret rather than a user access token.

Responses

Returns a paginated list of all Pulumi Deployments executions across an organization, filtered to only include deployments for stacks the requesting user has access to. The response includes each deployment’s ID, status, version, creation time, the requesting user, project and stack names, Pulumi operation type, job details, and associated update results. Use ‘page’ (minimum 1, default 1) and ‘pageSize’ (1-100, default 10) for pagination, ‘sort’ to specify the sort field, and ‘asc’ to control sort direction (default descending). The response also includes the total count of matching deployments.

Request Parameters

• orgName string path required
  The organization name
• asc boolean query optional
  Sort in ascending order when true (default false)
• page integer query optional
  Page number (min 1, default 1)
• pageSize integer query optional
  Results per page (1-100, default 10)
• sort string query optional
  Field to sort results by

Responses

Returns metadata about the organization’s Pulumi Deployments state. The response includes the overall pause status, a list of individually paused stacks (as stack references like project/stack), the configured concurrency limit (maximum number of concurrent deployments), and deployment counts broken down by status (notStarted, accepted, running, failed, succeeded, skipped, and total). This endpoint is useful for monitoring deployment health and capacity across an organization.

Request Parameters

• orgName string path required
  The organization name

Responses

Pauses all future Pulumi Deployments executions across an entire organization. While paused, new deployments can still be queued and currently executing deployments will continue to run to completion. However, queued deployments will not be picked up for execution until deployments are resumed. This provides a safety mechanism to temporarily halt all deployment activity across the organization, for example during maintenance windows or incident response. Requires organization administrator permissions. Use the ResumeOrgDeployments endpoint to resume processing.

Request Parameters

• orgName string path required
  The organization name

Responses

Resumes Pulumi Deployments executions for an organization that was previously paused via PauseOrgDeployments. Any queued deployments that accumulated while the organization was paused will begin processing according to the organization’s concurrency limits. Requires organization administrator permissions.

Request Parameters

• orgName string path required
  The organization name

Responses

Retrieves a summary of Pulumi Deployments compute usage (deployment minutes) for an organization. The response provides aggregated deployment minute consumption over the specified time period. Use the ‘granularity’ parameter to control time bucketing (e.g. ‘daily’ or ‘hourly’), and either ’lookbackDays’ (number of days from the current date) or ’lookbackStart’ (a Unix timestamp) to define the reporting window. Returns 204 No Content if no usage data is available for the specified period.

Request Parameters

• orgName string path required
  The organization name
• granularity string query optional
  Time granularity for the summary (e.g. ‘daily’, ‘hourly’)
• lookbackDays integer query optional
  Number of days to look back from the current date
• lookbackStart integer query optional
  Start of the lookback period (Unix timestamp)

Responses

Retrieves raw deployment usage records for self-hosted Pulumi Cloud customers to self-report deployment consumption. Returns aggregated deployment usage records for the specified organization. The ’lookbackDays’ query parameter controls how far back in time to retrieve records. This endpoint is primarily used by self-hosted customers for usage reporting and billing reconciliation purposes.

Request Parameters

• orgName string path required
  The organization name
• lookbackDays integer query optional
  Number of days to look back

Responses

Returns a paginated list of Pulumi Deployments executions for a specific stack. The response includes each deployment’s ID, status, version, creation and modification timestamps, the requesting user, Pulumi operation type, job details with step-level progress, and associated stack update results. Use ‘page’ (minimum 1, default 1) and ‘pageSize’ (1-100, default 10) for pagination, ‘sort’ to specify the sort field, and ‘asc’ to control sort direction (default descending). The response also includes the total count of deployments for the stack.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• stackName string path required
  The stack name
• asc boolean query optional
  Sort in ascending order when true (default false)
• page integer query optional
  Page number (min 1, default 1)
• pageSize integer query optional
  Results per page (1-100, default 10)
• sort string query optional
  Field to sort results by

Responses

Initiates a new Pulumi Deployments execution for a stack. Pulumi Deployments is a managed service that executes Pulumi operations (update, preview, refresh, or destroy) in a secure, hosted environment.

Important: The stack must already exist before a deployment can be created for it.

The operation field is required and accepts: update, preview, refresh, or destroy. Three usage modes are supported:

1. Stack settings only: Send {"operation": "update"} to use the stack’s saved deployment settings.
2. Merged settings: Include partial settings in the request body alongside operation. When inheritSettings is true (the default), request settings are merged with saved stack settings, with request values taking precedence.
3. Request settings only: Set inheritSettings to false and provide all settings in the request body.

Settings include source context (git repo, branch, directory), operation context (environment variables, pre-run commands, OIDC configuration), executor context, GitHub integration settings, and cache options.

This is v2 with breaking changes from CreateAPIDeploymentHandler: inheritSettings defaults to true, and operation is a required top-level field and no longer valid as part of operationContext.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• stackName string path required
  The stack name

Request Body

• operation enum optional
  The Pulumi operation to perform.
  Values: update, preview, destroy, refresh, detect-drift, remediate-drift
• tag string optional
  A tag to identify the deployment settings configuration.
• executorContext ExecutorSettingsRequest optional
  The executor context defining the execution environment.
• ↳ executorImage DockerImageRequest optional
  The Docker image to use for the execution environment.
• ↳ executorRootPath string optional
  The root path for the executor binary and working directory.
• inheritSettings boolean optional
  Whether this deployment should inherit the stack’s deployment settings. Defaults to true.
• sourceContext SourceContextRequest optional
  The source context defining where the source code is located.
• ↳ git SourceContextGitRequest optional
  Git-based source context configuration.
• ↳ hg SourceContextHgRequest optional
  Mercurial-based source context configuration.
• ↳ template SourceContextTemplateRequest optional
  Template-based source context configuration.
• gitHub DeploymentSettingsGitHubRequest optional
  GitHub-specific deployment settings
• ↳ repository string optional
  The GitHub repository in the format owner/repo.
• ↳ deployCommits boolean optional
  Whether to automatically deploy commits pushed to the target branch.
• ↳ previewPullRequests boolean optional
  Whether to automatically preview pull requests.
• ↳ pullRequestTemplate boolean required
  Whether to use a pull request template for deployment previews.
• ↳ deployPullRequest integer optional
  The pull request number to deploy, if targeting a specific pull request.
• ↳ paths array[string] optional
  The list of file paths to filter deployment triggers.
• ↳ installationId string optional
  The GitHub App installation ID.
• vcs DeploymentSettingsVCS optional
  VCS provider settings
• ↳ repository string optional
  The VCS repository reference (format varies by provider)
• ↳ deployCommits boolean optional
  Whether to deploy all commits to the default branch
• ↳ paths array[string] optional
  Paths within the repository that trigger deployments when changed
• ↳ installationId string optional
  VCS installation/integration ID linking to the VCS provider
• ↳ pullRequestTemplate boolean optional
  Whether to use pull request templates for deployment PRs
• ↳ previewPullRequests boolean optional
  Whether to create preview deployments for pull requests
• ↳ deployPullRequest integer optional
  Specific pull request number to deploy (overrides automatic deployment)
• ↳ provider string required
• operationContext OperationContextRequest optional
  The operation context defining pre-run and post-run commands and environment variables.
• ↳ oidc OperationContextOIDCConfigurationRequest optional
  The OIDC configuration for the operation.
• ↳ preRunCommands array[string] optional
  Optional list of commands to run before Pulumi is invoked.
• ↳ operation enum optional
  The Pulumi operation to perform (e.g. update, preview, destroy).
  Values: update, preview, destroy, refresh, detect-drift, remediate-drift
• ↳ environmentVariables map[string]SecretValue optional
  Environment variables to apply during execution.
• ↳ options OperationContextOptionsRequest optional
  Options to specify or override default behavior.
• ↳ role DeploymentRoleRequest optional
  The deployment role to assume for the operation.
• agentPoolID string optional
  The identifier of the agent pool to use for deployments.
• cacheOptions CacheOptionsRequest optional
  Cache options for the deployment.
• ↳ enable boolean optional
  Whether build caching should be enabled for deployments on this stack.

Responses

Retrieves detailed information about a specific Pulumi Deployments execution by its deployment ID. The response includes the deployment’s current status, creation and modification timestamps, version number, the user who requested the deployment, the Pulumi operation type (update, preview, refresh, or destroy), and detailed job information. Each job contains an array of steps with their individual statuses (not-started, running, succeeded, or failed), start times, and last update timestamps. The response also includes any associated stack update results with update IDs, versions, start/end times, and result status.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• stackName string path required
  The stack name
• deploymentId string path required
  The deployment identifier

Responses

Terminates an in-progress Pulumi Deployments execution for a specific stack. If the deployment is currently running, it is stopped immediately. If the deployment is queued but has not yet started, it is removed from the queue.

Warning: Canceling a deployment is a dangerous action and may leave the stack in an inconsistent state if the deployment is canceled during the execution of a Pulumi operation.

Note that this serves two endpoints:

• /{orgName}/{projectName}/{stackName}/deployments/{deploymentId}/cancel
• /admin/deployments/{deploymentId}/cancel

The former requires that the requesting user has stack deployment create permissions. The latter requires that the requesting user is a site administrator.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• stackName string path required
  The stack name
• deploymentId string path required
  The deployment identifier

Responses

Retrieves execution logs for a Pulumi Deployments run. Supports two retrieval modes: streaming mode and step mode. In streaming mode, omit job/step parameters and use the continuationToken to incrementally fetch logs from the beginning through completion. Each response includes a nextToken field; continue requesting with this token until nextToken is absent, indicating all logs have been retrieved. In step mode, specify job and step indices to retrieve logs for a specific step within a specific job, with offset and count parameters for pagination within that step’s logs. In step mode, count must be between 1 and 499 (default 100), and the response includes a nextOffset field for fetching subsequent pages. Log lines include timestamps and the log line content.

Note that this serves two endpoints:

• /{orgName}/{projectName}/{stackName}/deployments/{deploymentId}/logs
• /admin/deployments/{deploymentId}/logs

The former requires stack deployment read permissions. The latter requires site administrator privileges.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• stackName string path required
  The stack name
• deploymentId string path required
  The deployment identifier
• continuationToken string query optional
  Continuation token for streaming logs; use nextToken from the previous response to fetch subsequent log entries
• count integer query optional
  Number of log lines to return (1-499, default 100)
• job integer query optional
  Zero-based job index to retrieve logs for
• offset integer query optional
  Zero-based line offset within the step logs
• step integer query optional
  Zero-based step index within the specified job

Responses

Retrieves all stack updates (program updates) associated with a specific Pulumi Deployments execution. A single deployment may produce one or more stack updates depending on the operation performed. Each update in the response includes details such as the update ID, version, start and end times, result status, and resource changes. This is useful for correlating deployment executions with their resulting infrastructure changes.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• stackName string path required
  The stack name
• deploymentId string path required
  The deployment identifier

Responses

Clears all cached dependency and build artifacts associated with the project for Pulumi Deployments. The deployment cache stores dependencies and other artifacts between deployment runs to speed up execution. Use this endpoint to force a clean build on the next deployment, for example when cached dependencies become stale or corrupted.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• stackName string path required
  The stack name

Responses

Returns a presigned URL for saving or restoring the Pulumi Deployments dependency cache. The cache stores build artifacts and dependencies between deployment runs to speed up execution. The request body must specify a method (PUT to upload a cache archive, or GET to download one) and a non-empty cache key identifying the cached content. The returned presigned URL can be used directly for the corresponding HTTP operation against the object store without additional authentication.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• stackName string path required
  The stack name

Request Body

• method string required
  S3 method of the presigned URL
• key string required
  The key

Responses

Returns metadata about the Pulumi Deployments state for a specific stack. The response distinguishes the source of any pause:

• paused: overall pause status (true if either stack or org is paused)
• stackPaused: whether the stack itself is paused
• organizationPaused: whether the containing organization is paused

This is useful for determining whether new deployments will be processed or held in the queue.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• stackName string path required
  The stack name

Responses

Pauses all future Pulumi Deployments executions for a specific stack. While paused, new deployments can still be queued and currently executing deployments will continue to run to completion. However, queued deployments will not be picked up for execution until deployments are resumed. The stack must have deployment settings configured before it can be paused. Requires stack deployment create permissions. Use the ResumeStackDeployments endpoint to resume processing.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• stackName string path required
  The stack name

Responses

Resumes Pulumi Deployments executions for a stack that was previously paused via PauseStackDeployments. Any queued deployments that accumulated while the stack was paused will begin processing. The stack must have deployment settings configured. Requires stack deployment create permissions.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• stackName string path required
  The stack name

Responses

Retrieves the Pulumi Deployments configuration for a specified stack. The response includes all saved deployment settings: source context (git repository URL, branch, and directory), operation context (environment variables, pre-run commands, OIDC provider configuration), executor context (deployment executor configuration), GitHub integration settings (repository, paths, deployment triggers), and cache options for dependency caching between runs. These settings serve as the baseline configuration for deployments when inheritSettings is true on a deployment request. Returns 404 if the stack has no deployment settings configured.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• stackName string path required
  The stack name

Responses

Creates or updates Pulumi Deployments settings for a stack using a merge operation. If no settings exist, they are created. If settings already exist, the request body is merged with the current settings using the following logic: for each property, start with the current value, remove it if the patch specifies null, or merge the new non-null value with the existing one. Non-object properties (strings, numbers, booleans) are replaced entirely. Settings include source context (git repository URL, branch, directory), operation context (environment variables, pre-run commands, OIDC configuration), executor context, GitHub integration settings, and cache options. Requires a Team Growth or higher subscription. Cannot be used to configure Pulumi Deployments for Terraform stacks.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• stackName string path required
  The stack name

Request Body

• tag string optional
  A tag to identify the deployment settings configuration.
• executorContext ExecutorSettingsRequest optional
  The executor context defining the execution environment.
• ↳ executorImage DockerImageRequest optional
  The Docker image to use for the execution environment.
• ↳ executorRootPath string optional
  The root path for the executor binary and working directory.
• sourceContext SourceContextRequest optional
  The source context defining where the source code is located.
• ↳ git SourceContextGitRequest optional
  Git-based source context configuration.
• ↳ hg SourceContextHgRequest optional
  Mercurial-based source context configuration.
• ↳ template SourceContextTemplateRequest optional
  Template-based source context configuration.
• gitHub DeploymentSettingsGitHubRequest optional
  GitHub-specific deployment settings
• ↳ repository string optional
  The GitHub repository in the format owner/repo.
• ↳ deployCommits boolean optional
  Whether to automatically deploy commits pushed to the target branch.
• ↳ previewPullRequests boolean optional
  Whether to automatically preview pull requests.
• ↳ pullRequestTemplate boolean required
  Whether to use a pull request template for deployment previews.
• ↳ deployPullRequest integer optional
  The pull request number to deploy, if targeting a specific pull request.
• ↳ paths array[string] optional
  The list of file paths to filter deployment triggers.
• ↳ installationId string optional
  The GitHub App installation ID.
• vcs DeploymentSettingsVCS optional
  VCS provider settings
• ↳ repository string optional
  The VCS repository reference (format varies by provider)
• ↳ deployCommits boolean optional
  Whether to deploy all commits to the default branch
• ↳ paths array[string] optional
  Paths within the repository that trigger deployments when changed
• ↳ installationId string optional
  VCS installation/integration ID linking to the VCS provider
• ↳ pullRequestTemplate boolean optional
  Whether to use pull request templates for deployment PRs
• ↳ previewPullRequests boolean optional
  Whether to create preview deployments for pull requests
• ↳ deployPullRequest integer optional
  Specific pull request number to deploy (overrides automatic deployment)
• ↳ provider string required
• operationContext OperationContextRequest optional
  The operation context defining pre-run and post-run commands and environment variables.
• ↳ oidc OperationContextOIDCConfigurationRequest optional
  The OIDC configuration for the operation.
• ↳ preRunCommands array[string] optional
  Optional list of commands to run before Pulumi is invoked.
• ↳ operation enum optional
  The Pulumi operation to perform (e.g. update, preview, destroy).
  Values: update, preview, destroy, refresh, detect-drift, remediate-drift
• ↳ environmentVariables map[string]SecretValue optional
  Environment variables to apply during execution.
• ↳ options OperationContextOptionsRequest optional
  Options to specify or override default behavior.
• ↳ role DeploymentRoleRequest optional
  The deployment role to assume for the operation.
• agentPoolID string optional
  The identifier of the agent pool to use for deployments.
• cacheOptions CacheOptionsRequest optional
  Cache options for the deployment.
• ↳ enable boolean optional
  Whether build caching should be enabled for deployments on this stack.

Responses

Fully replaces the Pulumi Deployments settings for a stack. Unlike the PATCH endpoint (PatchDeploymentSettings) which merges changes, this endpoint replaces all settings with the provided values. Any previously configured settings not included in the request body will be removed. Settings include source context (git repository URL, branch, directory), operation context (environment variables, pre-run commands, OIDC configuration), executor context, GitHub integration settings, and cache options. Requires a Team Growth or higher subscription. Cannot be used to configure Pulumi Deployments for Terraform stacks.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• stackName string path required
  The stack name

Request Body

• tag string optional
  A tag to identify the deployment settings configuration.
• executorContext ExecutorSettingsRequest optional
  The executor context defining the execution environment.
• ↳ executorImage DockerImageRequest optional
  The Docker image to use for the execution environment.
• ↳ executorRootPath string optional
  The root path for the executor binary and working directory.
• sourceContext SourceContextRequest optional
  The source context defining where the source code is located.
• ↳ git SourceContextGitRequest optional
  Git-based source context configuration.
• ↳ hg SourceContextHgRequest optional
  Mercurial-based source context configuration.
• ↳ template SourceContextTemplateRequest optional
  Template-based source context configuration.
• gitHub DeploymentSettingsGitHubRequest optional
  GitHub-specific deployment settings
• ↳ repository string optional
  The GitHub repository in the format owner/repo.
• ↳ deployCommits boolean optional
  Whether to automatically deploy commits pushed to the target branch.
• ↳ previewPullRequests boolean optional
  Whether to automatically preview pull requests.
• ↳ pullRequestTemplate boolean required
  Whether to use a pull request template for deployment previews.
• ↳ deployPullRequest integer optional
  The pull request number to deploy, if targeting a specific pull request.
• ↳ paths array[string] optional
  The list of file paths to filter deployment triggers.
• ↳ installationId string optional
  The GitHub App installation ID.
• vcs DeploymentSettingsVCS optional
  VCS provider settings
• ↳ repository string optional
  The VCS repository reference (format varies by provider)
• ↳ deployCommits boolean optional
  Whether to deploy all commits to the default branch
• ↳ paths array[string] optional
  Paths within the repository that trigger deployments when changed
• ↳ installationId string optional
  VCS installation/integration ID linking to the VCS provider
• ↳ pullRequestTemplate boolean optional
  Whether to use pull request templates for deployment PRs
• ↳ previewPullRequests boolean optional
  Whether to create preview deployments for pull requests
• ↳ deployPullRequest integer optional
  Specific pull request number to deploy (overrides automatic deployment)
• ↳ provider string required
• operationContext OperationContextRequest optional
  The operation context defining pre-run and post-run commands and environment variables.
• ↳ oidc OperationContextOIDCConfigurationRequest optional
  The OIDC configuration for the operation.
• ↳ preRunCommands array[string] optional
  Optional list of commands to run before Pulumi is invoked.
• ↳ operation enum optional
  The Pulumi operation to perform (e.g. update, preview, destroy).
  Values: update, preview, destroy, refresh, detect-drift, remediate-drift
• ↳ environmentVariables map[string]SecretValue optional
  Environment variables to apply during execution.
• ↳ options OperationContextOptionsRequest optional
  Options to specify or override default behavior.
• ↳ role DeploymentRoleRequest optional
  The deployment role to assume for the operation.
• agentPoolID string optional
  The identifier of the agent pool to use for deployments.
• cacheOptions CacheOptionsRequest optional
  Cache options for the deployment.
• ↳ enable boolean optional
  Whether build caching should be enabled for deployments on this stack.

Responses

Removes all Pulumi Deployments settings for a stack, including source context, operation context, executor context, GitHub integration settings, and cache options. After deletion, the stack can no longer run deployments until new settings are configured. Any active schedules (drift detection, TTL, or custom) associated with the stack may also be affected.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• stackName string path required
  The stack name

Responses

Encrypts a plaintext secret value for secure storage in Pulumi Deployments settings. Use this endpoint to encrypt sensitive values such as cloud provider credentials, API keys, or other secrets before including them in deployment settings (e.g. as environment variables in operationContext). The encrypted value can then be safely stored in the deployment settings and will be decrypted at deployment execution time. The request body must contain a non-empty plaintext value to encrypt.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• stackName string path required
  The stack name

Request Body

• secret string required
  The secret value in plaintext.
• ciphertext array[string] optional
  The encrypted representation of the secret value.

Responses

Retrieves detailed information about a specific Pulumi Deployments execution by its version number within the stack. This is an alternative to fetching by deployment ID and returns the same response structure: deployment status, creation and modification timestamps, the user who requested the deployment, the Pulumi operation type, job details with step-level progress, and any associated stack update results.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• stackName string path required
  The stack name
• version string path required
  The deployment version number

Responses

Returns a paginated list of all drift detection runs for a stack. Each drift run represents a scheduled or manually triggered drift detection execution and includes details about whether drift was detected and any remediation actions taken. Use the ‘page’ (minimum 1, default 1) and ‘pageSize’ (1-100, default 10) query parameters for pagination.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• stackName string path required
  The stack name
• page integer query optional
  Page number (min 1, default 1)
• pageSize integer query optional
  Results per page (1-100, default 10)

Responses

Retrieves the current drift detection status and associated metadata for a stack. Drift occurs when the actual state of cloud resources diverges from the state declared in the Pulumi program. The response indicates whether drift has been detected, when the last drift check was performed, and details about any detected differences. This is used in conjunction with drift detection schedules to monitor infrastructure compliance.

Request Parameters

• orgName string path required
  The organization name
• projectName string path required
  The project name
• stackName string path required
  The stack name

Responses