Pipeline run sequence

  • Article
  • 12 minutes to read

Azure DevOps Services | Azure DevOps Server 2020 | Azure DevOps Server 2019

Runs correspond one execution of a pipeline. During a run, the pipeline is candy, and agents process one or more than jobs. A pipeline run includes jobs, steps, and tasks. Runs power both continuous integration (CI) and continuous delivery (CD) pipelines.

Pipeline overview

When yous run a pipeline, many things happen under the covers. While you often won't need to know about them, occasionally it's useful to have the big picture show. At a loftier level, Azure Pipelines will:

  • Process the pipeline
  • Request one or more agents to run jobs
  • Hand off jobs to agents and collect the results

On the agent side, for each job, an agent volition:

  • Get fix for the job
  • Run each pace in the job
  • Study results to Azure Pipelines

Jobs may succeed, neglect, or be canceled. At that place are likewise situations where a job may non consummate. Understanding how this happens tin can assistance you troubleshoot issues.

Permit's break down each action one past one.

Procedure the pipeline

Expand YAML templates

To plough a pipeline into a run, Azure Pipelines goes through several steps in this guild:

  1. Showtime, expand templates and evaluate template expressions.
  2. Next, evaluate dependencies at the stage level to pick the first stage(s) to run.
  3. For each stage selected to run, 2 things happen:
    • All resource used in all jobs are gathered upward and validated for authorization to run.
    • Evaluate dependencies at the job level to pick the first job(s) to run.
  4. For each job selected to run, aggrandize multi-configs (strategy: matrix or strategy: parallel in YAML) into multiple runtime jobs.
  5. For each runtime job, evaluate weather to decide whether that job is eligible to run.
  6. Asking an agent for each eligible runtime job.

Equally runtime jobs complete, Azure Pipelines will run into if there are new jobs eligible to run. If then, steps 4 - 6 repeat with the new jobs. Similarly, every bit stages complete, steps 2 - half dozen will exist repeated for whatever new stages.

This ordering helps answer a mutual question: why can't I use sure variables in my template parameters? Step 1, template expansion, operates solely on the text of the YAML certificate. Runtime variables don't exist during that footstep. Later step 1, template parameters take been resolved and no longer exist.

Information technology also answers another mutual issue: why can't I use variables to resolve service connectedness / environment names? Resources are authorized before a stage can start running, so phase- and task-level variables aren't bachelor. Pipeline-level variables can be used, but only those explicitly included in the pipeline. Variable groups are themselves a resources subject to authorization, so their data is too not bachelor when checking resource authorization.

Request an agent

Whenever Azure Pipelines needs to run a job, it will ask the pool for an agent. (Server jobs are an exception, since they run on the Azure Pipelines server itself.) Microsoft-hosted and cocky-hosted amanuensis pools work slightly differently.

Microsoft-hosted amanuensis pool requests

Offset, the service checks on your organization'southward parallel jobs. It adds upwardly all running jobs on all Microsoft-hosted agents and compares that with the number of parallel jobs purchased. If there are no available parallel slots, the job has to wait on a slot to free up.

