クラシック リリースと成果物の変数

  • [アーティクル]

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

クラシック リリースと成果物の変数は、パイプライン全体でデータを交換、および転送するための便利な方法です。 各変数は文字列として格納されます。その値はパイプラインの実行ごとに変更できます。

変数は、テンプレート解析時にのみ使用できるランタイム パラメーターとは異なります。

DevOps CI/CD プロセスの各ステージでアプリケーションを展開するためのタスクを構成するとき、変数は次のようなことに役立ちます。

  • より汎用的な配置パイプラインを一度定義し、それをステージごとに簡単にカスタマイズします。 たとえば、変数を使って Web 配置の接続文字列を表すことができます。この変数の値は、ステージによって変更できます。 これはカスタム変数です。

  • 配置パイプラインが実行されている特定のリリース、ステージ、成果物、またはエージェントのコンテキストに関する情報を使います。 たとえば、スクリプトでは、ビルドの場所にアクセスしてダウンロードしたり、一時ファイル作成のためにエージェント上の作業ディレクトリにアクセスしたりすることが必要な場合があります。 これらは既定の変数です。

注意

YAML パイプラインの詳細については、ユーザー定義変数と定義済み変数に関するページを参照してください。

既定の変数

実行コンテキストに関する情報は、実行中のタスクからは既定の変数を介して利用できます。 タスクやスクリプトはこれらの変数を使って、実行中のシステム、リリース、ステージ、またはエージェントに関する情報を見つけることができます。 System.Debug を除き、これらの変数は読み取り専用で、その値はシステムによって自動的に設定されます。 最も重要な変数のいくつかを次の表に示します。 完全な一覧を確認するには、「すべての変数の現在の値を表示する」を参照してください。

ヒント

リリースのすべての変数の現在の値を表示し、既定の変数を使ってリリースをデバッグ モードで実行することができます。

システム

変数名 説明
System.TeamFoundationServerUri Azure Pipelines のサービス接続の URL。 スクリプトやタスクから、Azure Pipelines の REST API を呼び出すために使います。

例: https://fabrikam.vsrm.visualstudio.com/
System.TeamFoundationCollectionUri Team Foundation コレクションまたは Azure Pipelines の URL。 スクリプトやタスクから、ビルドやバージョン管理などの他のサービスの REST API を呼び出すために使います。

例: https://dev.azure.com/fabrikam/
System.CollectionId このビルドまたはリリースが属するコレクションの ID。

例: 6c6f3423-1c84-4625-995a-f7f143a1e43d
System.DefinitionId 現在のリリースが属するリリース パイプラインの ID。

例: 1
System.TeamProject このビルドまたはリリースが属するプロジェクトの名前。

例: Fabrikam
System.TeamProjectId このビルドまたはリリースが属するプロジェクトの ID。

例: 79f5c12e-3337-4151-be41-a268d2c73344
System.ArtifactsDirectory リリースの配置中に成果物がダウンロードされるディレクトリ。 成果物をエージェントにダウンロードする必要がある場合は、すべての配置の前にディレクトリがクリアされます。 Agent.ReleaseDirectory および System.DefaultWorkingDirectory と同じです。

例: C:\agent\_work\r1\a
System.DefaultWorkingDirectory リリースの配置中に成果物がダウンロードされるディレクトリ。 成果物をエージェントにダウンロードする必要がある場合は、すべての配置の前にディレクトリがクリアされます。 Agent.ReleaseDirectory および System.ArtifactsDirectory と同じです。

例: C:\agent\_work\r1\a
System.WorkFolder このエージェントの作業ディレクトリ。ビルドまたはリリースごとにサブフォルダーが作成されます。 Agent.RootDirectory および Agent.WorkFolder と同じです。

例: C:\agent\_work
System.Debug これは、ユーザーが "設定" することができる唯一のシステム変数です。 これを true に設定すると、リリースをデバッグ モードで実行し、エラー検出を支援します。

例: true

リリース

変数名 説明
Release.AttemptNumber このステージでこのリリースが配置された回数。

例: 1
Release.DefinitionEnvironmentId 対応するリリース パイプラインのステージの ID。

