General build definition settings

Last Update: 4/11/2017

Team Services | TFS 2017 | TFS 2015 | Previous versions (XAML builds)

If you're using the New Build Editor, then these settings are found on the Options tab.

Default agent queue

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

Tip: If your code is in Visual Studio Team Services (Team Services) and you run your builds on Windows, in many cases the simplest option is use the Hosted pool.

Build job authorization scope

Specify the authorization scope for a build job. Select:

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

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


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

Build number format

If you leave it blank, your completed build is given a unique integer as its name. But 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.


At the time the build is queued:

  • Team project name: Fabrikam

  • Build definition 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:


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


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


Example replacement value



Note: The build definition name must not contain invalid characters, including whitespace.



$(BuildID) is an internal immutable ID.












2 (The third build on this day will be 3, and so on.)

Use $(Rev:.rr) 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.



You can specify other date formats such as $(Date:MMddyy)












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:


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

Build job timeout in minutes

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 (Team Services only)

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 will be given 5 minutes to cancel instead of the 15 you specified.


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

Badge enabled

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

  3. When he 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}/>


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 steps or manually by you.

Build step demands

Some build steps won't run unless one or more demands are met by the build agent. For example, the Visual Studio Build step demands that msbuild and visualstudio are installed on the build agent. If your build includes steps 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 process requires SpecialSoftware.

Add the demand to your build definition.

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:

    • Team Services: https://{your_account}
    • 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.


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

If you are using Team Services, 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 a build agent?

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

I can't select a default agent queue and I can't queue my build. 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 Visual Studio Team Services and not yet available on-premises. Some features are available on-premises if you have upgraded to the latest version of TFS.