Skip to main content
POST
Error
Back to the Project deployment APIs overview Use this endpoint to promote an active deployment’s release to a higher environment. The call moves the same immutable release to the targetEnvironment and checks that environment’s qualification gate again. The source deployment must be active. The request needs the cicd.promote scope and authority on the target environment. Promotion creates a new deployment and runs asynchronously. The response returns deploymentId, jobId, statusUrl, and jobStatusUrl. Use the deploymentId with Get deployment to track progress. To bypass the gate, set bypassQualificationGate to true and send a bypassReason. The bypass needs the cicd.gate.bypass scope. Promotion works for projects that you import with the Import API when you build the release with source.kind set to project_snapshot. The API returns these errors:
  • 403 ENV_SCOPE_VIOLATION: Your key or token lacks authority for targetEnvironment.
  • 404: The deployment doesn’t exist or you can’t access it.
  • 409 DEPLOYMENT_NOT_PROMOTABLE: The source deployment is not active.
  • 409: The release failed the qualification gate.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

projectId
string
required

UUID v7; must be in the key/token's projectIds.

deploymentId
string
required

Body

application/json
targetEnvironment
enum<string>
required
Available options:
dev,
staging,
production
bypassQualificationGate
boolean

Requires scope cicd.gate.bypass.

bypassReason
string

Response

Promotion started

success
boolean
required
deploymentId
string
required

Id of the (new) deployment this action created.

jobId
string
required

cicd-deploy-<deploymentId>.

statusUrl
string
jobStatusUrl
string