例: 1
Release.DefinitionId 現在のリリースが属するリリース パイプラインの ID。

例: 1
Release.DefinitionName 現在のリリースが所属するリリース パイプラインの名前。

例: fabrikam-cd
Release.Deployment.RequestedFor 現在進行中の配置をトリガー (開始) した ID の表示名。

例: Mateo Escobedo
Release.Deployment.RequestedForEmail 現在進行中の配置をトリガー (開始) した ID のメール アドレス。

例: mateo@fabrikam.com
Release.Deployment.RequestedForId 現在進行中の配置をトリガー (開始) した ID。

例: 2f435d07-769f-4e46-849d-10d1ab9ba6ab
Release.DeploymentID 配置の ID。 ジョブごとに一意です。

例: 254
Release.DeployPhaseID 配置が実行されているフェーズの ID。

例: 127
Release.EnvironmentId 配置が現在進行中のリリース内のステージ インスタンスの ID。

例: 276
Release.EnvironmentName 配置が現在進行中のステージの名前。

例: Dev
Release.EnvironmentUri 配置が現在進行中のリリース内のステージ インスタンスの URI。

例: vstfs://ReleaseManagement/Environment/276
Release.Environments.{ステージ名}.status ステージの配置の状態。

例: InProgress
Release.PrimaryArtifactSourceAlias プライマリ成果物ソースの別名

例: fabrikam\_web
Release.Reason 配置の理由。 サポートされる値は次のとおりです。
ContinuousIntegration - ビルド完了後、継続的デプロイでリリースが開始されました。
Manual - リリースが手動で開始されました。
None - 配置の理由が指定されていません。
Schedule - リリースはスケジュールから開始されました。
Release.ReleaseDescription リリース時に指定されたテキストの説明。

例: Critical security patch
Release.ReleaseId 現在のリリース レコードの識別子。

例: 118
Release.ReleaseName 現在のリリースの名前。

例: Release-47
Release.ReleaseUri 現在のリリースの URI。

例: vstfs://ReleaseManagement/Release/118
Release.ReleaseWebURL このリリースの URL。

例: https://dev.azure.com/fabrikam/f3325c6c/_release?releaseId=392&_a=release-summary
Release.RequestedFor リリースをトリガーした ID の表示名。

例: Mateo Escobedo
Release.RequestedForEmail リリースをトリガーした ID のメール アドレス。

例: mateo@fabrikam.com
Release.RequestedForId リリースをトリガーした ID。

例: 2f435d07-769f-4e46-849d-10d1ab9ba6ab
Release.SkipArtifactsDownload エージェントへの成果物のダウンロードをスキップするかどうかを指定するブール値。

例: FALSE
Release.TriggeringArtifact.Alias リリースをトリガーした成果物の別名。 リリースがスケジュールされているか、手動でトリガーした場合、これは空です。

例: fabrikam\_app

リリース ステージ

変数名 説明
Release.Environments.{ステージ名}.Status 指定したステージ内での、このリリースの配置の状態。

例: NotStarted

エージェント

変数名 説明
Agent.Name エージェント プールに登録されているエージェントの名前。 これはコンピューター名と異なる可能性があります。

例: fabrikam-agent
Agent.MachineName エージェントが構成されているコンピューターの名前。

例: fabrikam-agent
Agent.Version エージェント ソフトウェアのバージョン。

例: 2.109.1
Agent.JobName 実行中のジョブの名前 (Release や Build など)。

例: Release
Agent.HomeDirectory エージェントがインストールされているフォルダー。 このフォルダーには、エージェントのコードとリソースが含まれています。

例: C:\agent
Agent.ReleaseDirectory リリースの配置中に成果物がダウンロードされるディレクトリ。 成果物をエージェントにダウンロードする必要がある場合は、すべての配置の前にディレクトリがクリアされます。 System.ArtifactsDirectory および System.DefaultWorkingDirectory と同じです。

例: C:\agent\_work\r1\a
Agent.RootDirectory このエージェントの作業ディレクトリ。ビルドまたはリリースごとにサブフォルダーが作成されます。 Agent.WorkFolder および System.WorkFolder と同じです。

