You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Azure Pipelines assigns a unique run number (also called a build number) to each pipeline execution. You can customize these numbers to make them more meaningful for your team, using variables, tokens, and naming patterns.
14
+
Azure Pipelines assigns a unique run number, also called a build number, to identify each execution of a pipeline or build. This article explains the structure of these numbers and how you can customize them to be more meaningful for your team.
15
15
16
-
The run number is used to identify a specific execution of a pipeline or build. The build number is synonymous with the run number.
17
-
18
-
If you don't specify a build name in YAML pipelines, or you leave the **Name** field blank in Classic pipelines, your run gets a unique integer as its name. You can give runs more useful names that are meaningful to your team. You can use a combination of tokens, variables, and underscore characters in build names.
16
+
If you don't specify a build name in YAML pipelines, or you leave the **Build number format** field blank in Classic pipelines, each run gets a unique integer as its name. You can use a combination of naming patterns, tokens, and variables to give runs more useful names.
19
17
20
18
::: moniker range=">=azure-devops-2020"
21
19
22
-
You can only customize the run number at the root level of your pipeline using the `name` property. Set the `name` property at the [pipeline](/azure/devops/pipelines/yaml-schema/pipeline) level. The `name` property isn't supported in templates or stages.
20
+
## Customize the name property
21
+
22
+
In Classic pipelines, you can customize the **Build number format** under **Options** in the pipeline definition. In YAML pipelines, you can customize the run number by using the `name` property at the [pipeline](/azure/devops/pipelines/yaml-schema/pipeline) level. The `name` property isn't supported in templates or stages.
23
23
24
-
The following code sets a custom run number format like `project_def_main_202408281`:
24
+
The following YAML pipeline example sets a custom run number format like **project_def_main_202408281**:
The default value for a run number in Azure Pipelines is `$(Date:yyyyMMdd).$(Rev:r)`. `$(Rev:r)` is a special variable format that only works in the build number field. When a build completes, if nothing else in the build number changed, the `Rev` integer value increases by one.
37
+
The default value for an Azure Pipelines run number is `$(Date:yyyyMMdd).$(Rev:r)`. The `$(Rev:r)` is a special variable that works only in the build number field. When a build completes, if nothing else in the build number changed, the `Rev` integer value increases by one.
38
38
39
39
`$(Rev:r)`resets to `1` when any other part of the build number changes. For example, if you configure your build number format as `$(Build.DefinitionName)_$(Date:yyyyMMdd).$(Rev:r)`, the build number resets when the date changes.
40
40
41
-
If the previous build number was `MyBuild_20230621.1`, the next build number that day is `MyBuild_20230621.2`. The first build number the next day is `MyBuild_20230622.1`.
42
-
43
-
`$(Rev:r)`also resets to `1` if you change the build number to indicate a version change. For example, if your build format is `1.0.$(Rev:r)` and your last build number was `1.0.3`, if you change the build number to `1.1.$(Rev:r)`, the next build number is `1.1.1`.
41
+
If the previous build number was **MyBuild_20230621.1**, the next build number that day is **MyBuild_20230621.2**. The first build number the next day is **MyBuild_20230622.1**.
44
42
45
-
## Example
43
+
`$(Rev:r)`also resets to `1` if you change the version. If your build format is `1.0.$(Rev:r)` and your last build number was **1.0.3**, if you change the version to `1.1.$(Rev:r)`, the next build number is **1.1.1**.
46
44
47
-
Consider the following data for a build run:
45
+
For example, if you specify the build number format `$(TeamProject)_$(Build.DefinitionName)_$(SourceBranchName)_$(Date:yyyyMMdd).$(Rev:r)`, the second run on May 6, 2024 is named **Fabrikam_CIBuild_main_20240506.2**.
48
46
49
-
- Project name: Fabrikam
50
-
- Pipeline name: CIBuild
51
-
- Branch: main
52
-
- Build ID/Run ID: 752
53
-
- Date: May 6, 2024
54
-
- Time: 9:07:03 PM
55
-
- One run completed earlier today.
47
+
The build number tokens resolve as follows:
56
48
57
-
If you specify the following build number format, the second run on May 6, 2024 is named **Fabrikam_CIBuild_main_20240506.2**.
The following table shows how each token resolves, based on the previous example. You can use these tokens only to define run numbers. They don't work anywhere else in a pipeline.
58
+
The following table shows how run number tokens resolve. You can use these tokens only to define run numbers. They don't work anywhere else in a pipeline.
66
59
67
60
| Token | Example value | Notes |
68
61
| ----- | -------------- | ----------- |
69
-
| `$(Build.DefinitionName)` | CIBuild | The pipeline name can't contain invalid or whitespace characters.|
70
-
| `$(Build.BuildId)` | 752 | `$(Build.BuildId)` is an internal, immutable ID, also called the Run ID, that is unique across the Azure DevOps organization.|
| `$(Build.BuildId)` | 752 | An internal, immutable ID, also called the `Run ID`, that's unique in the Azure DevOps organization.|
64
+
| `$(Date:yyyyMMdd)` | 20240506 | A date format. You can also specify other date formats, such as `$(Date:MMddyy)`. |
71
65
| `$(DayOfMonth)` | 6 ||
72
66
| `$(DayOfYear)` | 126 ||
73
67
| `$(Hours)` | 21 ||
74
68
| `$(Minutes)` | 7 ||
75
69
| `$(Month)` | 5 ||
76
-
| `$(Rev:r)` | 2 | The third daily run is `3`, and so on. Use `$(Rev:r)` to ensure that every completed build has a unique name. |
77
-
| `$(Date:yyyyMMdd)` | 20240506 | You can specify other date formats such as `$(Date:MMddyy)`. |
70
+
| `$(Rev:r)` | 2 | Number of runs that day. Use `$(Rev:r)` to ensure that every completed build has a unique name. |
78
71
| `$(Seconds)` | 3 ||
79
72
| `$(SourceBranchName)` | main ||
80
73
| `$(TeamProject)` | Fabrikam ||
@@ -84,21 +77,21 @@ The following table shows how each token resolves, based on the previous example
84
77
>[!IMPORTANT]
85
78
>If you want to show prefix zeros in the run number, you can add more `r` characters to the `Rev` token. For example, specify `$(Rev:rr)` if you want the `Rev` number to begin with `01`, `02`, and so on.
86
79
>
87
-
>If you use a zero-padded `Rev` as part of a version numbering scheme, some pipeline tasks or popular tools, like NuGet packages, remove the leading zeros. This behavior causes a version number mismatch in the artifacts that are produced.
80
+
>However, if you use a zero-padded `Rev` as part of a version numbering scheme, some pipeline tasks or popular tools like NuGet packages remove the leading zeros. This behavior causes a version number mismatch in the artifacts that the build produces.
88
81
89
-
## Expressions
82
+
### Expressions
90
83
91
-
If you use an expression to set the build number, you can't use some tokens, because their values aren't set at the time expressions are evaluated. These tokens include `$(Build.BuildId)`, `$(Build.BuildURL)`, and `$(Build.BuildNumber)`.
84
+
If you use an expression to set the build number, you can't use `$(Build.BuildId)`, `$(Build.BuildUri)`, or `$(Build.BuildNumber)` tokens, because their values aren't set at the time pipeline expressions are evaluated.
92
85
93
-
## Variables
86
+
### Variables
94
87
95
-
You can use user-defined and predefined variables in your build number. For example, if you define `My.Variable`, you can specify the following number format:
88
+
You can use both predefined and user-defined variables in your build number. For example, if you define `My.Variable`, you can specify the following number format. The first four variables are predefined.
In the preceding example, the first four variables are predefined. For information on how to define user variables, see [Set variables in pipelines](variables.md#set-variables-in-pipeline).
94
+
For more information about predefined variables, see [Use predefined variables](../build/variables.md). For information on how to define user variables, see [Define variables](variables.md).
102
95
103
96
## FAQ
104
97
@@ -118,15 +111,15 @@ The time zone is UTC.
118
111
119
112
::: moniker range="<azure-devops"
120
113
121
-
The time zone is the same as the time zone of the operating system of the machine that runs your application tier server.
114
+
The time zone is the same as the operating system of the machine that runs your application tier server.
122
115
123
116
::: moniker-end
124
117
125
118
::: moniker range=">=azure-devops-2020"
126
119
127
120
### How can I set the build number dynamically with conditions?
128
121
129
-
You can use variables as part of your run number. In the following example, the variable `why` is used as part of the run number, and its value changes depending on the `Build.Reason`.
122
+
You can use variables as part of your run number. In the following example, the variable `why` is set as part of the run number, and its value changes depending on the `Build.Reason`.
130
123
131
124
```yaml
132
125
variables:
@@ -151,7 +144,7 @@ steps:
151
144
152
145
### How can I reference the run number variable within a script?
153
146
154
-
You can reference the run number directly as `$(Build.BuildNumber)` in your scripts, or create a custom variable that includes it. For example:
147
+
You can reference the run number directly as `$(Build.BuildNumber)` in your scripts, or create a custom variable that includes the number. For example:
0 commit comments