// Project Steps

Update a project step

Update step name, scope, run mode, parallelism, error handling, and properties.

PUT/api/project/step

Description

Updates a step on a project. Pass only the fields to change. propertiesJson is a JSON-encoded string matching the step template's property schema.

Filters (machineIdFilter, machineTagFilter, cloudTargetTagFilter) constrain which targets the step runs on within the step's selected environments.

Parameters

NameInTypeRequiredDescription
projectStepId body string yes ID of the step.
name body string no New step name.
description body string no New description.
stepTemplateId body string no Switch to a different step template.
runOn body string no See below.
errorAction body string no See below.
disabled body boolean no Disable the step without removing it.
executeCondition body string no See below.
executeConditionScript body string no Required when executeCondition is VariableCheck: the name of the boolean variable that must resolve to true. Despite the name, it is a variable name and not a script.
parallelMachines body number no Max machines to run on in parallel.
parallelCloudTargets body number no Max cloud targets to run on in parallel.
workerTagId body string no Tag identifying the worker pool.
environments body array<string> no Environment IDs the step is restricted to.
machineIdFilter body array<string> no Restrict to these machine IDs.
machineTagFilter body array<object> no Tag-set filter for machines.
cloudTargetTagFilter body array<object> no Tag-set filter for cloud targets.
propertiesJson body string no JSON-encoded step property values.

Run mode

runOn accepts TargetMachine, Worker, or WorkerToCloudTargets. The value must also be included in the selected step template's supportedRunModes; otherwise the request returns 400.

Error action

errorAction accepts Stop or Continue. It chooses the level a script failure is logged at, and nothing else - neither value stops the deployment.

  • Stop - a failing script is logged at Error, so it counts towards the deployment ErrorCount.
  • Continue - a failing script is logged at Warning, so it counts towards WarningCount instead.

A script that exits with a non-zero code does not fail its step and does not fail the deployment either way. See Get deployment status for how to tell a clean run from a merely finished one.

Execute condition

executeCondition accepts Always, AllPreviousStepsSucceeded, or VariableCheck. It is the only setting that can hold a step back because of what happened earlier in the deployment.

  • Always - the step runs whatever came before it.
  • AllPreviousStepsSucceeded - the step is skipped when the error counts recorded against the preceding steps add up to more than zero. Only steps whose errorAction is Stop can contribute to that sum, and the first step in a project has nothing before it, so the condition never holds it back.
  • VariableCheck - the step runs only on the targets where the boolean variable named in executeConditionScript resolves to true.

A step held back by its condition is recorded as skipped, not failed, and adds nothing to ErrorCount.

Errors

StatusMeaning
400 Invalid projectStepId or validation failure.
401 Missing or invalid Basic auth credentials, or the service account lacks the required role.