例: C:\agent\_work
Agent.WorkFolder このエージェントの作業ディレクトリ。ビルドまたはリリースごとにサブフォルダーが作成されます。 Agent.RootDirectory および System.WorkFolder と同じです。

例: C:\agent\_work
Agent.DeploymentGroupId エージェントが登録されている配置グループの ID。 配置グループ ジョブでのみ使用できます。

例: 1

一般的な成果物

リリースで参照される成果物ごとに、次の成果物の変数を使用できます。 すべての変数が各成果物の種類で意味を持つわけではありません。 次の表は、既定の成果物の変数を一覧表示し、成果物の種類に応じて持つ値の例を示しています。 例が空の場合は、その成果物の種類に対してその変数が設定されていないことを意味します。

{alias} プレースホルダーを成果物の別名に指定した値、またはリリース パイプライン用に生成された既定値で置き換えます。

変数名 説明
Release.Artifacts.{別名}.DefinitionId ビルド パイプラインまたはリポジトリの識別子。

Azure Pipelines の例: 1
GitHub の例: fabrikam/asp
Release.Artifacts.{別名}.DefinitionName ビルド パイプラインまたはリポジトリの名前。

Azure Pipelines の例: fabrikam-ci
TFVC の例: $/fabrikam
Git の例: fabrikam
GitHub の例: fabrikam/asp (main)
Release.Artifacts.{別名}.BuildNumber ビルド番号またはコミット識別子。

Azure Pipelines の例: 20170112.1
Jenkins/TeamCity の例: 20170112.1
TFVC の例: Changeset 3
Git の例: 38629c964
GitHub の例: 38629c964
Release.Artifacts.{別名}.BuildId ビルド識別子。

Azure Pipelines の例: 130
Jenkins/TeamCity の例: 130
GitHub の例: 38629c964d21fe405ef830b7d0220966b82c9e11
Release.Artifacts.{別名}.BuildURI ビルドの URL。

Azure Pipelines の例: vstfs://build-release/Build/130
GitHub の例: https://github.com/fabrikam/asp
Release.Artifacts.{別名}.SourceBranch ソースがビルドされたブランチの完全なパスと名前。

Azure Pipelines の例: refs/heads/main
Release.Artifacts.{別名}.SourceBranchName ソースのビルド元となったブランチの名前のみ。

Azure Pipelines の例: main
Release.Artifacts.{別名}.SourceVersion ビルドされたコミット。

Azure Pipelines の例: bc0044458ba1d9298cdc649cb5dcf013180706f7
Release.Artifacts.{別名}.Repository.Provider ソースのビルド元であるリポジトリの種類。

Azure Pipelines の例: Git
Release.Artifacts.{別名}.RequestedForID ビルドをトリガーしたアカウントの識別子。

Azure Pipelines の例: 2f435d07-769f-4e46-849d-10d1ab9ba6ab
Release.Artifacts.{別名}.RequestedFor ビルドを要求したアカウントの名前。

Azure Pipelines の例: Mateo Escobedo
Release.Artifacts.{別名}.Type 成果物ソースの種類 (ビルドなど)。

Azure Pipelines の例: Build
Jenkins の例: Jenkins
TeamCity の例: TeamCity
TFVC の例: TFVC
Git の例: Git
GitHub の例: GitHub
Release.Artifacts.{別名}.PullRequest.TargetBranch pull request のターゲットとなるブランチの完全なパスと名前。 この変数は、リリースが pull request フローによってトリガーされる場合にのみ初期化されます。

Azure Pipelines の例: refs/heads/main
Release.Artifacts.{別名}.PullRequest.TargetBranchName pull request のターゲットとなるブランチの名前のみ。 この変数は、リリースが pull request フローによってトリガーされる場合にのみ初期化されます。

Azure Pipelines の例: main

成果物ソースの別名に関するページも参照してください

プライマリ成果物

リリース パイプラインのプライマリ成果物として、成果物の 1 つを指定します。 指定されたプライマリ成果物に対して、Azure Pipelines では次の変数が設定されます。

