Get deployment status

Description

Returns the current status of a deployment, plus a chunk of logs. To poll incrementally, pass status.LastLogDateTick from the previous response as getLogsAfter.

Parameters

The status object

status describes the deployment as a whole and is returned whether or not you asked for logs. Status, ErrorCount and WarningCount are always present. Every other field can be null, and every date is UTC.

• Status - how far the deployment engine got, as one of the names listed under Status values below. It reports the state of the run, not a verdict on the deployed work - see Deciding whether a deployment succeeded.
• ErrorCount - how many error-level log entries the deployment has recorded so far, counting entries logged at Error and Critical. It only ever grows, and it counts log lines rather than failed steps, so one failing step can add several. A deployment that reached Completed can still have a non-zero ErrorCount.
• WarningCount - the same count for entries logged at Warning.
• LastLogDate and LastLogDateTick - the timestamp of the newest log entry of this deployment, as an ISO 8601 date and as the matching .NET tick count. Feed the tick value back as getLogsAfter to page through new entries. Both are null until the deployment writes its first log entry.
• LastUpdate - when the server last updated the deployment record. A running deployment refreshes this as it makes progress, so it doubles as a liveness signal.
• LastAttemptDate - when a worker last picked the deployment up. A deployment that waits for a slot and is retried has this set more than once.
• CancellationRequestedDate - when cancellation was requested, or null if it was not. This can be set while the deployment is still Running, because the request is recorded first and the deployment stops once it reaches a point where it can.
• CancellationRequestedByName - the email address of the user who requested the cancellation, falling back to their display name.
• CompleteDate - when the deployment finished. null until it does.

Each entry in logs carries its own ErrorCount and WarningCount. Those are not copies of the deployment totals - they count the failures recorded underneath that entry in the log tree, so a step group reports the errors of its children while the error line itself stays at 0.

Status values

Status is one of seven names, returned exactly as spelled here.

• Queued - the deployment has been accepted and is waiting for a worker. Every deployment starts here.
• Validating - a worker has claimed the deployment and is preparing it to run.
• AwaitingSlot - the deployment is ready but the organization has no free deployment slot, so it is waiting for one. It goes back to Validating when a slot frees up.
• Running - the deployment is executing its steps.
• Completed - the engine reached the end of the step list. It means the run finished, not that the deployed work was healthy.
• Failed - the engine could not finish the run. The usual causes are an agent that could not be reached, a package or script module that could not be delivered to a target, a step that timed out, a deployment that outlived its maximum duration, or an unhandled error in the run itself. The reason is written to the log.
• Cancelled - the deployment was stopped after a cancellation request.

Completed, Failed and Cancelled are terminal - a deployment in one of them will not change again, so this is where polling should stop. The other four are transient, and a deployment can move between AwaitingSlot and Validating more than once before it runs.

Deciding whether a deployment succeeded

Status and ErrorCount answer two different questions. Status says whether the engine completed the orchestration. ErrorCount says whether the work it orchestrated reported problems.

A failing script does not fail its step and does not fail the deployment. The agent reports the step as completed, and the failure is recorded as a log entry - which is what moves ErrorCount. A deployment in which every script failed still returns Status of Completed.

What counts as a failing script depends on the script language:

• powershell (PowerShell 7) - an error the script raises: a throw, or a cmdlet error or Write-Error that stops the script. The exit code does not fail the step. A script that ends with exit 3 counts as a success and logs a warning saying so, which adds to WarningCount. A native command (such as cmd /c) that returns a non-zero code logs nothing at all. To fail on an exit code, check it and throw, for example if ($LASTEXITCODE -ne 0) { throw "Exited with code $LASTEXITCODE" }.
• powershell5 (Windows PowerShell 5.1) and python - the script runs as a separate process, and that process ending with a non-zero code is a failure, as is an error the script raises. exit 3 counts. A native command's code counts only if the script passes it on with exit.

Treat a deployment as successful only when all three of these hold:

1. Status is Completed.
2. ErrorCount is 0.
3. The run reached the targets you expected - see Steps that match no targets below.

How errorAction changes the counts

Every step carries an errorAction of Stop or Continue. It chooses the level a script failure is logged at, and nothing else:

• Stop - the failure is logged at Error, so it increments ErrorCount.
• Continue - the failure is logged at Warning, so it increments WarningCount and leaves ErrorCount untouched.

Neither value ends the deployment. On a project whose steps use Continue, an ErrorCount of 0 no longer proves the run was clean, and WarningCount and the log have to be read as well.

Later steps still run

A step that records errors does not stand down the steps after it. The engine offers every remaining step, and only the executeCondition of that step can hold it back:

• Always - the step runs whatever happened before it.
• AllPreviousStepsSucceeded - the step is skipped when the error counts recorded against all preceding steps add up to more than zero. This is the only condition that reacts to earlier failures, and it counts the same error-level entries that drive ErrorCount, so an earlier step set to Stop is what arms it and Continue is what disarms it.
• VariableCheck - the step runs only where the named boolean variable resolves to true.

A skipped step is not a failure. It is recorded as skipped and adds nothing to ErrorCount.

Steps that match no targets

A step whose machine ID or tag filters match no agent has nothing to run on. That is not treated as an error: the step is recorded as finished, contributes no errors, and a deployment made entirely of such steps reaches Completed having done no work. A step whose only matching agents are disabled behaves the same way.

Nothing in the status object distinguishes this from a step that ran everywhere. To tell them apart, call Get deployment targets, which lists every step with the targets it matched and ran on. Or read logs: every target a step ran on appears as a child entry named Machine <machineId> / <name> beneath that step entry, and a step that matched nothing has no such children. Agents that were considered and filtered out are listed only when the deployment runs with the boolean project variable __debug set to true.

Errors