Description
Deploys an existing release. You can target an environment by name, a lifecycle phase, or pass a structured environments list with per-environment machine rules.
Returns the new deployment IDs (one per environment). The deployment runs asynchronously - poll GET /api/deployment for status.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
releaseId |
body | string | yes | ID of the release to deploy. |
environmentName |
body | string | no | Single environment to deploy to (alternative to environments). |
phaseName |
body | string | no | Deploy to every environment in the given lifecycle phase. |
environments |
body | array<object> | no | List of { environmentName, machineMode, machineIds? } setups for fine-grained control. |
redownloadPackages |
body | boolean | no | Force agents to redownload packages even if cached. |
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 | Deploy for this tenant. 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 | Deploy to several tenants: each tenant gets one deployment per environment of the request that it uses for the project. Each tenant is checked like tenantId, for its own environments; the ones that can't be deployed (also a tenant that uses none of the environments) are skipped and listed in skippedTenants. A tenantId sent as well joins the list. |
tenantTag |
body | string | no | Deploy to every tenant connected to the project (not archived) that has this tag, by tag name or ID, and uses at least one of the environments. Can be combined with tenantIds; a tenant named twice is deployed once. |
includeNoTenant |
body | boolean | no | With tenantIds or tenantTag: also create the deployment without a tenant (projects that allow tenants). Defaults to false. |
Deploying for a tenant
Send tenantId to deploy the release for one tenant. Each deployment created (one per environment) is for that tenant. When it is created, the tenant's variable values for its environment are copied onto it - a value given for that environment wins over the tenant's value for all environments, which wins over the variable's default. A retry of the deployment uses that copy, so changing the tenant's values afterwards only affects new deployments. Secret values stay encrypted in the copy.
In the deployment, tenant values are variables like the project's (#{Name} and VAR.Name), and they can refer to project variables and the other way round. A project value scoped to a tag, machine, cloud target or step still wins over a tenant value of the same name; an unscoped or environment-only project value does not. The script context also gets Tenant.Id, Tenant.Name and Tenant.Tags (tag names joined with a comma). They are not defined for a deployment that is not for a tenant.
Only machines and cloud targets set to serve this tenant take part - directly, or through one of the tenant's tags. A deployment that is not for a tenant leaves out targets set to "only for tenants". Workers are not picked by tenant. A step that ends up with no targets follows its onNoTargets setting.
Deploying to several tenants
Send tenantIds, tenantTag, or both, to deploy the release to several tenants at once. Each tenant gets its own ordinary deployments, as if it had been sent with tenantId: the same queue and parallel limit, its own copy of tenant values and its own machines. With includeNoTenant the deployment without a tenant is created too.
Each tenant is deployed only to the environments of the request (or of phaseName) that it uses for the project. For example, with a phase of Prod EU and Prod US, a tenant that uses Prod EU gets one deployment to Prod EU; the deployment without a tenant goes to both.
Each tenant is checked on its own, for its own environments (archived, not connected to the project, uses none of the environments, missing required values, not finished the earlier phase). Tenants that fail are skipped and listed in skippedTenants as { tenantId, name, reason }; the rest are deployed. When none can be deployed the request is refused with every reason. deployments lists what was created, with the environment and tenant of each deployment.
A request with only tenantId works as before: the tenant must use every environment of the request.
{
"releaseId": "rel_9f4c...",
"environmentName": "Production",
"tenantTag": "eu"
}
Errors
| Status | Meaning |
|---|---|
400 |
Invalid releaseId, 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). |
400 |
With tenantIds or tenantTag: none of the tenants can be deployed (the message gives each reason), no tenant connected to the project has the tag (or none with the tag uses any of the environments), or the project doesn't deploy to tenants. |
409 |
Resource usage limit exceeded - response includes resourceUsageErrors. |
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. |