Description
Promotes a project's release without needing to know its release ID. If version is omitted, the highest existing version is used - highest by SemVer across the whole project, which is not necessarily the most recently created release and does not take channels into account. The deployment payload is the same as /api/release/deploy aside from looking up the release by project and version.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId |
body | string | yes | ID of the project to promote. |
version |
body | string | no | Specific version to promote, matched exactly as the release was created. Unlike Get a release and List deployments, this does not fall back to a SemVer equivalent - 6.1 will not find a release stored as 6.1.0. That is deliberate: those two are reads, and this one starts a deployment, so a version it was not given exactly is refused rather than interpreted. Defaults to the highest existing version when omitted. |
environmentName |
body | string | no | Single environment to deploy to. |
phaseName |
body | string | no | Promote to every environment in the given lifecycle phase. |
environments |
body | array<object> | no | Per-environment machine rules - same shape as /api/release/deploy. |
redownloadPackages |
body | boolean | no | Force agents to redownload packages. |
deploymentDateUnixMillis |
body | integer | no | Schedule the deployment for a future time (UTC unix millis). |
excludeStepNames |
body | array<string> | no | Skip these step names from the deployment. |
Errors
| Status | Meaning |
|---|---|
400 |
Invalid projectId, no release found to promote, no matching environments, or validation failure. |
400 |
One or more of the named environments is not available for this release - the message reads some environments are not available (disabled or blocked by phase progression for this release) and lists them. An environment is unavailable when it has been switched off with Update an environment, or when the release has not reached its lifecycle phase yet. Check enabled on List environments to tell the two apart. |
409 |
Resource usage limit exceeded. |
401 |
Missing or invalid Basic auth credentials, the service account may not deploy this project, or it may not deploy to one of the environments named - the last of those lists the environment IDs it refused. |