运行号和生成号

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

本文介绍 Azure Pipelines 生成号和运行号的构造方式，以及如何在管道中自定义它们。

运行号用于标识管道或生成的特定执行。 生成号与运行号同义。

如果未在 YAML 管道中指定生成名称，或者在经典管道中将名称字段留空，则运行将获得一个唯一的整数作为其名称。 你可以为运行提供对团队有意义且更有用的名称。 你可以在内部版本名称中使用令牌、变量和下划线字符的组合。

在 YAML 管道中，内部版本名称属性称为 name，必须位于管道的根级别。 在 YAML 文件的根级别指定的项目是管道属性。

注意

属性 name 在模板文件中不起作用。

以下示例代码输出一个自定义的生成号，如 project_def_master_202408281。

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 PM
• 今天早些时候完成了一次运行。

如果指定以下生成号格式，则 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

重要

如果要在运行号中显示前缀零，可以为 Rev 令牌添加更多 r 字符。 例如，如果希望 Rev 编号以 01、02 等开头，请指定 $(Rev:rr)。

如果在版本编号方案中使用带零的 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)

相关内容

定义变量