Phases

Note

Build and release pipelines are called definitions in TFS 2018 and in older versions. Service connections are called service endpoints in TFS 2018 and in older versions.

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 pipelines 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.

The full syntax to specify an agent phase is:


phases:
- phase: string
  queue:
    name: string
    demands: string | [ string ]
    container: string
    timeoutInMinutes: number
    cancelTimeoutInMinutes: number
    parallel: number
    matrix: { string: { string: string } }
  steps:
    - script: echo Hello world

The above syntax is necessary only if you want to define multiple phases or change the properties for a phase. You can skip the phase syntax if you need only a single phase with the standard options. For example, the following YAML file runs a single phase on the Hosted VS2017 queue.

steps:
- script: echo Hello world

If you want to specify just the queue, you can do that and skip the other properties. For example:

phases:
- phase: Run this job on a Linux agent
  queue: Hosted Linux Preview
  steps:
    ...

Phases can also be defined as templates in a separate file. This allows you to define your logic once and then reuse it in several places. Templates can include parameters which the pipeline definition can vary.

# File: templates/npm.yml

parameters:
  name: ''  # defaults for any parameters that aren't specified
  queue: ''

phases:
- phase: ${{ parameters.name }}
  queue: ${{ parameters.queue }}
  steps:
  - script: npm install
  - script: npm test

When you consume the template in your pipeline, specify values for the template parameters.

# File: .vsts-ci.yml

phases:
- template: templates/npm.yml  # Template reference
  parameters:
    name: macOS
    queue: Hosted macOS Preview

- template: templates/npm.yml  # Template reference
  parameters:
    name: Linux
    queue: Hosted Linux Preview

- template: templates/npm.yml  # Template reference
  parameters:
    name: Windows
    queue: Hosted VS2017

YAML is not yet supported in TFS.

Demands

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

queue:
  name: myPrivateAgents
  demands: agent.os -equals Windows_NT
steps:
- script: echo hello world

Or multiple demands:

queue:
  name: myPrivateAgents
  demands:
  - agent.os -equals Darwin
  - anotherCapability -equals somethingElse
steps:
- script: echo hello world

YAML is not yet supported in TFS.

Learn more about build and release agent capabilities.

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 forever (except in hosted pools, where they will be forcibly stopped).

The timeoutInMinutes allows a limit to be set for the job execution time. When not specified, the default is 60 minutes. The cancelTimeoutInMinutes allows a limit to be set for the job cancel time. When not specified, the default is 5 minutes.

queue:
  timeoutInMinutes: number
  cancelTimeoutInMinutes: number

YAML is not yet supported in TFS.

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 pipeline 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 pipeline 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 pipeline or in an environment of a release pipeline to run a set of tests in parallel - once for each test configuration.

The matrix setting enables a phase to be dispatched multiple times, with different variable sets. The parallel tag restricts the amount of parallelism. The following phase will be dispatched three times with the values of Location and Browser set as specified. However, only two jobs will run in parallel at a time.

phases:
- phase: Test
  queue:
    parallel: 2
    matrix: 
      US_IE:
        Location: US
        Browser: IE
      US_Chrome:
        Location: US
        Browser: Chrome
      Europe_Chrome:
        Location: Europe
        Browser: Chrome

YAML is not yet supported in TFS.

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.

When parallel is specified and matrix is not defined, the setting indicates how many jobs to dispatch. Variables System.JobPositionInPhase and System.TotalJobsInPhase are added to each job. The variables can then be used within your scripts to divide work among the jobs. See Parallel and multiple execution using agent phases.

phases:
- phase: Test
  queue:
    parallel: 2

YAML is not yet supported in TFS.

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.

Here is an example of defining variables in a phase and using them within tasks.

variables:
  mySimpleVar: simple var value
  "my.dotted.var": dotted var value
  "my var with spaces": var with spaces value

steps:
- script: echo Input macro = $(mySimpleVar). Env var = %MYSIMPLEVAR%
  condition: eq(variables['agent.os'], 'Windows_NT')
- script: echo Input macro = $(mySimpleVar). Env var = $MYSIMPLEVAR
  condition: in(variables['agent.os'], 'Darwin', 'Linux')
- bash: echo Input macro = $(my.dotted.var). Env var = $MY_DOTTED_VAR
- powershell: Write-Host "Input macro = $(my var with spaces). Env var = $env:MY_VAR_WITH_SPACES"

YAML is not yet supported in TFS.

Artifact download

These options are not available in YAML.

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.

OAuth token is always made available to the scripts that run through YAML. Here is an example:

steps:
- powershell: |
    $url = "$($env:SYSTEM_TEAMFOUNDATIONCOLLECTIONURI)$env:SYSTEM_TEAMPROJECTID/_apis/build/definitions/$($env:SYSTEM_DEFINITIONID)?api-version=4.1-preview"
    Write-Host "URL: $url"
    $pipeline = Invoke-RestMethod -Uri $url -Headers @{
      Authorization = "Bearer $env:TOKEN"
    }
    Write-Host "Pipeline = $($definition | ConvertTo-Json -Depth 100)"
  env:
    TOKEN: $(system.accesstoken)

YAML is not yet supported in TFS.