Phases

You can organize your build or deployment process into phases. Every build or deployment process has at least one phase.

Note

You must install TFS 2018.2 to use phases in build processes. In TFS 2018 RTM you can use phases in release management deployment processes.

You can organize your deployment process into phases. Every deployment process has at least one phase.

A phase is a series of tasks that run sequentially on the same target. At design time in your phase you specify a series of tasks that you want to run on a common target. At run time (when either the build or release process is triggered), each phase is dispatched as one or more jobs to its target.

Note

You must install Update 2 to use phases in TFS 2017, and they are available only in release management deployment processes. Phases in build definitions are available in VSTS, TFS 2018.2, and newer versions.

In a build process, the most common target is an agent. The other kind of target is the VSTS server.

In a build process, the most common target is an agent. The other kind of target is the server (your TFS instance).

In a deployment process, the target can be either an agent, a deployment group, or the server.

When the target is an agent, the tasks are run on the computer that hosts the agent.

When you create a new definition, it starts with a single agent phase. The properties for the agent phase are displayed when you select the agent phase in the editor.

Demands

Use demands to specify what capabilities an agent must have to run jobs from your phase.

You have the option to specify demands in the definition, in the phases, or both. If you specify demands in both the definition and in a phase, the union of the two sets of demands is required for the system to select an agent.

Learn more about build and release agent capabilities.

Container image

If you are using YAML, you can specify a Docker container to use for your agent phase.

Containers are not yet supported in the web editor.

Timeouts

To avoid hanging up your resources when your process is hung or waiting too long, it's a good idea to set a limit on how long your process is allowed to run. Use the phase timeout setting to specify the limit in minutes for jobs run by this phase. A zero value means that the jobs will run for an effectively unlimited amount of time.

Select the phase and then specify the timeout value.

On the Options tab you can specify default values for all phases in the definition. If you specify a non-zero value for the phase timeout, then it overrides any value that is specified in the definition options. If you specify a zero value, then the timeout value from the definition options is used. If the definition value is also set to zero, then there is no timeout.

Jobs targeting Microsoft-hosted agents have additional restrictions on how long they may run.

You can also set the timeout for each task individually - see task control options.

Multi-configuration

From a single phase you can run multiple jobs and multiple agents in parallel. Some examples include:

  • Multi-configuration builds: An agent phase can be used in a build definition to build multiple configurations in parallel. For example, you could build a Visual C++ app for both debug and release configurations on both x86 and x64 platforms. To learn more, see Visual Studio Build - multiple configurations for multiple platforms.

  • Multi-configuration deployments: An agent phase can be used in an environment of a release definition to run multiple deployment jobs in parallel, for example, to different geographic regions.

  • Multi-configuration testing: An agent phase can be used in a build definition or in an environment of a release definition to run a set of tests in parallel - once for each test configuration.

To run multiple jobs using multi-configuration option, you identify a variable named a multiplier, and specify a list of values for that multiplier. A separate job is run for each value in the list. To use multipliers for build or deployment, you must:

  • Define one or more variables on the Variables tab of the definition or in a variable group. Each variable, known in this context as a multiplier variable, must be defined as a comma-delimited list of the values you want to pass individually to the agents.

  • Enter the name of the multiplier variable, without the $ and parentheses, as the value of the Multipliers parameter.

  • If you want to execute the phase for more than one multiplier variable, enter the variable names as a comma-delimited list - omitting the $ and parentheses for each one.

  • If you want to limit the number of agents used during the deployment to a number less than you have configured for your account, enter that value as the Maximum number of agents parameter.

For example, you might define two variables named Location and Browser as follows::

  • Location = US,Europe
  • Browser = IE,Chrome,Edge,Firefox

The following configuration will execute the deployment eight times using a maximum of four agents at any one time:

  • Multipliers = Location,Browser
  • Maximum number of agents = 4

With multi-configuration you can run multiple jobs, each with a different value for one or more variables (multipliers). If you want to run the same job on multiple agents, then you can use multi-agent option of parallelism. The test slicing example above can be accomplished through multi-agent option.

Slicing

An agent phase can be used to run a suite of tests in parallel. For example, you can run a large suite of 1000 tests on a single agent. Or, you can use two agents and run 500 tests on each one in parallel. To leverage slicing, the tasks in the phase should be smart enough to understand the slice they belong to. The Visual Studio Test task is one such task that supports test slicing. If you have installed multiple agents, you can specify how the Visual Studio Test task will run in parallel on these agents. Variables System.SliceNumber and System.SliceCount are added to each job.

Specify the multi-agent option on an agent phase to leverage slicing. The job is dispatched as many times as the number of agents you specify, and the variables System.SliceNumber and System.SliceCount are automatically set in each job.

Phase variables

If you are using YAML, variables can be specified on the phase. The variables can be passed to task inputs using the macro syntax $(variableName), or accessed within a script using the environment variable.

Phase variables are not yet supported in the web editor.

Artifact download

In a release definition, you may choose to skip the download of artifacts during the job execution. Use this option if you want to implement your own custom logic for downloading artifacts by using tasks, or if the tasks in a particular phase do not rely on the artifacts.

Alternatively, You can choose to download specific artifacts during the job execution in a release. Use this option if the tasks in a particular phase rely on only specific artifacts.

Access to OAuth token

You can allow tasks running in this phase to access current VSTS or TFS OAuth security token. The token can be use to authenticate to the VSTS REST API.

Select the Allow scripts to access OAuth token option in the control options for the phase.