配置运行或生成号

  • 项目

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

你可以自定义管道运行的编号方式。 运行号的默认值为 $(Date:yyyyMMdd).$(Rev:r)。

在 Azure DevOps 中，$(Rev:r) 是一种特殊的变量格式，仅适用于生成号字段。 完成生成后，如果生成号中没有其他更改，则 Rev 整数值将按一递增。

$(Rev:r) 在你更改生成号的部分内容时重置。 例如，如果已将生成号格式配置为 $(Build.DefinitionName)_$(Date:yyyyMMdd).$(Rev:r)，则当日期在第二天发生变化时，生成号将重置。 如果生成号是 MyBuild_20230621.1，则当天的下一个生成号是 MyBuild_20230621.2。 第二天，生成号为 MyBuild_20230622.1。

如果生成号格式为 1.0.$(Rev:r)，则在你更改生成号的部分内容时，生成号将重置为 1.0.1。 例如，如果最后一个生成号为 1.0.3，然后你将生成号更改为 1.1.$(Rev:r) 以指示版本更改，则下一个生成号为 1.1.1。

在 YAML 中，此属性称为 name，并且必须位于管道的根级别。

注意

在 YAML 文件的根级别指定的项目是管道属性。

如果未指定，则系统会为你的运行提供一个唯一的整数作为其名称。 你可以为运行提供对团队有意义且更有用的名称。 你可以使用令牌、变量和下划线字符的组合。 属性 name 在模板文件中不起作用。

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

steps:
  - script: echo '$(Build.BuildNumber)' # outputs customized build number like project_def_master_20200828.1

YAML 生成在 TFS 上尚不可用。

示例

此时，将启动运行：

  • 项目名称：Fabrikam

  • 管道名称：CIBuild

  • 分支：main

  • 生成 ID/运行 ID：752

  • 日期：2019 年 5 月 5 日。

  • 时间：下午 9:07:03。

  • 今天早些时候完成了一次运行。

如果指定此生成号格式：

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

然后，同一天的第二次运行将命名为：Fabrikam_CIBuild_main_20190505.2

令牌

下表显示了如何基于上一个示例解析每个令牌。 这些令牌只能用于定义运行编号；它们在管道中的其他任何位置都不起作用。

标记 替换值示例
$(Build.DefinitionName) CIBuild

注意：管道名称不得包含无效字符或空格字符。
$(Build.BuildId) 752

$(Build.BuildId) 是内部不可变 ID，也称为运行 ID。 它在整个组织中是唯一的。
$(DayOfMonth) 5
$(DayOfYear) 217
$(Hours) 21
$(Minutes) 7
$(Month) 8
$(Rev:r) 2（第三次运行为 3，以此类推。）

使用 $(Rev:r) 确保每个已完成的生成都具有一个唯一名称。 生成启动后，如果未更改生成号中的其他任何内容，则 Rev 整数值将按一递增。

如果要在编号中显示前缀零，可以添加更多“r”字符。 例如，如果希望 Rev 编号以 01、02 开头，请指定“$(Rev：rr)”。 如果使用零填充 Rev 作为版本号方案的一部分，请注意，某些管道任务或常用工具（如 NuGet 包）会删除前导零，这会导致产生的工件中的版本号不匹配。
$(Date:yyyyMMdd) 20090824

可以指定其他日期格式，如 $(Date:MMddyy)
$(Seconds) 3
$(SourceBranchName) 主要
$(TeamProject) Fabrikam
$(Year:yy) 09
$(Year:yyyy) 2009

变量

还可以在编号中使用范围为“All”的用户定义变量和预定义变量。 例如，如果已定义 My.Variable，则可以指定以下编号格式：

$(Build.DefinitionName)_$(Build.DefinitionVersion)_$(Build.RequestedFor)_$(Build.BuildId)_$(My.Variable)

前四个变量是预定义的。 My.Variable 是你在“变量”选项卡上定义的。

表达式

如果使用表达式来设置生成号，某些令牌是不能使用的，因为在计算表达式时不会设置它们的值。 这些令牌包括 $(Build.BuildId)、$(Build.BuildURL) 和 $(Build.BuildNumber)。

常见问题解答

运行号可以达到多大？可以使用哪些字符？

运行号最多可以有 255 个字符。 不允许的字符包括 "、/、:、<、>、'、|、?、@ 和 *。 不能以 . 结尾。

生成号时间值是用哪个时区表示的？

时区为 UTC。

时区与运行应用层服务器的计算机操作系统的时区相同。

如何在脚本中引用运行号变量？

可以使用 $(Build.BuildNumber) 调用运行号变量。 可以定义包含运行号的新变量，也可以直接调用运行号。 在此示例中，$(MyRunNumber) 是一个包含运行号的新变量。

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


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

如何使用条件动态设置生成号？

可以使用变量作为运行号的一部分。 在此示例中，变量 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)' ## output run number