运行和生成编号
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
本文介绍如何构造 Azure Pipelines 内部版本号和运行编号,以及如何在管道中自定义它们。
运行编号用于标识管道或生成的特定执行。 内部版本号是运行编号的同义词。
如果未在 YAML 管道中指定生成名称,或者在经典管道中将 Name 字段留空,则运行将获取一个唯一的整数作为其名称。 你可以为运行提供对团队有意义的更有用的名称。 可以在生成名称中使用标记、变量和下划线字符的组合。
在 YAML 管道中,调用 name
生成名称属性,并且必须位于管道的根级别。 在 YAML 文件的根级别指定的项目是管道属性。
注意
属性 name
在模板文件中不起作用。
以下示例代码输出自定义的内部版本号,如 project_def_master_20240828.1。
name: $(TeamProject)_$(Build.DefinitionName)_$(SourceBranchName)_$(Date:yyyyMMdd).$(Rev:r)
steps:
- script: echo '$(Build.BuildNumber)'
运行次数
Azure Pipelines 中运行编号的默认值为 $(Date:yyyyMMdd).$(Rev:r)
。 $(Rev:r)
是一种仅在生成号字段中工作的特殊变量格式。 生成完成后,如果内部版本号中没有其他任何更改,整数 Rev
值将增加一个。
$(Rev:r)
1
在内部版本号的任何其他部分发生更改时重置。 例如,如果将内部版本号格式配置为 $(Build.DefinitionName)_$(Date:yyyyMMdd).$(Rev:r)
,则生成号将在日期更改时重置。
如果以前的内部版本号为 MyBuild_20230621.1
,则当天的下一个内部版本号为 MyBuild_20230621.2
。 第二天的第一个内部版本号是 MyBuild_20230622.1
。
$(Rev:r)
如果更改内部版本号以指示版本更改,则也会重置 1
为< 例如,如果生成格式为 1.0.$(Rev:r)
和最后一个内部版本号 1.0.3
,如果将内部版本号更改为,则下一个内部版本号 1.1.$(Rev:r)
为 1.1.1
。
示例
请考虑以下用于生成运行的数据:
- 项目名称:Fabrikam
- 管道名称:CIBuild
- 分支:main
- 生成 ID/运行 ID:752
- 日期:2024 年 5 月 6 日
- 时间:晚上 9:07:03
- 今天早些时候完成了一次运行。
如果指定以下内部版本号格式,则 2024 年 5 月 6 日的第二个运行命名 为 Fabrikam_CIBuild_main_20240506.2。
$(TeamProject)_$(Build.DefinitionName)_$(SourceBranchName)_$(Date:yyyyMMdd).$(Rev:r)
令牌
下表显示了每个令牌如何根据前面的示例解析。 只能使用这些令牌来定义运行编号。 它们在管道中的其他任何位置都不起作用。
令牌 | 示例值 | 备注 |
---|---|---|
$(Build.DefinitionName) |
CIBuild | 管道名称不能包含无效或空格字符。 |
$(Build.BuildId) |
752 | $(Build.BuildId) 是一个内部不可变 ID,也称为“运行 ID”,在 Azure DevOps 组织中是唯一的。 |
$(DayOfMonth) |
6 | |
$(DayOfYear) |
126 | |
$(Hours) |
21 | |
$(Minutes) |
7 | |
$(Month) |
5 | |
$(Rev:r) |
2 | 第三次每日运行是 3 等。 用于 $(Rev:r) 确保每个已完成的生成都具有唯一的名称。 |
$(Date:yyyyMMdd) |
20240506 | 可以指定其他日期格式,例如 $(Date:MMddyy) 。 |
$(Seconds) |
3 | |
$(SourceBranchName) |
主要 | |
$(TeamProject) |
Fabrikam | |
$(Year:yy) |
24 | |
$(Year:yyyy) |
2024 |
重要
如果要在运行编号中显示前缀零,可以向令牌添加更多 r
字符 Rev
。 例如,指定 $(Rev:rr)
是否希望 Rev
数字以 01
开头 02
,等等。
如果使用零填充 Rev
作为版本号方案的一部分,请注意,某些管道任务或常用工具(如 NuGet 包)会删除前导零。 此行为会导致生成的项目中的版本号不匹配。
表达式
如果使用表达式设置生成号,则无法使用某些标记,因为在计算表达式时未设置这些标记的值。 这些令牌包括 $(Build.BuildId)
、$(Build.BuildURL)
和 $(Build.BuildNumber)
。
变量
可以在内部版本号中使用用户定义的和预定义变量。 例如,如果定义 My.Variable
,可以指定以下数字格式:
$(Build.DefinitionName)_$(Build.DefinitionVersion)_$(Build.RequestedFor)_$(Build.BuildId)_$(My.Variable)
在前面的示例中,前四个变量是预定义的。 有关如何定义用户变量的信息,请参阅 在管道中设置变量。
常见问题解答
运行编号的大小以及可以使用哪些字符?
运行编号最多可以包含 255 个字符。 不能使用字符"
、/
、、:
、<
>
'
、、|
、?
、或@
*
,不能以数字结尾。.
生成号时间值以何种时区表示?
时区为 UTC。
时区与运行应用程序层服务器的计算机的操作系统的时区相同。
如何使用条件动态设置生成号?
可以使用变量作为运行号的一部分。 在下面的示例中,变量 why
用作运行编号的一部分,其值会根据该变量的变化 Build.Reason
而变化。
variables:
- name: why
${{ if eq(variables['Build.Reason'], 'PullRequest') }}:
value: pr
${{ elseif eq(variables['Build.Reason'], 'Manual' ) }}:
value: manual
${{ elseif eq(variables['Build.Reason'], 'IndividualCI' ) }}:
value: indivci
${{ else }}:
value: other
name: $(TeamProject)_$(SourceBranchName)_$(why)_$(Date:yyyyMMdd).$(Rev:r)
pool:
vmImage: 'ubuntu-latest'
steps:
- script: echo '$(Build.BuildNumber)'
如何在脚本中引用运行编号变量?
可以定义包含运行编号的新变量,或直接调用运行编号。 在以下示例中, $(MyRunNumber)
是包含运行编号的新变量。 可以使用 MyRunNumber
或 $(Build.BuildNumber)
.
# Set MyRunNumber
variables:
MyRunNumber: '1.0.0-CI+$(Build.BuildNumber)'
steps:
- script: echo $(MyRunNumber)
- script: echo $(Build.BuildNumber)