クラシック リリース パイプラインで変数を使用する
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
クラシック リリース パイプラインで変数を使用すると、パイプライン全体でデータを交換および転送するのに便利です。 各変数は文字列として格納され、その値はパイプライン実行間で変更できます。
テンプレートの解析時にのみ使用できるランタイム パラメーターとは異なり、クラシック リリース パイプラインの変数はデプロイ プロセス全体を通じてアクセスできます
クラシック リリース パイプラインの各ステージにアプリケーションをデプロイするタスクを設定する場合、変数を使用することで次のことが可能です。
カスタマイズの簡略化: 一般的なデプロイ パイプラインを一度定義すれば、さまざまなステージに簡単に適応できます。 たとえば、変数を使用して Web デプロイの接続文字列を表し、必要に応じて各ステージの値を調整します。 これらは、カスタム変数と呼ばれます。
コンテキスト情報の活用: ステージ、成果物、またはデプロイを実行しているエージェントなど、リリース コンテキストに関する詳細にアクセスします。 たとえば、スクリプトによっては、ダウンロード用のビルド場所や、一時ファイルを作成するためのエージェントの作業ディレクトリが必要になる場合があります。 これらは、既定の変数と呼ばれます。
既定の変数
既定の変数は実行コンテキストに関する重要な情報を、実行中のタスクとスクリプトに提供します。 これらの変数を使用すると、実行されているシステム、リリース、ステージ、またはエージェントに関する詳細にアクセスできます。
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.{stage-name}.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 の ID。 例: 2f435d07-769f-4e46-849d-10d1ab9ba6ab |
| Release.SkipArtifactsDownload | エージェントへの成果物のダウンロードをスキップするかどうかを指定するブール値。 例: FALSE |
| Release.TriggeringArtifact.Alias | リリースをトリガーした成果物の別名。 リリースがスケジュールされているか、手動でトリガーした場合、これは空です。 例: fabrikam\_app |
リリースステージ変数
| 変数名 | 説明 |
|---|---|
| Release.Environments.{stage name}.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: 1GitHub: fabrikam/asp |
| Release.Artifacts.{別名}.DefinitionName | ビルド パイプラインまたはリポジトリの名前。例: Azure Pipelines: fabrikam-ciTFVC: $/fabrikamGit: fabrikamGitHub: fabrikam/asp (main) |
| Release.Artifacts.{別名}.BuildNumber | ビルド番号またはコミット識別子。例: Azure Pipelines: 20170112.1Jenkins: 20170112.1TFVC: Changeset 3Git: 38629c964GitHub: 38629c964 |
| Release.Artifacts.{別名}.BuildId | ビルド識別子。例: Azure Pipelines: 130Jenkins: 130GitHub: 38629c964d21fe405ef830b7d0220966b82c9e11 |
| Release.Artifacts.{別名}.BuildURI | ビルドの URL。例: Azure Pipelines: vstfs://build-release/Build/130GitHub: 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: BuildJenkins: JenkinsTFVC: TFVCGit: GitGitHub: GitHub |
| Release.Artifacts.{別名}.PullRequest.TargetBranch | pull request のターゲットとなるブランチの完全なパスと名前。 この変数は、リリースがプル リクエスト フローによってトリガーされた場合にのみ初期化されます。例: Azure Pipelines: refs/heads/main |
| Release.Artifacts.{別名}.PullRequest.TargetBranchName | 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 をエイリアスとして持つ成果物の PowerShell タスクに引数として Release.Artifacts.{Artifact alias}.DefinitionName を渡すには、$(Release.Artifacts.ASPNET4.CI.DefinitionName) を使用します。
スクリプトで既定の変数を使うには、まず、既定の変数名の . を _ に置き換える必要があります。 たとえば、ASPNET4.CI をエイリアスとして持つ成果物の Release.Artifacts.{Artifact alias}.DefinitionName の値を PowerShell スクリプトで印刷するには、$env:RELEASE_ARTIFACTS_ASPNET4_CI_DEFINITIONNAME を使用します。 元のエイリアス (ASPNET4.CI) は ASPNET4_CI に置き換えられることに注意してください。
カスタム変数
カスタム変数は、さまざまなスコープで定義できます。
変数グループ: 変数グループを使用して、プロジェクト内のすべての定義で値を共有します。 これは、プロジェクト内の定義、ステージ、タスク全体で同じ値を使用し、それらを 1 つの場所から管理する場合に便利です。 変数グループを [パイプライン]>[ライブラリ] で定義および管理します。
リリース パイプライン変数: リリース パイプライン変数を使用して、リリース パイプライン内のすべてのステージで値を共有します。 これは、ステージ間やタスク間で一貫性のある値を必要とするシナリオに最適で、1 つの場所から値を更新することもできます。 これらの変数は、リリース パイプラインの [変数] タブで定義および管理します。 変数を追加するときは、[パイプライン変数] ページで [範囲] ドロップダウン リストを [リリース] に設定します。
ステージ変数: ステージ変数を使用して、リリース パイプラインの特定のステージ内で値を共有します。 これは、ステージごとに異なるものの、ステージ内のすべてのタスクで一貫性のある値の場合に便利です。 これらの変数は、リリース パイプラインの [変数] タブで定義および管理します。 変数を追加するときは、[パイプライン変数] ページで [範囲] ドロップダウン リストを適切な環境に設定します。
プロジェクト、リリース パイプライン、ステージ レベルでカスタム変数を使用すると、次のことが可能です。
値の重複を避けて、すべての出現箇所を 1 回の変更で簡単に更新できるようになります。
ユーザーが表示したり変更したりできないようにして、機密値をセキュリティで保護します。 変数をセキュリティで保護された (シークレット) としてマークするには、変数の横にある
アイコンを選択します。重要
非表示の変数 (シークレット) の値はサーバー上に安全に格納されており、保存後にユーザーが表示することはできません。 デプロイ中、これらの値がタスクによって参照されると、Azure Pipelines は値の解読を行い、セキュリティで保護された HTTPS チャネル経由で値をエージェントに渡します。
Note
カスタム変数を作成すると、標準変数が上書きされる可能性があります。 たとえば、Windows エージェントでカスタムの Path 変数を定義すると、$env:Path 変数が上書きされ、PowerShell を正常に実行できなくなる可能性があります。
カスタム変数の使用
タスクでカスタム変数を使用するには、変数名をかっこで囲み、その前に $ 文字を付けます。 たとえば、adminUserName という名前の変数がある場合、その変数の現在の値を $(adminUserName) としてタスクに挿入できます。
Note
同じ範囲 (ジョブやステージなど) でパイプラインにリンクされている異なるグループの変数は競合する可能性があり、その場合は予期しない結果が生じます。 これを回避するには、すべての変数グループで変数に一意の名前を付けるようにします。
スクリプトで変数を定義および変更する
スクリプトから変数を定義または変更するには、task.setvariable ログ コマンドを使います。 更新された変数の値は、実行されているジョブに範囲が設定されます。そして、ジョブ間やステージ間では保持されません。 変数名は大文字に変換され、"." と " " が "_" に置き換えられます。
たとえば、Agent.WorkFolder が AGENT_WORKFOLDERになります。
- Windows では、この変数に
%AGENT_WORKFOLDER%または$env:AGENT_WORKFOLDERとしてアクセスします。 - Linux と macOS では、
$AGENT_WORKFOLDERを使用します。
ヒント
スクリプトは、次の場所で実行できます。
- Batch スクリプト タスクまたは PowerShell タスクのどちらかを使用する Windows エージェント。
- Shell スクリプト タスクを使用する macOS または Linux のエージェント。
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)
すべての変数の現在の値を表示する
[パイプライン]>[リリース] を選択します。
リリースの概要ビューを開き、関心のあるステージを選択します。 手順の一覧で、[ジョブの初期化] を選びます。
これにより、この手順のログが開きます。 下にスクロールして、このジョブのエージェントによって使われる値を確認します。
デバッグ モードでリリースを実行する
リリースをデバッグ モードで実行すると、リリース実行中に追加情報が表示されるため、問題や障害を診断して解決することができます。 デバッグ モードは、リリース全体で有効にすることも、特定のリリース ステージ内のタスクに対してのみ有効にすることもできます。
リリース全体でデバッグ モードを有効にするには、リリース パイプラインの [変数] タブに、値
trueを持つSystem.Debugという名前の変数を追加します。特定のステージに対してデバッグ モードを有効にするには、そのステージのショートカット メニューから [ステージの構成] ダイアログを開き、[変数] タブに値
trueを持つSystem.Debugという名前の変数を追加します。または、値
trueを持つSystem.Debugという名前の変数を含む変数グループを作成し、この変数グループをリリース パイプラインにリンクします。
ヒント
Azure ARM サービス接続に関連するエラーが発生した場合の詳細については、「方法: Azure Resource Manager サービス接続のトラブルシューティング」を参照してください。