Delivery
List Delivery Approvals
/api/preview/delivery/{orgName}/approvalsLists 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
orgNamestring path requiredThe organization namecontinuationTokenstring query optionalContinuation token from a previous pagemaxResultsinteger query optionalThe number of results per page. The default is 50. A value below 1 or above 100 returns a 400 error.projectstring query optionalOnly approvals of the pipeline with this project name. Use it withstack.stackstring query optionalOnly approvals of the pipeline with this stack name. Use it withproject.statusstring query optionalpending,closedorall. The default ispending. Any other value that is not empty returns a 400 error.
Responses
- The approvals of the page, newest first.
- ↳
projectstring requiredThe project name of the pipeline stack. - ↳
stackstring requiredThe stack name of the pipeline stack. - ↳
runNumberinteger requiredThe number of the run. - ↳
gateIdstring requiredThe ID of the gate. - ↳
conditionIdstring requiredThe ID of the condition. - ↳
conditionNamestring requiredThe name of the condition. - ↳
stageNamestring optionalThe name of the stage. - ↳
releaseNumberinteger optionalThe number of the release. - ↳
requestedAtstring requiredWhen the approval was requested. - ↳
actorstring optionalThe login of the user who started the run. - ↳
changeRequestStatusstring optionalThe status of the change request of the approval. - ↳
conditionStateenum optionalThe state of the condition:pending,satisfiedorrejected.Values:pending,satisfied,rejected - ↳
requiredApprovalsinteger optionalThe number of approvals that are needed. - ↳
approvalsinteger optionalThe number of approvals that count now. continuationTokenstring optionalThe token of the next page. Not set on the last page.
List Delivery Programs
/api/preview/delivery/{orgName}/programsLists 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
orgNamestring path requiredThe organization namecontinuationTokenstring query optionalContinuation token from a previous pagekindstring query optionalOnly programs of this kind. The only kind ispipeline. Any other value that is not empty returns a 400 error.maxResultsinteger query optionalThe number of results per page. The default is 50. A value below 1 or above 100 returns a 400 error.querystring query optionalOnly programs whose project or stack name contains this textstatusstring query optionalOnly programs whose latest run has this status:in_progress,succeeded,failed,canceledorsuperseded. Any other value that is not empty returns a 400 error.waitKindstring query optionalOnly programs that have a run in progress that waits for this kind of condition. The only kind isapproval. Any other value that is not empty returns a 400 error.
Responses
- The programs of the page, in stack order.
- ↳
projectstring requiredThe project name. - ↳
stackstring requiredThe stack name. - ↳
registeredboolean requiredWhether the program has an active registration. A stack with local runs only has none. - The latest run, without its stage entries.
- The stages in order.
- ↳
pendingApprovalsinteger requiredThe number of approvals that wait now. continuationTokenstring optionalThe token of the next page. Not set on the last page.
Dispatch Delivery Run
/api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/dispatchStarts 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
orgNamestring path requiredThe organization nameprojectNamestring path requiredThe project namestackNamestring path requiredThe stack name
Request Body
keystring optionalA key that prevents duplicate dispatches. A second dispatch with the same key, the samerefand the samesourcesreturns the run of the first. A dispatch with a differentrefor differentsourcesis a new dispatch. The key has at most 128 printable ASCII characters.refstring optionalA 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.- Release sources to pin. A source that is not pinned gets its latest value.
Responses
Get Delivery Program
/api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/programReturns 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
orgNamestring path requiredThe organization nameprojectNamestring path requiredThe project namestackNamestring path requiredThe stack name
Responses
orgstring requiredThe organization name.projectstring requiredThe project name.stackstring requiredThe stack name.kindenum requiredThe kind of the program:pipeline.Values:pipelineregisteredboolean requiredWhether the program has an active registration. A stack with only a failed registration has none.registeringboolean requiredWhether the first registration is still finishing. The program is not registered yet, andregistrationis the pending registration.- The active registration, or the pending one while
registeringis true. - ↳
idstring optionalThe ID of the registration. A new active registration has a new ID, so a changed ID means that the pipeline definition can have changed. - ↳
registeredboolean requiredWhether a registration is active. - ↳
statusenum optionalThe status of the registration.Values:pending,succeeded,failed,local - ↳
reasonstring optionalWhy a registration failed. - ↳
programCommitstring optionalThe commit of the registered program. - ↳
actorstring optionalWho registered the program. - ↳
actorKindenum optionalThe kind of the actor.Values:user,webhook,system,trigger - ↳
createdAtstring optionalWhen the registration was made. - ↳
warningsarray[string] optionalThe warnings of the registration. - The latest failed registration, if it is newer than the active one.
- ↳
idstring optionalThe ID of the registration. A new active registration has a new ID, so a changed ID means that the pipeline definition can have changed. - ↳
registeredboolean requiredWhether a registration is active. - ↳
statusenum optionalThe status of the registration.Values:pending,succeeded,failed,local - ↳
reasonstring optionalWhy a registration failed. - ↳
programCommitstring optionalThe commit of the registered program. - ↳
actorstring optionalWho registered the program. - ↳
actorKindenum optionalThe kind of the actor.Values:user,webhook,system,trigger - ↳
createdAtstring optionalWhen the registration was made. - ↳
warningsarray[string] optionalThe warnings of the registration. - The newest attempt to register the pipeline, whether it is queued, running, failed or done.
- ↳
idstring requiredThe ID of the entry: the ID of the update, or the ID of the queued registration when it has no update. - ↳
sourceenum requiredWho started the attempt.Values:user,push - ↳
commitstring optionalThe commit of the attempt, if known. - ↳
dirtyboolean optionalWhether the checkout of a user registration had uncommitted changes, or did not say. Not set for a push or while the update runs. - ↳
branchstring optionalThe tracked branch, if known. Only a registration that a push queued records it. - 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.
- ↳
stateenum requiredThe state of the attempt.Values:queued,running,succeeded,failed,canceled - ↳
messagestring optionalWhy the attempt failed, if it did. - ↳
activeboolean requiredWhether this is the active registration of the pipeline. - ↳
updateVersioninteger optionalThe version of the update of the pipeline stack, if the attempt has an update. - ↳
workItemIdstring optionalThe ID of the registration that the push queued. Set for a push. - ↳
requestedBystring optionalThe login of the user who ran the update, for a user registration. - ↳
createdstring requiredWhen the attempt was created. - ↳
finishedstring optionalWhen the attempt finished. Not set while it is in progress. - The stages in the order of the stage graph.
- ↳
pausedboolean requiredWhether the stage is paused. - ↳
pausedBystring optionalWho paused the stage. - ↳
pausedAtstring optionalWhen the stage was paused. - ↳
deployedReleaseNumberinteger optionalThe release deployed at the stage. - ↳
deployedRunNumberinteger optionalThe run that deployed it. - ↳
lockRunNumberinteger optionalThe run that holds the lock of the stage. - ↳
queueLengthinteger requiredThe number of runs that wait for the stage. List them with the runs route, itsstagefilter andqueuedset to true. - The run that deployed the current release of the stage.
- The last cloud release that converged the stage. Downstream pipelines read this one. It differs from
deployedwhile a local release is deployed. - 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.
- The newest open gate of the stage over all runs in progress.
- The members of the stage in the active registration, at most 1000.
- ↳
fromarray[string] optionalThe names of the stages that must converge first. - ↳
namestring requiredThe name of the stage. - ↳
whenarray[string] optionalThe kinds and names of the conditions of the stage. - The newest runs in progress, at most 20.
- ↳
numberinteger requiredThe number of the run. - ↳
kindenum requiredThe 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.
- The structured status of the run.
- ↳
triggerKindenum requiredWhat 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 upof the pipeline stack.
- ↳
actorKindenum requiredWho started the run:user,webhook,triggerorsystem.Values:user,webhook,system,trigger - ↳
actorstring optionalThe login of the user who started the run, if a user did. - ↳
targetStagestring optionalThe stage that an operator run deploys. - ↳
releaseNumberinteger optionalThe number of the release of the run. - The commit of the program that the run executes.
- ↳
programRefstring optionalThe ref (branch, tag or commit SHA) that a person started the run at. Absent for a run at the head of the program branch. - ↳
originRunNumberinteger optionalThe number of the run that an operator run repeats. - One entry for each stage of the run, in the order of the stages.
- ↳
createdAtstring requiredWhen the run was created. - ↳
finishedAtstring optionalWhen the run ended. - ↳
localboolean optionalWhether the run is a local run, started withpulumi up. Set only when it is. runsInProgressCountinteger requiredThe number of runs in progress.- Summary facts about the pipeline.
- The latest run that ended.
- The newest release.
- ↳
approvalCountinteger requiredThe number of approvals that wait now. - ↳
newestApprovalRunNumberinteger optionalThe run of the newest waiting approval. - ↳
newestApprovalGateIdstring optionalThe gate of the newest waiting approval. - ↳
newestApprovalConditionIdstring optionalThe condition of the newest waiting approval. - Whether the caller can dispatch a run.
- ↳
allowedboolean requiredWhether the caller can do the action now. - ↳
reasonstring optionalWhy the caller cannot do the action. Not set when it is allowed.
List Delivery Releases
/api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/releasesLists 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
orgNamestring path requiredThe organization nameprojectNamestring path requiredThe project namestackNamestring path requiredThe stack namecontinuationTokenstring query optionalContinuation token from a previous pagemaxResultsinteger query optionalThe number of results per page. The default is 50. A value below 1 or above 100 returns a 400 error.readyboolean query optionalWhen true, only ready releasesrollbackStagestring query optionalOnly the releases that the rollback of this stage accepts
Responses
- The releases of the page, newest first.
- ↳
numberinteger requiredThe number of the release. - The structured status of the originating run of the release.
- ↳
readyboolean requiredWhether the release is ready. A release is ready when its first pass has finished. - ↳
originRunNumberinteger requiredThe number of the run that created the release. - The commit of the program of the release.
- ↳
createdAtstring requiredWhen the release was created. - The stages where the release is deployed.
- ↳
localboolean optionalWhether the release is a local release, started withpulumi up. Set only when it is. continuationTokenstring optionalThe token of the next page. Not set on the last page.
Get Delivery Release
/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
orgNamestring path requiredThe organization nameprojectNamestring path requiredThe project namestackNamestring path requiredThe stack namereleaseNumberinteger path requiredThe number of the release
Responses
- The facts of the release.
- ↳
numberinteger requiredThe number of the release. - The structured status of the originating run of the release.
- ↳
readyboolean requiredWhether the release is ready. A release is ready when its first pass has finished. - ↳
originRunNumberinteger requiredThe number of the run that created the release. - The commit of the program of the release.
- ↳
createdAtstring requiredWhen the release was created. - The stages where the release is deployed.
- ↳
localboolean optionalWhether the release is a local release, started withpulumi up. Set only when it is. previousReleaseNumberinteger optionalThe number of the previous release.- The recorded sources of the release.
- The recorded commit of a version control source.
- ↳
changedboolean requiredWhether the value changed since the previous release. - ↳
upstreamReleaseinteger optionalThe release of the upstream pipeline. - ↳
branchstring optionalThe branch. - ↳
kindenum requiredThe kind of the source: a repository kind, orpipelinefor 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.
- ↳
namestring optionalThe name of the source in the pipeline program, which a run pins it by. - ↳
repositorystring optionalThe repository. - ↳
upstreamProgramstring optionalThe upstream program of apipelinesource, asorganization/project/stack. The upstream pipeline is always in the organization of the program. - ↳
upstreamStagestring optionalThe upstream stage. - The artifacts of the release, grouped by run.
- ↳
runNumberinteger requiredThe number of the run. - The artifacts by name.
- The rollout by stage and run.
- ↳
stageNamestring requiredThe name of the stage. - ↳
runNumberinteger requiredThe number of the run. - The structured status of the stage in the run.
- ↳
convergedAtstring optionalWhen the stage converged. runsTruncatedboolean requiredWhether the release has more runs than the artifacts and the rollout cover. The runs route lists them all.
List Delivery Runs
/api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/runsLists 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
orgNamestring path requiredThe organization nameprojectNamestring path requiredThe project namestackNamestring path requiredThe stack namecontinuationTokenstring query optionalContinuation token from a previous pagemaxResultsinteger query optionalThe number of results per page. The default is 50. A value below 1 or above 100 returns a 400 error.queuedboolean query optionalWhen true, list the runs that wait for admission to the stage instage, in admission order. It requiresstage.releaseinteger query optionalOnly runs of the release with this numberstagestring query optionalOnly runs that reached this stage: they wait at it, hold its lock or converged itstatusstring query optionalOnly runs with this status:in_progress,succeeded,failed,canceledorsuperseded. Any other value that is not empty returns a 400 error.
Responses
- The runs of the page, newest first.
- ↳
numberinteger requiredThe number of the run. - ↳
kindenum requiredThe 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.
- The structured status of the run.
- ↳
triggerKindenum requiredWhat 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 upof the pipeline stack.
- ↳
actorKindenum requiredWho started the run:user,webhook,triggerorsystem.Values:user,webhook,system,trigger - ↳
actorstring optionalThe login of the user who started the run, if a user did. - ↳
targetStagestring optionalThe stage that an operator run deploys. - ↳
releaseNumberinteger optionalThe number of the release of the run. - The commit of the program that the run executes.
- ↳
programRefstring optionalThe ref (branch, tag or commit SHA) that a person started the run at. Absent for a run at the head of the program branch. - ↳
originRunNumberinteger optionalThe number of the run that an operator run repeats. - One entry for each stage of the run, in the order of the stages.
- ↳
createdAtstring requiredWhen the run was created. - ↳
finishedAtstring optionalWhen the run ended. - ↳
localboolean optionalWhether the run is a local run, started withpulumi up. Set only when it is. continuationTokenstring optionalThe token of the next page. Not set on the last page.
Get Delivery Run Detail
/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
orgNamestring path requiredThe organization nameprojectNamestring path requiredThe project namestackNamestring path requiredThe stack namerunNumberinteger path requiredThe number of the run
Responses
- The facts of the run.
- ↳
numberinteger requiredThe number of the run. - ↳
kindenum requiredThe 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.
- The structured status of the run.
- ↳
triggerKindenum requiredWhat 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 upof the pipeline stack.
- ↳
actorKindenum requiredWho started the run:user,webhook,triggerorsystem.Values:user,webhook,system,trigger - ↳
actorstring optionalThe login of the user who started the run, if a user did. - ↳
targetStagestring optionalThe stage that an operator run deploys. - ↳
releaseNumberinteger optionalThe number of the release of the run. - The commit of the program that the run executes.
- ↳
programRefstring optionalThe ref (branch, tag or commit SHA) that a person started the run at. Absent for a run at the head of the program branch. - ↳
originRunNumberinteger optionalThe number of the run that an operator run repeats. - One entry for each stage of the run, in the order of the stages.
- ↳
createdAtstring requiredWhen the run was created. - ↳
finishedAtstring optionalWhen the run ended. - ↳
localboolean optionalWhether the run is a local run, started withpulumi up. Set only when it is. failureReasonstring optionalWhy the run failed.canceledBystring optionalThe login of the user who canceled the run.canceledAtstring optionalWhen the run was canceled.- The stack that the program of the run runs on.
- ↳
projectstring requiredThe project name of the stack. - ↳
stackstring requiredThe name of the stack. - ↳
existsboolean requiredWhether the stack still exists. A run stack is deleted with its pipeline. - The update of the pipeline stack that drove the run. Set only for a local run, which has no run stack.
- ↳
projectstring requiredThe project name of the pipeline stack. - ↳
stackstring requiredThe name of the pipeline stack. - ↳
versioninteger requiredThe version of the update on the pipeline stack. passCountinteger requiredThe number of passes of the run.- The latest pass of the run.
- ↳
numberinteger requiredThe number of the pass in the run. - ↳
statusenum requiredThe status of the pass.Values:queued,running,finished - ↳
outcomeenum optionalThe outcome of a finished pass.Values:awaiting,completed,failed,canceled - ↳
updateIdstring optionalThe ID of the update of the run stack that the pass made. - ↳
failureReasonstring optionalWhy the pass failed. Free-form text. - ↳
createdAtstring requiredWhen the pass was queued. - ↳
startedAtstring optionalWhen the pass started. - ↳
finishedAtstring optionalWhen the pass ended. - The stages of the run.
- ↳
namestring requiredThe name of the stage. - The structured status of the stage in the run.
- ↳
fromarray[string] optionalThe names of the stages that must converge first. - ↳
whenarray[string] optionalThe kinds and names of the conditions that the run declared for the stage, as kind:name. - ↳
admittedAtstring optionalWhen the stage got its lock. - ↳
convergedAtstring optionalWhen the stage converged. - The latest gate of the stage.
- The members of the run.
- ↳
idstring requiredThe ID of the member. - ↳
namestring requiredThe name of the member: the component and, for a group of stacks, the entry. - ↳
typeenum requiredThe type of the member.Values:job,stacks,artifact,agent - ↳
stageNamestring optionalThe name of the stage of the member. - The stack that a member of
Stacksupdates. - The structured status of the member, with the reason it waits.
- ↳
failureReasonstring optionalWhy the member failed. Free-form text. - ↳
agentTaskIdstring optionalThe Neo task that an Agent member started. - The current attempt of the member.
- The group of stacks of the member.
- ↳
dependsOnarray[string] optionalThe IDs of the members that this member waits for. - ↳
unchangedSinceReleaseinteger optionalThe release that last ran the member, for a member whose status is unchanged in a local run. Not set when unknown. - The edges between the stages and between the members.
- ↳
fromstring requiredThe start of the edge: a stage name or a member ID. - ↳
tostring requiredThe end of the edge: a stage name or a member ID. - ↳
kindenum requiredThe kind of the edge:stageormember.Values:stage,member - The artifacts that the run recorded.
- ↳
runNumberinteger requiredThe number of the run. - The artifacts by name.
- The actions available to the caller.
- Whether the caller can retry the run.
- Whether the caller can cancel the run.
Cancel Delivery Run
/api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/runs/{runNumber}/cancelCancels 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
orgNamestring path requiredThe organization nameprojectNamestring path requiredThe project namestackNamestring path requiredThe stack namerunNumberinteger path requiredThe number of the run
Responses
Get Delivery Gate
/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
orgNamestring path requiredThe organization nameprojectNamestring path requiredThe project namestackNamestring path requiredThe stack namerunNumberinteger path requiredThe number of the rungateIDstring path requiredThe identifier of the gate
Responses
- The gate with its conditions.
- ↳
idstring requiredThe ID of the gate. - ↳
stageNamestring optionalThe name of the stage of the gate. - ↳
roundinteger requiredThe round of the gate. A retry opens a new round. - ↳
statusenum requiredThe status of the gate.Values:open,passed,closed - The conditions of the gate.
- The rule of the gate with its satisfaction.
- ↳
createdAtstring requiredWhen the gate opened. - ↳
passedAtstring optionalWhen the gate passed. - ↳
closedAtstring optionalWhen the gate closed. - ↳
closeReasonenum optionalWhy 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.
- ↳
closedByKindenum optionalWho closed the gate: a user, or the system for a supersede, a failure or the end of the run.Values:user,webhook,system,trigger - ↳
closedBystring optionalThe login of the user who closed the gate, for example by canceling the run. runNumberinteger requiredThe number of the run.releaseNumberinteger optionalThe number of the release.stageNamestring optionalThe name of the stage.titlestring requiredThe title for the approval, for exampleApprove release 25 (run 41) into prod.- The summary of the stage previews for the gate. It is set for a gate of a stage.
- ↳
stacksPreviewedinteger requiredThe number of stacks with a preview that is done. - ↳
stacksNotAvailableinteger requiredThe number of stacks whose preview is not available. They are not counted as unchanged. - ↳
stacksWithChangesinteger requiredThe number of previewed stacks that have changes. - One entry for each member of the stage, at most 1000.
Continue Delivery Gate
/api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/runs/{runNumber}/gates/{gateID}/continueContinues 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
orgNamestring path requiredThe organization nameprojectNamestring path requiredThe project namestackNamestring path requiredThe stack namerunNumberinteger path requiredThe number of the rungateIDstring path requiredThe identifier of the gate
Request Body
conditionstring optionalThe name or the ID of the manual condition of the gate. It is necessary when the gate has more than one manual condition.commentstring optionalAn 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
statusenum requiredThe status of the gate after the action.Values:open,passed,closed
Retry Delivery Run
/api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/runs/{runNumber}/retryRetries 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
orgNamestring path requiredThe organization nameprojectNamestring path requiredThe project namestackNamestring path requiredThe stack namerunNumberinteger path requiredThe number of the run
Responses
runNumberinteger requiredThe number of the run that the action started or continued.
Pause Delivery Stage
/api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/stages/{stageName}/pausePauses 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
orgNamestring path requiredThe organization nameprojectNamestring path requiredThe project namestackNamestring path requiredThe stack namestageNamestring path requiredThe name of the stage
Responses
Promote Delivery Stage
/api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/stages/{stageName}/promoteDeploys 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
orgNamestring path requiredThe organization nameprojectNamestring path requiredThe project namestackNamestring path requiredThe stack namestageNamestring path requiredThe name of the stage
Request Body
releaseNumberinteger requiredThe number of the release.
Responses
runNumberinteger requiredThe number of the run that the action started or continued.
Redeploy Delivery Stage
/api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/stages/{stageName}/redeployDeploys 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
orgNamestring path requiredThe organization nameprojectNamestring path requiredThe project namestackNamestring path requiredThe stack namestageNamestring path requiredThe name of the stage
Responses
runNumberinteger requiredThe number of the run that the action started or continued.
Resume Delivery Stage
/api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/stages/{stageName}/resumeResumes a paused stage of a Delivery pipeline. The tokens that Delivery creates for a run cannot resume.
Request Parameters
orgNamestring path requiredThe organization nameprojectNamestring path requiredThe project namestackNamestring path requiredThe stack namestageNamestring path requiredThe name of the stage
Responses
Rollback Delivery Stage
/api/preview/stacks/{orgName}/{projectName}/{stackName}/delivery/stages/{stageName}/rollbackRolls 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
orgNamestring path requiredThe organization nameprojectNamestring path requiredThe project namestackNamestring path requiredThe stack namestageNamestring path requiredThe name of the stage
Request Body
releaseNumberinteger requiredThe number of the release.
Responses
runNumberinteger requiredThe number of the run that the action started or continued.