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. |
tenantId |
body | string | no | Promote for this tenant - see Deploy a release. Required when the project only deploys to tenants, refused when the project doesn't deploy to tenants. The tenant must be connected to the project and to every environment of the deployment, must not be archived, and must have every required tenant variable filled in for those environments. Leave it out for a deployment that is not for a tenant. |
tenantIds |
body | array<string> | no | Promote to several tenants, each to the environments of the request it uses; tenants that can't be deployed are skipped and listed in skippedTenants - see Deploy a release. |
tenantTag |
body | string | no | Promote to every tenant connected to the project (not archived) with this tag, by tag name or ID, that uses at least one of the environments. |
includeNoTenant |
body | boolean | no | With tenantIds or tenantTag: also create the deployment without a tenant. Defaults to false. |
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. |
400 |
The tenant can't be used for this deployment, and the message says why: the project only deploys to tenants and none was given, the project doesn't deploy to tenants, the tenant was not found, is archived or deleted, isn't connected to the project or to one of the environments, or is missing required values (the message names them per environment). |
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. |