Task types & usage
Azure Pipelines | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018 - TFS 2015
Note
In Microsoft Team Foundation Server (TFS) 2018 and previous versions, build and release pipelines are called definitions, runs are called builds, service connections are called service endpoints, stages are called environments, and jobs are called phases.
A task is the building block for defining automation in a pipeline. A task is simply a packaged script or procedure that has been abstracted with a set of inputs.
When you add a task to your pipeline, it may also add a set of demands to the pipeline. The demands define the prerequisites that must be installed on the agent for the task to run. When you run the build or deployment, an agent that meets these demands will be chosen.
When you run a job, all the tasks are run in sequence, one after the other. To run the same set of tasks in parallel on multiple agents, or to run some tasks without using an agent, see jobs.
By default, all tasks run in the same context, whether that's on the host or in a job container. You may optionally use step targets to control context for an individual task.
Learn more about how to specify properties for a task with the YAML schema.
When you run a job, all the tasks are run in sequence, one after the other, on an agent. To run the same set of tasks in parallel on multiple agents, or to run some tasks without using an agent, see jobs.
Custom tasks
We provide some built-in tasks to enable fundamental build and deployment scenarios. We have also provided guidance for creating your own custom task.
In addition, Visual Studio Marketplace offers a number of extensions; each of which, when installed to your subscription or collection, extends the task catalog with one or more tasks. Furthermore, you can write your own custom extensions to add tasks to Azure Pipelines or TFS.
In YAML pipelines, you refer to tasks by name. If a name matches both an in-box task and a custom task, the in-box task will take precedence. You can use the task GUID or a fully-qualified name for the custom task to avoid this risk:
steps:
- task: myPublisherId.myExtensionId.myContributionId.myTaskName@1 #format example
- task: qetza.replacetokens.replacetokens-task.replacetokens@3 #working example
To find myPublisherId
and myExtensionId
, select Get on a task in the marketplace. The values after the itemName
in your URL string are myPublisherId
and myExtensionId
. You can also find the fully-qualified name by adding the task to a Release pipeline and selecting View YAML when editing the task.
Task versions
Tasks are versioned, and you must specify the major version of the task used in your pipeline. This can help to prevent issues when new versions of a task are released. Tasks are typically backwards compatible, but in some scenarios you may encounter unpredictable errors when a task is automatically updated.
When a new minor version is released (for example, 1.2 to 1.3), your build or release will automatically use the new version. However, if a new major version is released (for example 2.0), your build or release will continue to use the major version you specified until you edit the pipeline and manually change to the new major version. The build or release log will include an alert that a new major version is available.
You can set which minor version gets used by specifying the full version number of a task after the @
sign (example: GoTool@0.3.1
). You can only use task versions that exist for your organization.
In YAML, you specify the major version using @
in the task name.
For example, to pin to version 2 of the PublishTestResults
task:
steps:
- task: PublishTestResults@2
YAML pipelines aren't available in TFS.
Task control options
Each task offers you some Control Options.
Control options are available as keys on the task
section.
- task: string # reference to a task and version, e.g. "VSBuild@1"
condition: expression # see below
continueOnError: boolean # 'true' if future steps should run even if this step fails; defaults to 'false'
enabled: boolean # whether or not to run this step; defaults to 'true'
timeoutInMinutes: number # how long to wait before timing out the task
target: string # 'host' or the name of a container resource to target
The timeout period begins when the task starts running. It does not include the time the task is queued or is waiting for an agent.
In this YAML, PublishTestResults@2
will run even if the previous step fails because of the succeededOrFailed() condition.
steps:
- task: UsePythonVersion@0
inputs:
versionSpec: '3.7'
architecture: 'x64'
- task: PublishTestResults@2
inputs:
testResultsFiles: "**/TEST-*.xml"
condition: succeededOrFailed()
Note
For the full schema, see YAML schema for task
.
Conditions
Only when all previous dependencies have succeeded. This is the default if there is not a condition set in the YAML.
Even if a previous dependency has failed, unless the run was canceled. Use
succeededOrFailed()
in the YAML for this condition.Even if a previous dependency has failed, even if the run was canceled. Use
always()
in the YAML for this condition.Only when a previous dependency has failed. Use
failed()
in the YAML for this condition.
- Custom conditions which are composed of expressions
Step target
Tasks run in an execution context, which is either the agent host or a container.
An individual step may override its context by specifying a target
.
Available options are the word host
to target the agent host plus any containers defined in the pipeline.
For example:
resources:
containers:
- container: pycontainer
image: python:3.8
steps:
- task: SampleTask@1
target: host
- task: AnotherTask@1
target: pycontainer
Here, the SampleTask
runs on the host and AnotherTask
runs in a container.
YAML pipelines aren't available in TFS.
Build tool installers (Azure Pipelines)
Tool installers enable your build pipeline to install and control your dependencies. Specifically, you can:
Install a tool or runtime on the fly (even on Microsoft-hosted agents) just in time for your CI build.
Validate your app or library against multiple versions of a dependency such as Node.js.
For example, you can set up your build pipeline to run and validate your app for multiple versions of Node.js.
Example: Test and validate your app on multiple versions of Node.js
Tip
Want a visual walkthrough? See our April 19 news release.
Create an azure-pipelines.yml file in your project's base directory with the following contents.
pool:
vmImage: 'Ubuntu 16.04'
steps:
# Node install
- task: NodeTool@0
displayName: Node install
inputs:
versionSpec: '6.x' # The version we're installing
# Write the installed version to the command line
- script: which node
Create a new build pipeline and run it. Observe how the build is run. The Node.js Tool Installer downloads the Node.js version if it is not already on the agent. The Command Line script logs the location of the Node.js version on disk.
YAML pipelines aren't available in TFS.
Tool installer tasks
For a list of our tool installer tasks, see Tool installer tasks.
Disabling in-box and Marketplace tasks
On the organization settings page, you can disable Marketplace tasks, in-box tasks, or both.
Disabling Marketplace tasks can help increase security of your pipelines.
If you disable both in-box and Marketplace tasks, only tasks you install using tfx
will be available.
Related articles
Help and support
- See our troubleshooting page
- Get advice on Stack Overflow, and feel free to post your questions, search for answers, or suggest a feature on our Azure DevOps Developer Community. Support page.