変数名 同等なもの
Build.DefinitionId Release.Artifacts.{プライマリ成果物の別名}.DefinitionId
Build.DefinitionName Release.Artifacts.{プライマリ成果物の別名}.DefinitionName
Build.BuildNumber Release.Artifacts.{プライマリ成果物の別名}.BuildNumber
Build.BuildId Release.Artifacts.{プライマリ成果物の別名}.BuildId
Build.BuildURI Release.Artifacts.{プライマリ成果物の別名}.BuildURI
Build.SourceBranch Release.Artifacts.{プライマリ成果物の別名}.SourceBranch
Build.SourceBranchName Release.Artifacts.{プライマリ成果物の別名}.SourceBranchName
Build.SourceVersion Release.Artifacts.{プライマリ成果物の別名}.SourceVersion
Build.Repository.Provider Release.Artifacts.{プライマリ成果物の別名}.Repository.Provider
Build.RequestedForID Release.Artifacts.{プライマリ成果物の別名}.RequestedForID
Build.RequestedFor Release.Artifacts.{プライマリ成果物の別名}.RequestedFor
Build.Type Release.Artifacts.{プライマリ成果物の別名}.Type
Build.PullRequest.TargetBranch Release.Artifacts.{プライマリ成果物の別名}.PullRequest.TargetBranch
Build.PullRequest.TargetBranchName Release.Artifacts.{プライマリ成果物の別名}.PullRequest.TargetBranchName

既定の変数の使用

既定の変数は、リリース パイプラインで、またはスクリプト内での 2 つの方法で、タスクのパラメーターとして使用できます。

既定の変数は、タスクへの入力として直接使用できます。 たとえば、別名が ASPNET4.CI である成果物ソースの Release.Artifacts.{Artifact alias}.DefinitionName をタスクに渡すには、$(Release.Artifacts.ASPNET4.CI.DefinitionName) を使うことになります。

PowerShell スクリプトのタスクへの引数での成果物の変数の使用

スクリプトで既定の変数を使うには、まず、既定の変数名の . を _ に置き換える必要があります。 たとえば、PowerShell スクリプトで別名が ASPNET4.CI である成果物ソースの成果物の変数 Release.Artifacts.{Artifact alias}.DefinitionName の値を出力するには、$env:RELEASE_ARTIFACTS_ASPNET4_CI_DEFINITIONNAME を使うことになります。

インライン PowerShell スクリプトでの成果物の変数の使用

成果物ソースの別名の元の名前 ASPNET4.CI が ASPNET4_CI に置き換わっていることに注意してください。

すべての変数の現在の値を表示する

  1. リリースの概要のパイプライン ビューを開き、目的のステージを選びます。 手順の一覧で、[ジョブの初期化] を選びます。

    リリースのログを開く

  2. これにより、この手順のログが開きます。 下にスクロールして、このジョブのエージェントによって使われる値を確認します。

    リリースの変数の値の表示

デバッグ モードでリリースを実行する

リリース全体、または個々のリリース ステージのタスクだけをデバッグ モードで実行することにより、リリースの実行時やログ ファイルに追加情報を表示します。 これは、問題やエラーを解決するのに役立ちます。

  • リリース全体のデバッグ モードを開始するには、リリース パイプラインの [変数] タブに System.Debug という名前で値が true である変数を追加します。

  • 1 つのステージのデバッグ モードを開始するには、ステージのショートカット メニューから [ステージの構成] ダイアログを開き、[変数] タブに System.Debug という名前で値が true である変数を追加します。

  • または、変数グループに System.Debug という名前で値が true である変数を作成し、この変数グループをリリース パイプラインにリンクします。

ヒント

Azure RM サービス接続に関連するエラーが発生した場合は、「方法: Azure Resource Manager サービス接続のトラブルシューティング」を参照してください。

カスタム変数

