Build pipeline options

Azure Pipelines | TFS 2018 | TFS 2017 | TFS 2015

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.

Here we explain settings you can change on the build pipeline Options tab.

Description

Team Foundation Server (TFS) 2017.1 and older

This section is available under General tab.

If you specify a description here, it is shown near the name of the build pipeline when you select it in the Build area of your project.

Build number format

In YAML, this property is called name. If not specified, your completed build is given a unique integer as its name. You can give completed builds much more useful names that are meaningful to your team. You can use a combination of tokens, variables, and underscore characters.

name: $(TeamProject)_$(BuildDefinitionName)_$(SourceBranchName)_$(Date:yyyyMMdd)$(Rev:.r)
steps:
- script: echo hello world

YAML builds are not yet available on TFS.

Example

At the time the build is queued:

  • Project name: Fabrikam

  • Build pipeline name: CIBuild

  • Branch: master

  • Build ID: 752

  • Date: August 5, 2009.

  • Time: 9:07:03 PM.

  • The build ran once earlier today.

If you specify this build number format:

$(TeamProject)_$(BuildDefinitionName)_$(SourceBranchName)_$(Date:yyyyMMdd)$(Rev:.r)

Then the second completed build on this day would be named: Fabrikam_CIBuild_master_20090805.2

Tokens

The following table shows how each token is resolved based on the previous example.

Token Example replacement value
$(BuildDefinitionName) CIBuild

Note: The build pipeline name must not contain invalid or whitespace characters.
$(BuildID) 752

$(BuildID) is an internal immutable ID.
$(DayOfMonth) 5
$(DayOfYear) 217
$(Hours) 21
$(Minutes) 7
$(Month) 8
$(Rev:.r) 2 (The third build on this day will be 3, and so on.)

Use $(Rev:.r) to ensure that every completed build has a unique name. When a build is completed, if nothing else in the build number has changed, the Rev integer value is incremented by one.

If you want to show prefix zeros in the number, you can add additional 'r' characters. For example, specify $(rev:.rr) if you want the Rev number to begin with 01, 02, and so on.
$(Date:yyyyMMdd) 20090824

You can specify other date formats such as $(Date:MMddyy)
$(Seconds) 3
$(SourceBranchName) master
$(TeamProject) Fabrikam
$(Year:yy) 09
$(Year:yyyy) 2009

Variables

You can also use user-defined and predefined variables that have a scope of "All" in your build number format. For example, if you've defined My.Variable, you could specify the following build number format:

$(Build.DefinitionName)_$(Build.DefinitionVersion)_$(Build.RequestedFor)_$(Build.BuildId)_$(My.Variable)

The first four variables are predefined. My.Variable is defined by you on the variables tab.

Badge enabled

TFS 2017.1 and older

This section is available under General tab.

Select if you want to show the latest outcome of this build on external web sites.

  1. Select the Badge enabled check box.

  2. Save the pipeline.

  3. When the Show url link appears, click it and copy the URL to your clipboard.

  4. Use the URL as the source of an image in the HTML of the page of the external web site. For example: <img src="{URL you copied from the link}"/>

Create a work item on failure

If the build pipeline fails, you can automatically create a work item to track getting the problem fixed. You can specify the work item type.

You can also select if you want to assign the work item to the requestor. For example, if this is a CI build, and a team member checks in some code that breaks the build, then the work item is assigned to that person.

Additional Fields: You can set the value of work item fields. For example:

Field Value
System.Title Build $(Build.BuildNumber) failed
System.Reason Build failure

Q: What other work item fields can I set? A: Work item field index

Allow scripts to access the OAuth token

Select this check box if you want to enable your script to use the build pipeline OAuth token.

For an example, see Use a script to customize your build pipeline.

Default agent pool

TFS 2017.1 and older

This section is available under General tab.

Select the pool that's attached to the pool that contains the agents you want to run this pipeline.

Tip: If your code is in Azure Pipelines and you run your builds on Windows, in many cases the simplest option is to use the Hosted pool.

Build job authorization scope

TFS 2017.1 and older

This section is available under General tab.

Specify the authorization scope for a build job. Select:

  • Project Collection if the build needs access to multiple projects.

  • Current Project if you want to restrict this build to have access only the resources in the current project.

Build job timeout in minutes

TFS 2017.1 and older

This section is available under General tab.

Specify the maximum time a build job is allowed to execute on an agent before being canceled by the server. Leave it empty or at zero if you want the job to never be canceled by the server.

Build job cancel timeout in minutes

Specify the maximum time a build job is allowed to respond after the a user cancels the build. You can specify a value from 1 to 60 minutes.

Set this value to allow sufficient time for tasks to complete in cases where you've specified to Run this task as Even if a previous task has failed, even if the build was cancelled or as Custom conditions that allow a task to always run after cancellation.

Whatever value you set here, the Build job timeout in minutes limit still applies. For example:

  • Build job timeout in minutes = 30

  • Build job cancel timeout in minutes = 15

  • A user clicks Cancel after the build has run for 25 minutes.

  • The build is given 5 minutes to cancel instead of the 15 you specified.

Note

The system typically consumes about 10 seconds of this time allotment for messaging before your tasks run.

Demands

TFS 2017.1 and older

This section is available under General tab.

Use demands to make sure that the capabilities your build needs are present on the build agents that run it. Demands are asserted automatically by build tasks or manually by you.

Build task demands

Some build tasks won't run unless one or more demands are met by the build agent. For example, the Visual Studio Build task demands that msbuild and visualstudio are installed on the build agent. If your build includes tasks that have demands, they are listed first.

Manually entered demands

You might need to use on-premises build agents with special capabilities. For example, your build pipeline requires SpecialSoftware.

Add the demand to your build pipeline.

Name Type
SpecialSoftware exists

Register each build agent that has the capability.

  1. Go to the Agent pools tab at the root of the control panel:

    • Azure Pipelines: https://dev.azure.com/{your_organization}/_admin/_AgentPool
    • TFS 2018: https://{your_server}/DefaultCollection/_admin/_AgentPool
    • TFS 2017: https://{your_server}/tfs/DefaultCollection/_admin/_AgentPool
    • TFS 2015: http://{your_server}:8080/tfs/_admin/_AgentPool

    The TFS URL doesn't work for me. How can I get the correct URL?

  2. Click the agent, and then click Capabilities

  3. Add something like the following entry:

First box Second box
SpecialSoftware C:\Program Files (x86)\SpecialSoftware

Tip: When you manually queue a build you can change the demands for that run.

Multi-configuration

Select this option to build multiple configurations. For example, you could build a C++ app for both debug and release configurations on both x86 and x64 platforms. In Azure Pipelines and TFS 2018, you set this option in the Tasks tab for each Job in your pipeline (not in the Options tab). To learn about multi-configuration, see the example Build your C++ app for Windows.

Q & A

In what time zone are the build number time values expressed?

If you are using Azure Pipelines, then the time zone is UTC.

If you are using an on-premises Team Foundation Server, then the time zone is the same as the time zone of the operating system of the machine where you are running your application tier server.

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 pool and I can't queue my build or release. How do I fix this?

See Agent pools.

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

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