Once a parallel slot is bachelor, the job is routed to the requested agent type. Conceptually, the Microsoft-hosted pool is one behemothic, global pool of machines. (In reality, it's many different physical pools split by geography and operating system type.) Based on the vmImage (in YAML) or puddle proper noun (in the classic editor) requested, an agent is selected.

Pool selection

All agents in the Microsoft puddle are fresh, new virtual machines that haven't run any pipelines earlier. When the job completes, the agent VM will be discarded.

Self-hosted agent pool requests

Similar to the Microsoft-hosted pool, the service first checks on your organization'southward parallel jobs. It adds upwardly all running jobs on all self-hosted agents and compares that with the number of parallel jobs purchased. If in that location are no available parallel slots, the chore has to expect on a slot to free upward.

Once a parallel slot is available, the cocky-hosted pool is examined for a compatible amanuensis. Cocky-hosted agents offering capabilities, which are strings indicating that item software is installed or settings are configured. The pipeline has demands, which are the capabilities required to run the job. If a free agent whose capabilities lucifer the pipeline'southward demands cannot be constitute, the job volition continue waiting. If there are no agents in the pool whose capabilities match the demands, the job will neglect.

Self-hosted agents are typically reused from run to run. This means that a pipeline job can have side effects: warming up caches, having most commits already bachelor in the local repo, and so on.

Set to run a job

Once an amanuensis has accepted a chore, information technology has some preparation work to do. The amanuensis downloads (and caches for next fourth dimension) all the tasks needed to run the job. It creates working infinite on disk to hold the source code, artifacts, and outputs used in the run. Then information technology begins running steps.

Run each step

Steps are run sequentially, i later on another. Before a step can start, all the previous steps must be finished (or skipped).

Run each task

Steps are implemented by tasks. Tasks themselves are implemented as Node.js or PowerShell scripts. The job system routes inputs and outputs to the backing scripts. It also provides some mutual services such equally altering the system path and creating new pipeline variables.

Each pace runs in its ain procedure, isolating it from the environs left by previous steps. Because of this process-per-step model, surround variables are not preserved between steps. Still, tasks and scripts have a mechanism to communicate back to the agent: logging commands. When a task or script writes a logging command to standard out, the agent will accept whatever action is requested.

There is an agent control to create new pipeline variables. Pipeline variables volition be automatically converted into environment variables in the next stride. In order to ready a new variable myVar with a value of myValue, a script can practice this:

              echo '##vso[task.setVariable variable=myVar]myValue'                          
              Write-Host "##vso[task.setVariable variable=myVar]myValue"

Report and collect results

Each step can report warnings, errors, and failures. Errors and warnings are reported to the pipeline summary page, marking the task equally "succeeded with issues". Failures are also reported to the summary page, but they marker the job equally "failed". A step is a failure if it either explicitly reports failure (using a ##vso command) or ends the script with a non-zero exit lawmaking.

Logs and results flow from agent to service

As steps run, the amanuensis is constantly sending output lines to the service. That's why y'all can see a alive feed of the console. At the end of each pace, the entire output from the pace is also uploaded as a log file. Logs can be downloaded once the pipeline has finished. Other items that the agent can upload include artifacts and examination results. These are too available after the pipeline completes.

Land and conditions

The amanuensis keeps rails of each step's success or failure. As steps succeed with issues or neglect, the job'southward status will be updated. The job e'er reflects the "worst" outcome from each of its steps: if a step fails, the job also fails.

Before running a step, the agent volition check that footstep'south condition to make up one's mind whether it should run. By default, a step will only run when the job'due south condition is succeeded or succeeded with issues. Many jobs accept cleanup steps that demand to run no matter what else happened, so they tin can specify a condition of "e'er()". Cleanup steps might also be fix to run merely on cancellation. A succeeding cleanup step cannot salve the chore from failing; jobs can never become back to success after entering failure.

Timeouts and disconnects

Each job has a timeout. If the job has not completed in the specified time, the server will abolish the task. Information technology volition effort to betoken the agent to stop, and information technology volition mark the job as canceled. On the agent side, this ways canceling all remaining steps and uploading any remaining results.

Jobs accept a grace menstruum known as the cancel timeout in which to complete any cancellation work. (Recall, steps tin can be marked to run even on counterfoil.) Subsequently the timeout plus the cancel timeout, if the amanuensis has not reported that work has stopped, the server will mark the job as a failure.

Because Azure Pipelines distributes work to amanuensis machines, from time to time, agents may stop responding to the server. This tin can happen if the agent's host machine goes away (power loss, VM turned off) or if there'south a network failure. To help detect these conditions, the amanuensis sends a heartbeat message once per minute to let the server know it'due south still operating. If the server doesn't receive a heartbeat for 5 consecutive minutes, information technology assumes the agent will not come back. The task is marked equally a failure, letting the user know they should retry the pipeline.

Manage runs through the CLI

Using the Azure DevOps CLI, you can list the pipeline runs in your project and view details almost a specific run. You can likewise add and delete tags in your pipeline run.

Prerequisites

  • You lot must take installed the Azure DevOps CLI extension every bit described in Go started with Azure DevOps CLI.
  • Sign into Azure DevOps using az login.
  • For the examples in this commodity, set the default organization using az devops configure --defaults organization=YourOrganizationURL.

List pipeline runs

List the pipeline runs in your projection with the az pipelines runs list control. To get started, see Get started with Azure DevOps CLI.

                az pipelines runs listing [--branch]                        [--org]                        [--pipeline-ids]                        [--project]                        [--query-guild {FinishTimeAsc, FinishTimeDesc, QueueTimeAsc, QueueTimeDesc, StartTimeAsc, StartTimeDesc}]                        [--reason {all, batchedCI, buildCompletion, checkInShelveset, individualCI, manual, pullRequest, schedule, triggered, userCreated, validateShelveset}]                        [--requested-for]                        [--result {canceled, failed, none, partiallySucceeded, succeeded}]                        [--status {all, cancelling, completed, inProgress, none, notStarted, postponed}]                        [--tags]                        [--height]

Optional parameters

  • branch: Filter by builds for this branch.
  • org: Azure DevOps organization URL. You can configure the default organization using az devops configure -d organisation=ORG_URL. Required if not configured as default or picked up using git config. Example: --org https://dev.azure.com/MyOrganizationName/.
  • pipeline-ids: Space-separated IDs of definitions for which to list builds.
  • project: Proper name or ID of the project. You tin configure the default project using az devops configure -d projection=NAME_OR_ID. Required if not configured every bit default or picked upward using git config.
  • query-guild: Define the gild in which pipeline runs are listed. Accepted values are FinishTimeAsc, FinishTimeDesc, QueueTimeAsc, QueueTimeDesc, StartTimeAsc, and StartTimeDesc.
  • reason: Merely list builds for this specified reason. Accepted values are batchedCI, buildCompletion, checkInShelveset, individualCI, manual, pullRequest, schedule, triggered, userCreated, and validateShelveset.
  • requested-for: Limit to the builds requested for a specified user or grouping.
  • result: Limit to the builds with a specified upshot. Accustomed values are canceled, failed, none, partiallySucceeded, and succeeded.
  • status: Limit to the builds with a specified status. Accepted values are all, cancelling, completed, inProgress, none, notStarted, and postponed.
  • tags: Limit to the builds with each of the specified tags. Space separated.
  • peak: Maximum number of builds to list.

Example

The post-obit control lists the first iii pipeline runs that have a status of completed and a event of succeeded, and returns the event in table format.

                az pipelines runs list --status completed --result succeeded --acme 3 --output table  Run ID    Number      Condition     Result     Pipeline ID    Pipeline Name               Source Branch    Queued Time                 Reason --------  ----------  ---------  ---------  -------------  --------------------------  ---------------  --------------------------  ------ 125       20200124.1  completed  succeeded  12             Githubname.pipelines-java  master           2020-01-23 xviii:56:ten.067588  manual 123       20200123.two  completed  succeeded  12             Githubname.pipelines-java  master           2020-01-23 xi:55:56.633450  manual 122       20200123.ane  completed  succeeded  12             Githubname.pipelines-java  principal           2020-01-23 11:48:05.574742  manual

Prove pipeline run details

Show the details for a pipeline run in your project with the az pipelines runs show command. To get started, see Get started with Azure DevOps CLI.

                az pipelines runs show --id                        [--open]                        [--org]                        [--project]

Parameters

  • id: Required. ID of the pipeline run.
  • open: Optional. Opens the build results page in your web browser.
  • org: Azure DevOps organization URL. You can configure the default organization using az devops configure -d organization=ORG_URL. Required if not configured as default or picked up using git config. Example: --org https://dev.azure.com/MyOrganizationName/.
  • project: Proper noun or ID of the project. You lot can configure the default project using az devops configure -d project=NAME_OR_ID. Required if not configured as default or picked upwardly using git config.

Example

The following command shows details for the pipeline run with the ID 123 and returns the results in table format. It also opens your web browser to the build results page.

                az pipelines runs prove --id 122 --open --output table  Run ID    Number      Status     Outcome     Pipeline ID    Pipeline Proper noun               Source Branch    Queued Time                 Reason --------  ----------  ---------  ---------  -------------  --------------------------  ---------------  --------------------------  -------- 123       20200123.2  completed  succeeded  12             Githubname.pipelines-java  master           2020-01-23 11:55:56.633450  transmission

Add tag to pipeline run

Add together a tag to a pipeline run in your project with the az pipelines runs tag add together command. To go started, see Go started with Azure DevOps CLI.

                az pipelines runs tag add --run-id                           --tags                           [--org]                           [--project]

Parameters

  • run-id: Required. ID of the pipeline run.
  • tags: Required. Tags to be added to the pipeline run (comma-separated values).
  • org: Azure DevOps organization URL. You can configure the default organization using az devops configure -d organisation=ORG_URL. Required if not configured equally default or picked up using git config. Example: --org https://dev.azure.com/MyOrganizationName/.
  • project: Proper name or ID of the projection. You can configure the default project using az devops configure -d project=NAME_OR_ID. Required if not configured every bit default or picked upwards using git config.

Case

The following command adds the tag YAML to the pipeline run with the ID 123 and returns the result in JSON format.

                az pipelines runs tag add --run-id 123 --tags YAML --output json  [   "YAML" ]

List pipeline run tags

Listing the tags for a pipeline run in your project with the az pipelines runs tag list control. To become started, come across Become started with Azure DevOps CLI.

                az pipelines runs tag listing --run-id                            [--org]                            [--project]

Parameters

  • run-id: Required. ID of the pipeline run.
  • org: Azure DevOps organization URL. You can configure the default organization using az devops configure -d arrangement=ORG_URL. Required if not configured equally default or picked upwards using git config. Instance: --org https://dev.azure.com/MyOrganizationName/.
  • project: Name or ID of the project. You tin configure the default project using az devops configure -d projection=NAME_OR_ID. Required if non configured as default or picked upwardly using git config.

Example

The following command lists the tags for the pipeline run with the ID 123 and returns the result in table format.

                az pipelines runs tag listing --run-id 123 --output table  Tags ------ YAML

Delete tag from pipeline run

Delete a tag from a pipeline run in your projection with the az pipelines runs tag delete control. To become started, meet Get started with Azure DevOps CLI.

                az pipelines runs tag delete --run-id                              --tag                              [--org]                              [--projection]

Parameters

  • run-id: Required. ID of the pipeline run.
  • tag: Required. Tag to exist deleted from the pipeline run.
  • org: Azure DevOps arrangement URL. You can configure the default arrangement using az devops configure -d organization=ORG_URL. Required if non configured equally default or picked up using git config. Case: --org https://dev.azure.com/MyOrganizationName/.
  • projection: Name or ID of the project. You can configure the default project using az devops configure -d project=NAME_OR_ID. Required if not configured as default or picked upwardly using git config.

Example

The following command deletes the YAML tag from the pipeline run with ID 123.

                az pipelines runs tag delete --run-id 123 --tag YAML