カスタム変数は、さまざまなスコープで定義できます。

  • 変数グループを使うと、プロジェクト内のすべての定義で値が共有されます。 プロジェクト内のすべての定義、ステージ、タスクで同じ値を使う必要があり、1 か所で値を変更できるようにする場合に、変数グループを選びます。 変数グループの定義と管理は、[ライブラリ] タブで行います。

  • リリース パイプライン変数を使うと、すべてのステージで値を共有します。 リリース パイプラインのすべてのステージとタスクで同じ値を使用する必要があり、1 か所で値を変更できるようにする場合は、リリース パイプライン変数を選びます。 これらの変数の定義と管理は、リリース パイプラインの [変数] タブで行います。 [パイプライン変数] ページで、[スコープ] ドロップダウン リストを開き、[リリース] を選びます。 既定では、変数を追加すると、リリース スコープに設定されます。

  • ステージ変数を使用すると、1 つの特定のステージ内のすべてのタスクで値が共有されます。 ステージごとに異なる (ステージ内のすべてのタスクでは同じ) 値には、ステージレベルの変数を使います。 これらの変数の定義と管理は、リリース パイプラインの [変数] タブで行います。 [パイプライン変数] ページで、[スコープ] ドロップダウン リストを開き、必要なステージを選びます。 変数を追加するときは、スコープを適切な環境に設定します。

プロジェクト、リリース パイプライン、ステージ スコープでカスタム変数を使うと、次のことに役立ちます。

  • 値の重複を避け、1 回の操作で簡単にすべての出現箇所を更新できるようにします。

  • 機密性の高い値を、リリース パイプラインのユーザーが表示または変更できないように格納します。 構成プロパティをセキュリティで保護された (シークレット) 変数に指定するには、変数の横にある 南京錠 (南京錠) アイコンを選びます。

    重要

    非表示 (シークレット) 変数の値はサーバーにセキュリティで保護された方法で格納され、保存後にユーザーが表示することはできません。 配置中、Azure Pipelines リリース サービスは、タスクによって参照されたときにこれらの値を復号化し、セキュリティで保護された HTTPS チャネルを経由してエージェントに渡します。

注意

カスタム変数を作成すると、標準変数が上書きされる可能性があります。 たとえば、PowerShell の Path 環境変数です。 Windows エージェントでカスタム Path 変数を作成すると、$env:Path 変数が上書きされ、PowerShell は実行できなくなります。

カスタム変数の使用

ビルドやリリースのタスクでカスタム変数を使うには、変数名をかっこで囲み、その前に $ 文字を付けます。 たとえば、adminUserName という変数がある場合、その変数の現在値を $(adminUserName) としてタスクのパラメーターに挿入できます。

注意

同じスコープ (たとえば、ジョブやステージ) のパイプラインにリンクされている異なるグループの変数が競合し、結果が予測できない場合があります。 すべての変数グループで、変数に対して異なる名前を使うようにしてください。

スクリプトで変数を定義および変更する

スクリプトから変数を定義または変更するには、task.setvariable ログ コマンドを使います。 更新された変数値は、実行中のジョブにスコープが設定され、ジョブまたはステージ間でフローされないことに注意してください。 変数名は大文字に変換され、文字 "." と " " は "_" に置き換えられます。

たとえば、Agent.WorkFolder が AGENT_WORKFOLDER になります。 Windows では、%AGENT_WORKFOLDER% または $env:AGENT_WORKFOLDER としてアクセスします。 Linux と macOS では、$AGENT_WORKFOLDER を使います。

ヒント

スクリプトは、次で実行できます。

Batch スクリプト

sauce 変数と secret.Sauce 変数を設定する

@echo ##vso[task.setvariable variable=sauce]crushed tomatoes
@echo ##vso[task.setvariable variable=secret.Sauce;issecret=true]crushed tomatoes with garlic

変数を読み取る

引数

"$(sauce)" "$(secret.Sauce)"

スクリプト

@echo off
set sauceArgument=%~1
set secretSauceArgument=%~2
@echo No problem reading %sauceArgument% or %SAUCE%
@echo But I cannot read %SECRET_SAUCE%
@echo But I can read %secretSauceArgument% (but the log is redacted so I do not spoil
     the secret)

変数の読み取りによるコンソール出力:

No problem reading crushed tomatoes or crushed tomatoes
But I cannot read 
But I can read ******** (but the log is redacted so I do not spoil the secret)