Task types and usage

In YAML, you specify the major version by using @ in the task name. For example, to use version 2 of the PublishTestResults task, specify PublishTestResults@2. You can specify which minor version to use by providing the full task version number after the @, such as GoTool@0.3.1.

In Classic pipelines, each task has a Version selector to let you choose the version you want. Consider cloning the pipeline and testing the cloned pipeline with new major task versions. If you select a preview version such as 1.* Preview, the version is still under development and might have issues.

If you change the version and have problems with your builds, you can revert the pipeline change from the History tab. For release pipelines, the ability to restore to an older version isn't available. You must manually revert the changes to the release pipeline, then save the pipeline.

The following properties are available for YAML pipeline task steps. For more information, see the steps.task definition.

Conditions

A task can't determine whether to continue the pipeline job after the task finishes, only provide an ending status such as succeeded or failed. Downstream tasks and jobs can then set a condition based on that status to determine whether to run.

The conditions property specifies conditions under which this task runs. By default, a step runs if nothing in its job failed yet and the step immediately preceding it completed.

You can override or customize these defaults by setting the step to run even if or only if a previous dependency fails or has another outcome. You can also define custom conditions, which are composed of expressions.

Conditions based on previous dependency status include:

• Succeeded: Run only if all previous dependencies succeed. This behavior is the default if no condition is set in the YAML. To apply this condition, specify condition: succeeded().
• Succeeded or failed: Run even if a previous dependency fails, unless the run is canceled. To apply this condition, specify condition: succeededOrFailed().
• Always: Run even if a previous dependency fails, even if the run is canceled. To apply this condition, specify condition: always().
• Failed: Run only when a previous dependency fails. To apply this condition, specify condition: failed().

In the following YAML example, PublishTestResults@2 runs even if the previous step failed, because of its succeededOrFailed condition.

steps:
- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.x'
    architecture: 'x64'
- task: PublishTestResults@2
  inputs:
    testResultsFiles: "**/TEST-*.xml"
  condition: succeededOrFailed()

Continue on error

The continueOnError property tells the task whether to continue running and report success regardless of failures. If set to true, this property tells the task to ignore a failed status and continue running. Downstream steps and jobs treat the task result as success when they make their run decisions.

Enabled

By default, the task runs whenever the job runs. You can set enabled to false to disable the task. Temporarily disabling the task is useful to remove the task from the process for testing purposes or for specific deployments.

Retry count on task failure

The retryCountOnTaskFailure property specifies the number of times to retry the task if it fails. The default is zero retries.

• The maximum number of retries allowed is 10.
• The wait time before retry increases after each failed attempt, following an exponential backoff strategy. The first retry happens after 1 second, the second retry after 4 seconds, and the tenth retry after 100 seconds.
• Retrying the task doesn't provide idempotency. Side effects of the first try, such as partially creating an external resource, could cause retries to fail.
• No information about the number of retries is made available to the task.
• Task failure adds a warning to the task logs indicating that it failed before retrying the task.
• All retry attempts show in the UI as part of the same task node.

resources:
  containers:
  - container: pycontainer
    image: python:3.11

steps:
- task: SampleTask@1
  target: host
- task: AnotherTask@1
  target: pycontainer

Timeout

The timeout period begins when the task starts running, and doesn't include the time the task is queued or is waiting for an agent.

In Classic pipelines, tasks offer several Control Options.

Enabled

Clear the Enabled check box to disable a task. Temporarily disabling the task is useful to remove the task from the process for testing purposes or for specific deployments.

Continue on error

Select this option if you want this task to report success even if it fails, possibly allowing dependent tasks in the same job to run. The overall build or deployment can be no more than partially successful. Whether subsequent tasks run also depends on their Run this task setting.

Number of retries if task failed

Specify the number of retries if this task fails. The default is zero.

• The failing task retries in seconds. The wait time before retry increases after each failed attempt.
• Retrying the task doesn't provide idempotency. Side effects of the first try, such as partially creating an external resource, could cause retries to fail.
• No information about the retry count is made available to the task.
• Task failure adds a warning to the task logs indicating that it failed before retrying the task.
• All retry attempts show in the UI as part of the same task node.

Timeout

Enter the maximum time in minutes that the task can run before being automatically canceled. The default is 0, or infinite time. Setting a value other than zero overrides the setting for the parent task job. The timeout period begins when the task starts running, and doesn't include the time the task is queued or is waiting for an agent.

Run this task

Select one of the following conditions for running this task:

• Only when all previous tasks have succeeded. This condition is the default.
• Even if a previous task has failed, unless the build was canceled
• Even if a previous task has failed, even if the build was canceled
• Only when a previous task has failed
• Custom conditions, and then enter a Custom condition specifying an expression for when this task should run.

A YAML pipeline task can specify an env property, which lists name/value strings that represent environment variables.

- task: AzureCLI@2
  env:
    ENV_VARIABLE_NAME: value
    ENV_VARIABLE_NAME2: value
  ...

You can set environment variables by using script steps, or by using scripts in command line, Bash, or PowerShell tasks.

The following example runs a script step that assigns a value to the ENV_VARIABLE_NAME environment variable and echoes the value.

- script: echo "This is " $ENV_VARIABLE_NAME
  env:
    ENV_VARIABLE_NAME: value
  displayName: 'echo environment variable'

The preceding script is functionally the same as running a Bash@3 task with a script input. The following example uses the task syntax.

- task: Bash@3
  inputs:
    script: echo "This is " $ENV_VARIABLE_NAME
  env:
    ENV_VARIABLE_NAME: value
  displayName: 'echo environment variable'

In Classic pipelines, you can add and edit environment variables in the Environment Variables section of the task editor.

Create an azure-pipelines.yml file that has the following contents in your project's base directory.

pool:
  vmImage: 'windows-latest'

jobs:
- job: NodeJS
  strategy:
    matrix:
      node14:
        nodeVersion: '14.x'
      node16:
        nodeVersion: '16.x'
    maxParallel: 2
  steps:
    - task: NodeTool@0
      displayName: 'Install Node.js $(nodeVersion)'
      inputs:
        versionSpec: '$(nodeVersion)'
        checkLatest: true

    - script: |
        echo Using Node version $(nodeVersion)
        node --version
      displayName: 'Verify Node Installation'

Save and run the pipeline. The job runs twice, one for each version of Node.js you specified in the nodeVersion variable.

The Node.js Tool Installer downloads the Node.js version if it isn't already on the agent. The Command Line script writes the installed version to the command line.

1. In the Agent job for your Classic pipeline, under Execution plan, set Parallelism to Multi-configuration.

2. Under Multipliers, enter nodeVersion.

3. Set Maximum number of agents to 2.

4. Add the Node.js tool installer task to your pipeline with the following settings:

   • Enter $(nodeVersion) under Version Spec.
   • Select the check box for Check for Latest Version.

5. Add the Command line task to your pipeline, and enter the following code under Script:

   echo Using Node version $(nodeVersion)
node --version

6. On the Variables tab, define the variable nodeVersion with the value 14.x, 16.x, and select Settable at queue time.

   Note

   In a Release pipeline, select Settable at release time. For more information, see How can I edit variables at release time?

7. Select Save & queue.

8. On the Run pipeline screen, select Save and run.

The job runs twice, one for each version of Node.js you specified in the nodeVersion variable. The Node.js tool installer task downloads the Node.js version if it isn't already on the agent. The Command Line task logs the location of the Node.js version on disk.