Skip to main content
Pulumi logo Pulumi logo
  1. Docs
  2. Reference
  3. REST API Docs
  4. Delivery

Delivery

    List Delivery Approvals

    ▼
    Preview. This endpoint is in preview and may change without notice.
    GET /api/preview/delivery/{orgName}/approvals

    Lists the approvals of Delivery gates in the organization for the pipelines that the caller can read, newest request first, then by condition ID. The status filter keeps the pending approvals, the closed ones or all of them. An approval is pending when its gate is open and it has no change request yet or its change request is in draft, pending or ready status. Every other approval is closed, including approvals of gates that have ended. Results are paginated with continuationToken and maxResults; the response carries a continuationToken when more results follow. maxResults defaults to 50, and a value below 1 or above 100 returns a 400 error. An invalid continuation token returns a 400 error.

    Request Parameters

    • orgName string path required
      The organization name
    • continuationToken string query optional
      Continuation token from a previous page
    • maxResults integer query optional
      The number of results per page. The default is 50. A value below 1 or above 100 returns a 400 error.
    • project string query optional
      Only approvals of the pipeline with this project name. Use it with stack.
    • stack string query optional
      Only approvals of the pipeline with this stack name. Use it with project.
    • status string query optional
      pending, closed or all. The default is pending. Any other value that is not empty returns a 400 error.

    Responses

    200 OK
    • approvals array[DeliveryApproval] optional
      The approvals of the page, newest first.
    • ↳ project string required
      The project name of the pipeline stack.
    • ↳ stack string required
      The stack name of the pipeline stack.
    • ↳ runNumber integer required
      The number of the run.
    • ↳ gateId string required
      The ID of the gate.
    • ↳ conditionId string required
      The ID of the condition.
    • ↳ conditionName string required
      The name of the condition.
    • ↳ stageName string optional
      The name of the stage.
    • ↳ releaseNumber integer optional
      The number of the release.
    • ↳ requestedAt string required
      When the approval was requested.
    • ↳ actor string optional
      The login of the user who started the run.
    • ↳ changeRequestStatus string optional
      The status of the change request of the approval.
    • ↳ conditionState enum optional
      The state of the condition: pending, satisfied or rejected.
      Values: pending, satisfied, rejected
    • ↳ requiredApprovals integer optional
      The number of approvals that are needed.
    • ↳ approvals integer optional
      The number of approvals that count now.
    • continuationToken string optional
      The token of the next page. Not set on the last page.
    Errors: 400 A parameter is not valid

    List Delivery Programs

    ▼
    Preview. This endpoint is in preview and may change without notice.
    GET /api/preview/delivery/{orgName}/programs

    Lists the Delivery programs of the organization that the caller can read, in the order of the accessible stacks. Results are paginated with continuationToken and maxResults; the response carries a continuationToken when more results follow. maxResults defaults to 50, and a value below 1 or above 100 returns a 400 error. An invalid continuation token returns a 400 error.

    Request Parameters

    • orgName string path required
      The organization name
    • continuationToken string query optional
      Continuation token from a previous page
    • kind string query optional
      Only programs of this kind. The only kind is pipeline. Any other value that is not empty returns a 400 error.
    • maxResults integer query optional
      The number of results per page. The default is 50. A value below 1 or above 100 returns a 400 error.
    • query string query optional
      Only programs whose project or stack name contains this text
    • status string query optional
      Only programs whose latest run has this status: in_progress, succeeded, failed, canceled or superseded. Any other value that is not empty returns a 400 error.
    • waitKind string query optional
      Only programs that have a run in progress that waits for this kind of condition. The only kind is approval. Any other value that is not empty returns a 400 error.

    Responses

    200 OK
    • programs array[DeliveryProgramRow] optional
      The programs of the page, in stack order.
    • ↳ project string required
      The project name.
    • ↳ stack string required
      The stack name.
    • ↳ registered boolean required
      Whether the program has an active registration. A stack with local runs only has none.
    • ↳ lastRun DeliveryRunSummary optional
      The latest run, without its stage entries.
    • ↳ stages array[DeliveryProgramRowStage] optional
      The stages in order.
    • ↳ pendingApprovals integer required
      The number of approvals that wait now.
    • continuationToken string optional
      The token of the next page. Not set on the last page.
    Errors: 400 A parameter is not valid

    Dispatch Delivery Run

    ▼
    Preview. This endpoint is in preview and may change without notice.
    POST /api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/dispatch

    Starts a Delivery run of the pipeline on the stack at the head of the program branch, or at the ref of the request. Sources that the request does not pin get their latest value. An optional key prevents duplicate dispatches. A credential needs the pipeline:dispatch permission on the pipeline stack. A request that sets a ref or sources also needs the stack:write permission on that stack. Returns a 400 error if the key, the ref or a source is not valid, or if a pinned source is not a GitHub, GitLab, Bitbucket or Azure DevOps source of the pipeline, a 403 error if the organization cannot use Delivery, a 404 error if the stack is not a pipeline, and a 409 error if the pipeline has no active registration, cannot run, or changed while the run started.

    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

    • key string optional
      A key that prevents duplicate dispatches. A second dispatch with the same key, the same ref and the same sources returns the run of the first. A dispatch with a different ref or different sources is a new dispatch. The key has at most 128 printable ASCII characters.
    • ref string optional
      A branch name, a tag name or a full commit SHA of the program repository. The run uses the program code at that commit and the active definition of the pipeline. Empty means the head of the program branch.
    • sources array[DeliveryDispatchSource] optional
      Release sources to pin. A source that is not pinned gets its latest value.

    Responses

    200 OK
    • runNumber integer required
      The number of the run.
    Errors: 400 The key, the ref or a source is not valid, or a pinned source is not a GitHub, GitLab, Bitbucket or Azure DevOps source of the pipeline, is pinned twice or has an empty value 403 Delivery is not enabled, or the credential has no pipeline:dispatch permission on the stack, or has no stack:write permission on it for a request that sets a ref or sources 404 The stack is not a Delivery pipeline 409 The pipeline has no active registration, cannot run, or changed while the run started 503 The forge could not be read

    Get Delivery Program

    ▼
    Preview. This endpoint is in preview and may change without notice.
    GET /api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/program

    Returns the shell of a Delivery program: a projection of the active registration with live state. Each stage of the active registration carries the run that deployed its current release (deployed), the run that holds its lock (lockHolder), its newest open gate (openGate), its queue length and its members with their status. Stages and members that are not in the active registration do not appear; their history is in the run routes. The active registration has at most 1000 stages and 1000 members. The response also holds the runs in progress (at most 20, with a count) and a summary of the pipeline. A stack with a failed first registration and no program answers 200 with registered set to false.

    Request Parameters

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

    Responses

    200 OK
    • org string required
      The organization name.
    • project string required
      The project name.
    • stack string required
      The stack name.
    • kind enum required
      The kind of the program: pipeline.
      Values: pipeline
    • registered boolean required
      Whether the program has an active registration. A stack with only a failed registration has none.
    • registering boolean required
      Whether the first registration is still finishing. The program is not registered yet, and registration is the pending registration.
    • registration DeliveryRegistrationInfo required
      The active registration, or the pending one while registering is true.
    • ↳ id string optional
      The ID of the registration. A new active registration has a new ID, so a changed ID means that the pipeline definition can have changed.
    • ↳ registered boolean required
      Whether a registration is active.
    • ↳ status enum optional
      The status of the registration.
      Values: pending, succeeded, failed, local
    • ↳ reason string optional
      Why a registration failed.
    • ↳ programCommit string optional
      The commit of the registered program.
    • ↳ actor string optional
      Who registered the program.
    • ↳ actorKind enum optional
      The kind of the actor.
      Values: user, webhook, system, trigger
    • ↳ createdAt string optional
      When the registration was made.
    • ↳ warnings array[string] optional
      The warnings of the registration.
    • lastFailedRegistration DeliveryRegistrationInfo optional
      The latest failed registration, if it is newer than the active one.
    • ↳ id string optional
      The ID of the registration. A new active registration has a new ID, so a changed ID means that the pipeline definition can have changed.
    • ↳ registered boolean required
      Whether a registration is active.
    • ↳ status enum optional
      The status of the registration.
      Values: pending, succeeded, failed, local
    • ↳ reason string optional
      Why a registration failed.
    • ↳ programCommit string optional
      The commit of the registered program.
    • ↳ actor string optional
      Who registered the program.
    • ↳ actorKind enum optional
      The kind of the actor.
      Values: user, webhook, system, trigger
    • ↳ createdAt string optional
      When the registration was made.
    • ↳ warnings array[string] optional
      The warnings of the registration.
    • latestRegistration DeliveryRegistrationEntry optional
      The newest attempt to register the pipeline, whether it is queued, running, failed or done.
    • ↳ id string required
      The ID of the entry: the ID of the update, or the ID of the queued registration when it has no update.
    • ↳ source enum required
      Who started the attempt.
      Values: user, push
    • ↳ commit string optional
      The commit of the attempt, if known.
    • ↳ dirty boolean optional
      Whether the checkout of a user registration had uncommitted changes, or did not say. Not set for a push or while the update runs.
    • ↳ branch string optional
      The tracked branch, if known. Only a registration that a push queued records it.
    • ↳ programSource DeliverySourceRef optional
      Where the commit of a push lives: the kind and repository of the source that the queued registration recorded, and the branch. Not set for a registration by a person.
    • ↳ state enum required
      The state of the attempt.
      Values: queued, running, succeeded, failed, canceled
    • ↳ message string optional
      Why the attempt failed, if it did.
    • ↳ active boolean required
      Whether this is the active registration of the pipeline.
    • ↳ updateVersion integer optional
      The version of the update of the pipeline stack, if the attempt has an update.
    • ↳ workItemId string optional
      The ID of the registration that the push queued. Set for a push.
    • ↳ requestedBy string optional
      The login of the user who ran the update, for a user registration.
    • ↳ created string required
      When the attempt was created.
    • ↳ finished string optional
      When the attempt finished. Not set while it is in progress.
    • stages array[DeliveryStageSummary] optional
      The stages in the order of the stage graph.
    • ↳ paused boolean required
      Whether the stage is paused.
    • ↳ pausedBy string optional
      Who paused the stage.
    • ↳ pausedAt string optional
      When the stage was paused.
    • ↳ deployedReleaseNumber integer optional
      The release deployed at the stage.
    • ↳ deployedRunNumber integer optional
      The run that deployed it.
    • ↳ lockRunNumber integer optional
      The run that holds the lock of the stage.
    • ↳ queueLength integer required
      The number of runs that wait for the stage. List them with the runs route, its stage filter and queued set to true.
    • ↳ deployed DeliveryStageRun optional
      The run that deployed the current release of the stage.
    • ↳ lastCloudDeployed DeliveryStageRun optional
      The last cloud release that converged the stage. Downstream pipelines read this one. It differs from deployed while a local release is deployed.
    • ↳ lockHolder DeliveryStageRun optional
      The run that holds the lock of the stage, with the status of the stage in it. A normal run and an operator run can hold it.
    • ↳ openGate DeliveryStageGate optional
      The newest open gate of the stage over all runs in progress.
    • ↳ members array[DeliveryStageMember] optional
      The members of the stage in the active registration, at most 1000.
    • ↳ from array[string] optional
      The names of the stages that must converge first.
    • ↳ name string required
      The name of the stage.
    • ↳ when array[string] optional
      The kinds and names of the conditions of the stage.
    • runsInProgress array[DeliveryRunSummary] optional
      The newest runs in progress, at most 20.
    • ↳ number integer required
      The number of the run.
    • ↳ kind enum required
      The kind of the run.
      Values:
      normal — Normal
      A run that a trigger started.
      rollback — Rollback
      A run that an operator started to return a stage to an earlier release.
      redeploy — Redeploy
      A run that an operator started to deploy a stage again.
      force_promote — ForcePromote
      A run that an operator started to promote a release past its gates.
    • ↳ status DeliveryStatus required
      The structured status of the run.
    • ↳ triggerKind enum required
      What started the run.
      Values:
      registration — Registration
      A registration of the program.
      push — Push
      A push of a source.
      dispatch — Dispatch
      A dispatch by a user.
      operator — Operator
      An operator action on a stage.
      stage_converged — StageConverged
      A stage of another pipeline that converged.
      local — Local
      A local pulumi up of the pipeline stack.
    • ↳ actorKind enum required
      Who started the run: user, webhook, trigger or system.
      Values: user, webhook, system, trigger
    • ↳ actor string optional
      The login of the user who started the run, if a user did.
    • ↳ targetStage string optional
      The stage that an operator run deploys.
    • ↳ releaseNumber integer optional
      The number of the release of the run.
    • ↳ programCommit DeliveryCommit optional
      The commit of the program that the run executes.
    • ↳ programRef string optional
      The ref (branch, tag or commit SHA) that a person started the run at. Absent for a run at the head of the program branch.
    • ↳ originRunNumber integer optional
      The number of the run that an operator run repeats.
    • ↳ stages array[DeliveryRunStageSummary] optional
      One entry for each stage of the run, in the order of the stages.
    • ↳ createdAt string required
      When the run was created.
    • ↳ finishedAt string optional
      When the run ended.
    • ↳ local boolean optional
      Whether the run is a local run, started with pulumi up. Set only when it is.
    • runsInProgressCount integer required
      The number of runs in progress.
    • summary DeliverySummary required
      Summary facts about the pipeline.
    • ↳ lastFinishedRun DeliveryRunSummary optional
      The latest run that ended.
    • ↳ newestRelease DeliveryRelease optional
      The newest release.
    • ↳ approvalCount integer required
      The number of approvals that wait now.
    • ↳ newestApprovalRunNumber integer optional
      The run of the newest waiting approval.
    • ↳ newestApprovalGateId string optional
      The gate of the newest waiting approval.
    • ↳ newestApprovalConditionId string optional
      The condition of the newest waiting approval.
    • dispatch DeliveryAction required
      Whether the caller can dispatch a run.
    • ↳ allowed boolean required
      Whether the caller can do the action now.
    • ↳ reason string optional
      Why the caller cannot do the action. Not set when it is allowed.
    Errors: 404 The stack is not a Delivery program, or has no such item

    List Delivery Releases

    ▼
    Preview. This endpoint is in preview and may change without notice.
    GET /api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/releases

    Lists the releases of a Delivery program, ordered by release number, newest first. With ready set to true, only ready releases are listed. With rollbackStage set to the name of a stage, only the releases that the rollback of that stage accepts are listed: releases that converged the stage and are older than the release deployed at it; they are all ready, so rollbackStage cannot combine with ready. Results are paginated with continuationToken and maxResults; the response carries a continuationToken when more results follow. maxResults defaults to 50, and a value below 1 or above 100 returns a 400 error. An invalid continuation token returns a 400 error.

    Request Parameters

    • orgName string path required
      The organization name
    • projectName string path required
      The project name
    • stackName string path required
      The stack name
    • continuationToken string query optional
      Continuation token from a previous page
    • maxResults integer query optional
      The number of results per page. The default is 50. A value below 1 or above 100 returns a 400 error.
    • ready boolean query optional
      When true, only ready releases
    • rollbackStage string query optional
      Only the releases that the rollback of this stage accepts

    Responses

    200 OK
    • releases array[DeliveryRelease] optional
      The releases of the page, newest first.
    • ↳ number integer required
      The number of the release.
    • ↳ status DeliveryStatus required
      The structured status of the originating run of the release.
    • ↳ ready boolean required
      Whether the release is ready. A release is ready when its first pass has finished.
    • ↳ originRunNumber integer required
      The number of the run that created the release.
    • ↳ programCommit DeliveryCommit optional
      The commit of the program of the release.
    • ↳ createdAt string required
      When the release was created.
    • ↳ deployments array[DeliveryDeployment] optional
      The stages where the release is deployed.
    • ↳ local boolean optional
      Whether the release is a local release, started with pulumi up. Set only when it is.
    • continuationToken string optional
      The token of the next page. Not set on the last page.
    Errors: 400 A parameter is not valid 404 The stack is not a Delivery program, or has no such item

    Get Delivery Release

    ▼
    Preview. This endpoint is in preview and may change without notice.
    GET /api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/releases/{releaseNumber}

    Returns a release: its sources, the previous release, its artifacts grouped by run and its rollout by stage. The rollout lists at most 50 runs. List the runs of a release with the release filter of the runs route.

    Request Parameters

    • orgName string path required
      The organization name
    • projectName string path required
      The project name
    • stackName string path required
      The stack name
    • releaseNumber integer path required
      The number of the release

    Responses

    200 OK
    • release DeliveryRelease required
      The facts of the release.
    • ↳ number integer required
      The number of the release.
    • ↳ status DeliveryStatus required
      The structured status of the originating run of the release.
    • ↳ ready boolean required
      Whether the release is ready. A release is ready when its first pass has finished.
    • ↳ originRunNumber integer required
      The number of the run that created the release.
    • ↳ programCommit DeliveryCommit optional
      The commit of the program of the release.
    • ↳ createdAt string required
      When the release was created.
    • ↳ deployments array[DeliveryDeployment] optional
      The stages where the release is deployed.
    • ↳ local boolean optional
      Whether the release is a local release, started with pulumi up. Set only when it is.
    • previousReleaseNumber integer optional
      The number of the previous release.
    • sources array[DeliveryReleaseSource] optional
      The recorded sources of the release.
    • ↳ commit DeliveryCommit optional
      The recorded commit of a version control source.
    • ↳ changed boolean required
      Whether the value changed since the previous release.
    • ↳ upstreamRelease integer optional
      The release of the upstream pipeline.
    • ↳ branch string optional
      The branch.
    • ↳ kind enum required
      The kind of the source: a repository kind, or pipeline for an upstream pipeline. More kinds can be added.
      Values:
      github — GitHub
      A GitHub repository.
      gitlab — GitLab
      A GitLab repository.
      bitbucket — Bitbucket
      A Bitbucket repository.
      azure_devops — AzureDevOps
      An Azure DevOps repository.
      entire — Entire
      An Entire repository.
      custom — Custom
      A custom source.
      pipeline — Pipeline
      An upstream pipeline.
    • ↳ name string optional
      The name of the source in the pipeline program, which a run pins it by.
    • ↳ repository string optional
      The repository.
    • ↳ upstreamProgram string optional
      The upstream program of a pipeline source, as organization/project/stack. The upstream pipeline is always in the organization of the program.
    • ↳ upstreamStage string optional
      The upstream stage.
    • artifacts array[DeliveryRunArtifacts] optional
      The artifacts of the release, grouped by run.
    • ↳ runNumber integer required
      The number of the run.
    • ↳ artifacts map[string]DeliveryValue optional
      The artifacts by name.
    • rollout array[DeliveryRollout] optional
      The rollout by stage and run.
    • ↳ stageName string required
      The name of the stage.
    • ↳ runNumber integer required
      The number of the run.
    • ↳ status DeliveryStatus required
      The structured status of the stage in the run.
    • ↳ convergedAt string optional
      When the stage converged.
    • runsTruncated boolean required
      Whether the release has more runs than the artifacts and the rollout cover. The runs route lists them all.
    Errors: 404 The stack is not a Delivery program, or has no such item

    List Delivery Runs

    ▼
    Preview. This endpoint is in preview and may change without notice.
    GET /api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/runs

    Lists the runs of a Delivery program, ordered by run number, newest first. The filters stage, status and release combine. With queued set to true, the route lists instead the runs that wait for admission to the stage in stage, in the order the service admits them: operator runs by queue time, then run number, ascending; then normal runs by release number, then run number, descending. queued requires stage and returns a 400 error without it, and it cannot combine with release or status. The queue is a live view: an admission removes the first run and the others move up, so read it again from the first page after a change. Results are paginated with continuationToken and maxResults; the response carries a continuationToken when more results follow. maxResults defaults to 50, and a value below 1 or above 100 returns a 400 error. An invalid continuation token returns a 400 error.

    Request Parameters

    • orgName string path required
      The organization name
    • projectName string path required
      The project name
    • stackName string path required
      The stack name
    • continuationToken string query optional
      Continuation token from a previous page
    • maxResults integer query optional
      The number of results per page. The default is 50. A value below 1 or above 100 returns a 400 error.
    • queued boolean query optional
      When true, list the runs that wait for admission to the stage in stage, in admission order. It requires stage.
    • release integer query optional
      Only runs of the release with this number
    • stage string query optional
      Only runs that reached this stage: they wait at it, hold its lock or converged it
    • status string query optional
      Only runs with this status: in_progress, succeeded, failed, canceled or superseded. Any other value that is not empty returns a 400 error.

    Responses

    200 OK
    • runs array[DeliveryRunSummary] optional
      The runs of the page, newest first.
    • ↳ number integer required
      The number of the run.
    • ↳ kind enum required
      The kind of the run.
      Values:
      normal — Normal
      A run that a trigger started.
      rollback — Rollback
      A run that an operator started to return a stage to an earlier release.
      redeploy — Redeploy
      A run that an operator started to deploy a stage again.
      force_promote — ForcePromote
      A run that an operator started to promote a release past its gates.
    • ↳ status DeliveryStatus required
      The structured status of the run.
    • ↳ triggerKind enum required
      What started the run.
      Values:
      registration — Registration
      A registration of the program.
      push — Push
      A push of a source.
      dispatch — Dispatch
      A dispatch by a user.
      operator — Operator
      An operator action on a stage.
      stage_converged — StageConverged
      A stage of another pipeline that converged.
      local — Local
      A local pulumi up of the pipeline stack.
    • ↳ actorKind enum required
      Who started the run: user, webhook, trigger or system.
      Values: user, webhook, system, trigger
    • ↳ actor string optional
      The login of the user who started the run, if a user did.
    • ↳ targetStage string optional
      The stage that an operator run deploys.
    • ↳ releaseNumber integer optional
      The number of the release of the run.
    • ↳ programCommit DeliveryCommit optional
      The commit of the program that the run executes.
    • ↳ programRef string optional
      The ref (branch, tag or commit SHA) that a person started the run at. Absent for a run at the head of the program branch.
    • ↳ originRunNumber integer optional
      The number of the run that an operator run repeats.
    • ↳ stages array[DeliveryRunStageSummary] optional
      One entry for each stage of the run, in the order of the stages.
    • ↳ createdAt string required
      When the run was created.
    • ↳ finishedAt string optional
      When the run ended.
    • ↳ local boolean optional
      Whether the run is a local run, started with pulumi up. Set only when it is.
    • continuationToken string optional
      The token of the next page. Not set on the last page.
    Errors: 400 A parameter is not valid 404 The stack is not a Delivery program, or has no such item

    Get Delivery Run Detail

    ▼
    Preview. This endpoint is in preview and may change without notice.
    GET /api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/runs/{runNumber}

    Returns the page of a run: its facts, stages, members, graph edges and the actions available to the caller. Nested lists are bounded.

    Request Parameters

    • orgName string path required
      The organization name
    • projectName string path required
      The project name
    • stackName string path required
      The stack name
    • runNumber integer path required
      The number of the run

    Responses

    200 OK
    Schema: DeliveryRun
    • summary DeliveryRunSummary required
      The facts of the run.
    • ↳ number integer required
      The number of the run.
    • ↳ kind enum required
      The kind of the run.
      Values:
      normal — Normal
      A run that a trigger started.
      rollback — Rollback
      A run that an operator started to return a stage to an earlier release.
      redeploy — Redeploy
      A run that an operator started to deploy a stage again.
      force_promote — ForcePromote
      A run that an operator started to promote a release past its gates.
    • ↳ status DeliveryStatus required
      The structured status of the run.
    • ↳ triggerKind enum required
      What started the run.
      Values:
      registration — Registration
      A registration of the program.
      push — Push
      A push of a source.
      dispatch — Dispatch
      A dispatch by a user.
      operator — Operator
      An operator action on a stage.
      stage_converged — StageConverged
      A stage of another pipeline that converged.
      local — Local
      A local pulumi up of the pipeline stack.
    • ↳ actorKind enum required
      Who started the run: user, webhook, trigger or system.
      Values: user, webhook, system, trigger
    • ↳ actor string optional
      The login of the user who started the run, if a user did.
    • ↳ targetStage string optional
      The stage that an operator run deploys.
    • ↳ releaseNumber integer optional
      The number of the release of the run.
    • ↳ programCommit DeliveryCommit optional
      The commit of the program that the run executes.
    • ↳ programRef string optional
      The ref (branch, tag or commit SHA) that a person started the run at. Absent for a run at the head of the program branch.
    • ↳ originRunNumber integer optional
      The number of the run that an operator run repeats.
    • ↳ stages array[DeliveryRunStageSummary] optional
      One entry for each stage of the run, in the order of the stages.
    • ↳ createdAt string required
      When the run was created.
    • ↳ finishedAt string optional
      When the run ended.
    • ↳ local boolean optional
      Whether the run is a local run, started with pulumi up. Set only when it is.
    • failureReason string optional
      Why the run failed.
    • canceledBy string optional
      The login of the user who canceled the run.
    • canceledAt string optional
      When the run was canceled.
    • runStack DeliveryStackRef optional
      The stack that the program of the run runs on.
    • ↳ project string required
      The project name of the stack.
    • ↳ stack string required
      The name of the stack.
    • ↳ exists boolean required
      Whether the stack still exists. A run stack is deleted with its pipeline.
    • localUpdate DeliveryLocalUpdate optional
      The update of the pipeline stack that drove the run. Set only for a local run, which has no run stack.
    • ↳ project string required
      The project name of the pipeline stack.
    • ↳ stack string required
      The name of the pipeline stack.
    • ↳ version integer required
      The version of the update on the pipeline stack.
    • passCount integer required
      The number of passes of the run.
    • currentPass DeliveryPass optional
      The latest pass of the run.
    • ↳ number integer required
      The number of the pass in the run.
    • ↳ status enum required
      The status of the pass.
      Values: queued, running, finished
    • ↳ outcome enum optional
      The outcome of a finished pass.
      Values: awaiting, completed, failed, canceled
    • ↳ updateId string optional
      The ID of the update of the run stack that the pass made.
    • ↳ failureReason string optional
      Why the pass failed. Free-form text.
    • ↳ createdAt string required
      When the pass was queued.
    • ↳ startedAt string optional
      When the pass started.
    • ↳ finishedAt string optional
      When the pass ended.
    • stages array[DeliveryRunStage] optional
      The stages of the run.
    • ↳ name string required
      The name of the stage.
    • ↳ status DeliveryStatus required
      The structured status of the stage in the run.
    • ↳ from array[string] optional
      The names of the stages that must converge first.
    • ↳ when array[string] optional
      The kinds and names of the conditions that the run declared for the stage, as kind:name.
    • ↳ admittedAt string optional
      When the stage got its lock.
    • ↳ convergedAt string optional
      When the stage converged.
    • ↳ gate DeliveryGate optional
      The latest gate of the stage.
    • members array[DeliveryMember] optional
      The members of the run.
    • ↳ id string required
      The ID of the member.
    • ↳ name string required
      The name of the member: the component and, for a group of stacks, the entry.
    • ↳ type enum required
      The type of the member.
      Values: job, stacks, artifact, agent
    • ↳ stageName string optional
      The name of the stage of the member.
    • ↳ targetStack DeliveryStackRef optional
      The stack that a member of Stacks updates.
    • ↳ status DeliveryStatus required
      The structured status of the member, with the reason it waits.
    • ↳ failureReason string optional
      Why the member failed. Free-form text.
    • ↳ agentTaskId string optional
      The Neo task that an Agent member started.
    • ↳ currentAttempt DeliveryAttempt optional
      The current attempt of the member.
    • ↳ group DeliveryMemberGroup optional
      The group of stacks of the member.
    • ↳ dependsOn array[string] optional
      The IDs of the members that this member waits for.
    • ↳ unchangedSinceRelease integer optional
      The release that last ran the member, for a member whose status is unchanged in a local run. Not set when unknown.
    • edges array[DeliveryEdge] optional
      The edges between the stages and between the members.
    • ↳ from string required
      The start of the edge: a stage name or a member ID.
    • ↳ to string required
      The end of the edge: a stage name or a member ID.
    • ↳ kind enum required
      The kind of the edge: stage or member.
      Values: stage, member
    • artifacts DeliveryRunArtifacts optional
      The artifacts that the run recorded.
    • ↳ runNumber integer required
      The number of the run.
    • ↳ artifacts map[string]DeliveryValue optional
      The artifacts by name.
    • actions DeliveryRunActions required
      The actions available to the caller.
    • ↳ retry DeliveryAction required
      Whether the caller can retry the run.
    • ↳ cancel DeliveryAction required
      Whether the caller can cancel the run.
    Errors: 404 The stack is not a Delivery program, or has no such item

    Cancel Delivery Run

    ▼
    Preview. This endpoint is in preview and may change without notice.
    POST /api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/runs/{runNumber}/cancel

    Cancels a Delivery run of the pipeline on the stack. Work that the run started stops, and the run never shows as failed. Canceling a run that is already canceled succeeds and changes nothing. The tokens that Delivery creates for a run cannot cancel. Returns a 404 error if the stack is not a pipeline or has no such run, and a 409 error if the run is a local run or already ended in another status.

    Request Parameters

    • orgName string path required
      The organization name
    • projectName string path required
      The project name
    • stackName string path required
      The stack name
    • runNumber integer path required
      The number of the run

    Responses

    204 No Content
    Errors: 403 The credential cannot cancel a run 404 The stack is not a Delivery pipeline or has no such run 409 The run is a local run, or it already ended in another status

    Get Delivery Gate

    ▼
    Preview. This endpoint is in preview and may change without notice.
    GET /api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/runs/{runNumber}/gates/{gateID}

    Returns a gate: its title, its conditions, the rule with its satisfaction and, for each approval, the status of its change request, the approvals it needs and the approvals that count. The changes field summarizes the previews of the stage: the counts, and one entry for each member with the state of its preview and the number of changed config keys. A gate has at most 50 conditions, and the summary has one entry for each member of the stage, at most 1000.

    Request Parameters

    • orgName string path required
      The organization name
    • projectName string path required
      The project name
    • stackName string path required
      The stack name
    • runNumber integer path required
      The number of the run
    • gateID string path required
      The identifier of the gate

    Responses

    200 OK
    • gate DeliveryGate required
      The gate with its conditions.
    • ↳ id string required
      The ID of the gate.
    • ↳ stageName string optional
      The name of the stage of the gate.
    • ↳ round integer required
      The round of the gate. A retry opens a new round.
    • ↳ status enum required
      The status of the gate.
      Values: open, passed, closed
    • ↳ conditions array[DeliveryCondition] optional
      The conditions of the gate.
    • ↳ rule DeliveryRuleNode optional
      The rule of the gate with its satisfaction.
    • ↳ createdAt string required
      When the gate opened.
    • ↳ passedAt string optional
      When the gate passed.
    • ↳ closedAt string optional
      When the gate closed.
    • ↳ closeReason enum optional
      Why a closed gate closed.
      Values:
      canceled — Canceled
      The run was canceled.
      failed — Failed
      The run failed.
      superseded — Superseded
      A newer release superseded the run.
      ended — Ended
      The run ended.
      stage_converged — StageConverged
      The stage converged.
    • ↳ closedByKind enum optional
      Who closed the gate: a user, or the system for a supersede, a failure or the end of the run.
      Values: user, webhook, system, trigger
    • ↳ closedBy string optional
      The login of the user who closed the gate, for example by canceling the run.
    • runNumber integer required
      The number of the run.
    • releaseNumber integer optional
      The number of the release.
    • stageName string optional
      The name of the stage.
    • title string required
      The title for the approval, for example Approve release 25 (run 41) into prod.
    • changes DeliveryChangeSummary optional
      The summary of the stage previews for the gate. It is set for a gate of a stage.
    • ↳ stacksPreviewed integer required
      The number of stacks with a preview that is done.
    • ↳ stacksNotAvailable integer required
      The number of stacks whose preview is not available. They are not counted as unchanged.
    • ↳ stacksWithChanges integer required
      The number of previewed stacks that have changes.
    • ↳ entries array[DeliveryChangeEntry] optional
      One entry for each member of the stage, at most 1000.
    Errors: 404 The stack is not a Delivery program, or has no such item

    Continue Delivery Gate

    ▼
    Preview. This endpoint is in preview and may change without notice.
    POST /api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/runs/{runNumber}/gates/{gateID}/continue

    Continues the manual condition of a gate of a Delivery run, with an optional comment. Any credential with the pipeline:approve permission on the pipeline stack can continue a gate, except the tokens that Delivery creates for a run. The body names the condition (by name or ID) when the gate has more than one manual condition. Returns a 400 error if the comment is longer than 4096 bytes after trimming, a 404 error if the stack is not a pipeline, has no such run or gate, or the gate has no manual condition with the name in the request, and a 409 error if the gate is not open.

    Request Parameters

    • orgName string path required
      The organization name
    • projectName string path required
      The project name
    • stackName string path required
      The stack name
    • runNumber integer path required
      The number of the run
    • gateID string path required
      The identifier of the gate

    Request Body

    • condition string optional
      The name or the ID of the manual condition of the gate. It is necessary when the gate has more than one manual condition.
    • comment string optional
      An optional comment. It is shown with the person who continued the gate. Leading and trailing white space is removed, and the comment has at most 4096 bytes.

    Responses

    200 OK
    • status enum required
      The status of the gate after the action.
      Values: open, passed, closed
    Errors: 400 The gate has no manual condition, or more than one and the request does not name one, or the comment is longer than 4096 bytes after trimming 403 The credential has no pipeline:approve permission on the stack, or is a token that Delivery created for a run 404 The stack is not a Delivery pipeline, or has no such run or gate, or the gate has no manual condition with the name in the request 409 The gate is not open

    Retry Delivery Run

    ▼
    Preview. This endpoint is in preview and may change without notice.
    POST /api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/runs/{runNumber}/retry

    Retries a failed Delivery run of the pipeline on the stack. The run continues on its own stack with the same values: members that failed start again, and members that succeeded keep their results. The tokens that Delivery creates for a run cannot retry. Returns a 404 error if the stack is not a pipeline or has no such run, and a 409 error if the run is a local run, did not fail or its stack is gone, if the pipeline is being deleted, if the run reached its limit of passes, or if a stage moved on: a newer release was deployed to a stage where the run failed or waits for that stage (use rollback to deploy the release of the run again), or the run is a rollback, redeploy or promote run and something was deployed to its stage after it started (start the stage action again).

    Request Parameters

    • orgName string path required
      The organization name
    • projectName string path required
      The project name
    • stackName string path required
      The stack name
    • runNumber integer path required
      The number of the run

    Responses

    200 OK
    • runNumber integer required
      The number of the run that the action started or continued.
    Errors: 403 The credential cannot retry a run 404 The stack is not a Delivery pipeline or has no such run 409 The run is a local run, did not fail or has no stack; the pipeline is being deleted; the run reached its limit of passes; a newer release was deployed to a stage where the run failed or waits for that stage (use rollback); or the run is a rollback, redeploy or promote run and something was deployed to its stage after it started

    Pause Delivery Stage

    ▼
    Preview. This endpoint is in preview and may change without notice.
    POST /api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/stages/{stageName}/pause

    Pauses a stage of a Delivery pipeline. A run that holds the stage keeps it. Normal runs wait for the stage until it is resumed. The tokens that Delivery creates for a run cannot pause.

    Request Parameters

    • orgName string path required
      The organization name
    • projectName string path required
      The project name
    • stackName string path required
      The stack name
    • stageName string path required
      The name of the stage

    Responses

    204 No Content
    Errors: 403 The credential cannot act on a stage 404 The stack is not a Delivery pipeline, or has no such stage

    Promote Delivery Stage

    ▼
    Preview. This endpoint is in preview and may change without notice.
    POST /api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/stages/{stageName}/promote

    Deploys any ready release to a stage of a Delivery pipeline (force-promote). The new run skips the gate of the stage. The tokens that Delivery creates for a run cannot promote.

    Request Parameters

    • orgName string path required
      The organization name
    • projectName string path required
      The project name
    • stackName string path required
      The stack name
    • stageName string path required
      The name of the stage

    Request Body

    • releaseNumber integer required
      The number of the release.

    Responses

    200 OK
    • runNumber integer required
      The number of the run that the action started or continued.
    Errors: 403 The credential cannot act on a stage, or Delivery is not enabled for the organization 404 The stack is not a Delivery pipeline, or has no such stage or release 409 The release is a local release, is not ready yet, has no such stage, or did not converge, in its own run, a stage that the stage depends on; the pipeline is being deleted or has no service principal to run as; or a stack with the name of the new run stack already exists

    Redeploy Delivery Stage

    ▼
    Preview. This endpoint is in preview and may change without notice.
    POST /api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/stages/{stageName}/redeploy

    Deploys the release that a stage of a Delivery pipeline has again. The new run skips the gate of the stage. The tokens that Delivery creates for a run cannot redeploy.

    Request Parameters

    • orgName string path required
      The organization name
    • projectName string path required
      The project name
    • stackName string path required
      The stack name
    • stageName string path required
      The name of the stage

    Responses

    200 OK
    • runNumber integer required
      The number of the run that the action started or continued.
    Errors: 403 The credential cannot act on a stage, or Delivery is not enabled for the organization 404 The stack is not a Delivery pipeline, or has no such stage or release 409 Nothing was deployed to the stage yet, or the deployed release came from a local update, is not ready yet, or cannot be deployed again; the pipeline is being deleted or has no service principal to run as; or a stack with the name of the new run stack already exists

    Resume Delivery Stage

    ▼
    Preview. This endpoint is in preview and may change without notice.
    POST /api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/stages/{stageName}/resume

    Resumes a paused stage of a Delivery pipeline. The tokens that Delivery creates for a run cannot resume.

    Request Parameters

    • orgName string path required
      The organization name
    • projectName string path required
      The project name
    • stackName string path required
      The stack name
    • stageName string path required
      The name of the stage

    Responses

    204 No Content
    Errors: 403 The credential cannot act on a stage 404 The stack is not a Delivery pipeline, or has no such stage

    Rollback Delivery Stage

    ▼
    Preview. This endpoint is in preview and may change without notice.
    POST /api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/stages/{stageName}/rollback

    Rolls a stage of a Delivery pipeline back to an earlier release that was ready and converged the stage before. The rollback pauses the stage, so a newer release that waits does not deploy over it. The stage stays paused after the rollback run ends, also when it fails or is cancelled. Resume the stage to admit runs again. The new run skips the gate of the stage. The tokens that Delivery creates for a run cannot roll back.

    Request Parameters

    • orgName string path required
      The organization name
    • projectName string path required
      The project name
    • stackName string path required
      The stack name
    • stageName string path required
      The name of the stage

    Request Body

    • releaseNumber integer required
      The number of the release.

    Responses

    200 OK
    • runNumber integer required
      The number of the run that the action started or continued.
    Errors: 403 The credential cannot act on a stage, or Delivery is not enabled for the organization 404 The stack is not a Delivery pipeline, or has no such stage or release 409 Nothing was deployed to the stage yet; the release number is missing or less than 1, or the release is not lower than the release deployed to the stage, is a local release, is not ready yet, or never converged the stage; the pipeline is being deleted or has no service principal to run as; or a stack with the name of the new run stack already exists

      The infrastructure platform for humans and agents.