Configure run or build numbers

Note

In Microsoft Team Foundation Server (TFS) 2018 and previous versions, run and release pipelines are called definitions, runs are called builds, service connections are called service endpoints, stages are called environments, and jobs are called phases.

You can customize how your pipeline runs are numbered. The default value for run number is $(Date:yyyyMMdd).$(Rev:r).

In YAML, this property is called name. If not specified, your run is given a unique integer as its name. You can give runs 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 a run is started:

  • Project name: Fabrikam

  • Pipeline name: CIBuild

  • Branch: master

  • Build ID/Run ID: 752

  • Date: May 5, 2019.

  • Time: 9:07:03 PM.

  • One run completed earlier today.

If you specify this build number format:

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

Then the second run on this day would be named: Fabrikam_CIBuild_master_20190505.2

Tokens

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

Token Example replacement value
$(BuildDefinitionName) CIBuild

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

$(BuildID) is an internal immutable ID that is also referred to as the Run ID. It is unique across the organization.
$(DayOfMonth) 5
$(DayOfYear) 217
$(Hours) 21
$(Minutes) 7
$(Month) 8
$(Rev:r) 2 (The third run 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 number. For example, if you've defined My.Variable, you could specify the following 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.

Q & A

How large can a run number be?

Runs may be up to 255 characters.

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

The time zone is UTC.

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.

How can you reference the run number variable within a script?

The run number variable can be called with $(Build.BuildNumber). You can define a new variable that includes the run number or call the run number directly. In this example, $(MyRunNumber) is a new variable that includes the run number.

# Set MyRunNumber
variables: 
  MyRunNumber: '1.0.0-CI-$(Build.BuildNumber)'


steps:
- script: echo $(MyRunNumber) # display MyRunNumber
- script: echo $(Build.BuildNumber) #display Run Number