実行番号とビルド番号
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
この記事では、Azure Pipelines のビルド番号と実行番号の作成方法と、それらをパイプラインでカスタマイズする方法について説明します。
実行番号は、パイプラインまたはビルドの特定の実行を識別するために使用されます。 ビルド番号は、実行番号と同義です。
YAML パイプラインでビルド名を指定しない場合、またはクラシック パイプラインで [名前] フィールドを空白のままにした場合、実行はその名前として一意の整数を取得します。 チームにとって意味があり使いやすい名前を実行に付けることが推奨されます。 ビルド名には、トークン、変数、アンダースコア文字の組み合わせることができます。
YAML パイプラインでは、ビルド名プロパティは、name と呼ばれ、パイプラインのルート レベルにある必要があります。 YAML ファイルのルート レベルで指定された項目は、パイプライン プロパティです。
Note
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 整数値は 1 ずつ増加します。
ビルド番号の他の部分が変更されると、$(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
- 1 回の実行は、今日の早い段階で完了しました。
次のビルド番号形式を指定すると、2024 年 5 月 6日の 2番目の実行の名前は、Fabrikam_CIBuild_main_20240506.2 となります。
$(TeamProject)_$(Build.DefinitionName)_$(SourceBranchName)_$(Date:yyyyMMdd).$(Rev:r)
トークン
次の表に、前の例に基づいて各トークンがどのように解決されるかを示します。 これらのトークンは、実行番号の定義にのみ使用できます。 パイプライン内の他の場所では機能しません。
| Token | 値の例 | メモ |
|---|---|---|
$(Build.DefinitionName) |
CIBuild | パイプライン名に無効な文字または空白文字を含めてはなりません。 |
$(Build.BuildId) |
752 | $(Build.BuildId) は、Azure DevOps 組織全体で一意である、内部の不変 ID (実行 ID とも呼ばれます) です。 |
$(DayOfMonth) |
6 | |
$(DayOfYear) |
126 | |
$(Hours) |
21 | |
$(Minutes) |
7 | |
$(Month) |
5 | |
$(Rev:r) |
2 | 3 番目の日次実行は、3 などです。 $(Rev:r) を使用して、完了した各ビルドに一意の名前が付いているかを確認します。 |
$(Date:yyyyMMdd) |
20240506 | $(Date:MMddyy) などのその他日付形式を指定できます。 |
$(Seconds) |
3 | |
$(SourceBranchName) |
メイン | |
$(TeamProject) |
Fabrikam | |
$(Year:yy) |
24 | |
$(Year:yyyy) |
2024 |
重要
実行番号に、0 のプレフィックスを表示する場合は、より多くの r 文字を Rev トークンに追加できます。 たとえば、Rev 番号をの 1 桁目を 01、02などにする場合は、$(Rev:rr) を指定します。
バージョン番号付けスキームの一部として 0 を埋め込む Rev を使用する場合は、一部のパイプライン タスクや一般的なツール (NuGetパッケージなど) によって先頭の 0 が削除されることに注意してください。 この動作により、生成されるアーティファクトのバージョン番号との不一致が発生します。
式
式を使用してビルド番号を設定する場合、式の評価時に値が設定されないため、一部のトークンを使用できません。 これらのトークンには、$(Build.BuildId)、$(Build.BuildURL)、$(Build.BuildNumber) が含まれます。
変数
ビルド番号には、ユーザー定義変数と定義済み変数を使用できます。 たとえば、My.Variable を定義した場合は、次の数値形式を指定できます。
$(Build.DefinitionName)_$(Build.DefinitionVersion)_$(Build.RequestedFor)_$(Build.BuildId)_$(My.Variable)
前の例では、最初の 4 つの変数が定義済みです。 ユーザー変数を定義する方法については、「パイプラインで変数を設定する」を参照してください。
よく寄せられる質問
実行番号の大きさと使用できる文字は何ですか?
実行番号には、最大 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)