How to: Work with release definitions

VSTS | TFS 2018 | TFS 2017 | TFS 2015

This topic shows you how to:

Create a new release definition

  1. Open the Build & Release hub and choose Releases.

  2. Choose the + icon and select Create release definition.

    Creating a new release definition

  3. Select a template or start with an empty definition:

    • If a template is relevant to your scenario, select it to automatically add some tasks and apply typical settings. For example, if you select the Azure App Service Deployment template, you automatically get a task to deploy your app to Azure App Services.

    • If there's no template for your scenario, select Empty process and then add the tasks you need.

    Selecting a template or empty process

  4. Specify the artifacts you want to deploy. Choose the type of source and specify the details such as the project and build definition.

    Selecting the artifacts to deploy

  5. Open the Continuous deployment trigger panel and set the trigger if you want a new release to be created when a new version of the source artifacts are available.

    Setting the continuous deployment trigger

    What's the difference between a release definition and a release?

  6. Check that the environment deployment trigger is set to automatically start a deployment when the release is created. You can also specify other pre-deployment conditions here if required.

    Setting the pre-deployment options

  7. Open the Tasks tab and select the default Run on agent item. In the properties panel, under Agent selection, check that Hosted is selected to use the default queue and agent available in VSTS. If you want to use a different agent that you have previously installed, such as an on-premises agent in TFS, select the agents queue.

    Setting the deployment queue

  8. If required, or if you selected the empty process template, you can now add more tasks and additional environments.

Replicate a definition or environment

If your definition has a pattern that you want to replicate in other definitions, clone it or export it.

Cloning an existing release definition

When you clone a definition, the copy appears in your list of releases. You can save it with a new name.

When you export a definition, you can import it afterwards. Then, if required, modify it and save it with a new name.

Importing an existing release definition

Create and use a template

Create a template for a definition from an environment within the definition by using the old definition editor.

Switching to the previoius release definition editor

Creating a template from an existing release definition

After you create a template, it appears in the Custom tab of the Create release definition wizard. Your team members can use it to follow the pattern in new definitions. For more details, see Environment templates in Release Management.

Use the REST API

Create release definitions using the Release Management REST API.

Add more environments

A release definition, by default, contains a single environment. Configure additional environments in a release definition to represent the target server(s) or locations where you will deploy your app.

  1. Open the + Add list and choose New environment.

    Adding a new environment to a release definition

  2. The template selector panel opens. Follow these steps to configure the new environment.

  3. After you have created and configured your environments, add tasks to them.

You can add environments using the Release Management REST API.

Clone an existing environment

A release definition often contains several environments such as development, testing, QA, and production. Typically, all of these environments are fundamentally similar - and the techniques used to set up and deploy to each one are the same with the exception of minor differences in configuration for each environment and task (such as target URLs, service paths, and server names).

After you have added an environment to a release definition and configured it by adding tasks and setting the properties for each one, clone it to create another environment within the same definition.

You can clone individual environments directly within a definition in the Pipeline tab.

Cloning an existing environment directly

Alternatively, select the environment you want to clone, open the + Add list, and choose Clone environment.

Cloning a selected environment

The cloned environment has the same tasks, task properties, and configuration settings as the original.

Select the cloned environment to open the properties panel, and update the pre-deployment approval, trigger, and queue settings for the cloned environment as required.

Define processes in an environment

The deployment steps in an environment are described using task phases and tasks.

Add tasks

The Tasks tab of the release definition editor shows a list of the task phases and tasks defined for each environment. Open the tasks list for an environment by choosing the "phases and tasks" link in the environment, or by selecting the environment name in the Tasks drop-down list.

Opening the tasks tab

By default, unless you chose the Empty process template when you created your release definition, the definition will contain a Run on agent phase. Add tasks to a phase by choosing the + icon in the phase item to open the Add tasks panel. Select the type of task you need (or choose All), or search for a task by name. When you find the task, choose the Add button that appears when you select the task.

Adding tasks to a phase

A link at the top of the list takes you to Visual Studio Marketplace where you can download and install additional tasks.

You can add tasks specifically for execution on the deployment agent, on a deployment group, or on the server without using an agent by adding the appropriate type of task phase.

Adding a new task phase

For more details, see Environments and Phases in Build and Release Management.

You can add tasks to an environment using the Release Management REST API.

Use task groups

A task group lets you to encapsulate a sequence of tasks already defined in a build or a release definition into a single reusable task that can be added to a build or release definition just like any other task. You can choose to extract the parameters from the encapsulated tasks as configuration variables, and abstract the rest of the task information.

Creating task group context action

For more details, see Task groups.


Release definition concepts

A release definition contains all the tasks and settings used to create a release and deployment to your target machines. To learn more about release definition settings, see:


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


How do I programmatically create a release definition?

Release Management REST API

Do I need an agent?

You need at least one agent to run your build or release. Get an agent.

I can't select a default agent queue and I can't queue my build or release. How do I fix this?

See queues.

I use Team Foundation Server on-premises and I don't see some of these features. Why not?

Some of these features are available only on VSTS and not yet available on-premises. Some features are available on-premises if you have upgraded to the latest version of TFS.

Help and support