TFS 2018 task reference

A task performs an action in a pipeline. For example, a task can build an app, interact with Azure resources, install a tool, or run a test. Tasks are the building blocks for defining automation in a pipeline.

The articles in this section describe the built-in tasks for Azure Pipelines and specify the semantics for attributes that hold special meaning for each task.

For previous versions of the task reference, see:

• TFS 2017 task reference
• TFS 2015 task reference

For how-tos and tutorials about authoring pipelines using tasks, including creating custom tasks, custom extensions, and finding tasks on the Visual Studio Marketplace, see Tasks concepts and Azure Pipelines documentation.

Build tasks

Deploy tasks

Package tasks

Test tasks

Tool tasks

Utility tasks

Open source

These tasks are open source on GitHub. Feedback and contributions are welcome. See Pipeline task changelog for a list of task changes, including a historical record of task updates.

FAQ

What are task input aliases?

Inputs to a task are identified by a label, name, and may include one or more optional aliases. The following example is an excerpt from the source code for the Known Hosts Entry input of the InstallSSHKey@0 task.

{
    "name": "hostName",
    "aliases": [
        "knownHostsEntry"
    ],
    "label": "Known Hosts Entry"
    ...
}

Before YAML pipelines were introduced in 2019, pipelines were created and edited using a UI based pipeline editor, and only the label was used by pipeline authors to reference a task input.

When YAML pipelines were introduced in 2019, pipeline authors using YAML started using the task input name to refer to a task input. In some cases, the task input names weren't descriptive, so aliases were added to provide additional descriptive names for task inputs.

For example, the InstallSSHKey@0 task has a Known Hosts Entry input named hostName that expects an entry from a known_hosts file. The Known Hosts Entry label in the classic pipeline designer makes this clear, but it isn't as clear when using the hostName name in a YAML pipeline. Task input aliases were introduced to allow task authors to provide decriptive names for their previously authored tasks, and for the InstallSSHKey@0 task, a knownHostsEntry alias was added, while keeping the original hostName name for compatibility with existing pipelines using that name.

Any items in a task input's aliases are interchangeable with the name in a YAML pipeline. The following two YAML snippets are functionally identical, with the first example using the knownHostsEntry alias and the second example using hostName.

- task: InstallSSHKey@0
  inputs:
    # Using knownHostsEntry alias
    knownHostsEntry: 'sample known hosts entry line'
    # Remainder of task inputs omitted

- task: InstallSSHKey@0
  inputs:
    # Using hostName name
    hostName: 'sample known hosts entry line'
    # Remainder of task inputs omitted

Starting with Azure DevOps Server 2019.1, the YAML pipeline editor was introduced, which provides an intellisense type functionality.

The YAML pipeline editor uses the Yamlschema - Get REST API to retrieve the schema used for validation in the editor. If a task input has an alias, the schema promotes the alias to the primary YAML name for the task input, and the alias is suggested by the intellisense.

The following example is the Known Hosts Entry task input for the InstallSSHKey@0 task from the YAML schema, with knownHostsEntry listed in the name position and hostName in the aliases collection.

"properties": {
    "knownHostsEntry": {
      "type": "string",
      "description": "Known Hosts Entry",
      "ignoreCase": "key",
      "aliases": [
        "hostName"
      ]
    },

Because the intellisense in the YAML pipeline editor displays knownHostsEntry, and the YAML generated by the task assistant uses knownHostsEntry in the generated YAML, the task reference displays the alias from the task source code as the YAML name for a task input. If a task has more than one alias (there are a few that have two aliases), the first alias is used as the name.

Why did the task reference change?

The Azure Pipelines tasks reference documentation moved to its current location to support the following improvements.

• Task articles are generated using the task source code from the Azure Pipelines tasks open source repository.
• Task input names and aliases are generated from the task source so they are always up to date.
• YAML syntax blocks are generated from the task source so they are up to date.
• Supports community contributions with integrated user content such as enhanced task input descriptions, remarks and examples.
• Provides task coverage for all supported Azure DevOps versions.
• Updated every sprint to cover the latest updates.

To contribute, see Contributing to the tasks content.

Where can I learn step-by-step how to build my app?

Build your app

Can I add my own build tasks?

Yes: Add a build task

What are installer tasks?

To learn more about tool installer tasks, see Tool installers.