クラシック リリースと成果物の変数
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
クラシック リリースと成果物の変数は、パイプライン全体でデータを交換、および転送するための便利な方法です。 各変数は文字列として格納されます。その値はパイプラインの実行ごとに変更できます。
変数は、テンプレート解析時にのみ使用できるランタイム パラメーターとは異なります。
DevOps CI/CD プロセスの各ステージでアプリケーションを展開するためのタスクを構成するとき、変数は次のようなことに役立ちます。
より汎用的な配置パイプラインを一度定義し、それをステージごとに簡単にカスタマイズします。 たとえば、変数を使って 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.{ステージ名}.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 スクリプトで別名が ASPNET4.CI である成果物ソースの成果物の変数 Release.Artifacts.{Artifact alias}.DefinitionName
の値を出力するには、$env:RELEASE_ARTIFACTS_ASPNET4_CI_DEFINITIONNAME
を使うことになります。
成果物ソースの別名の元の名前 ASPNET4.CI
が ASPNET4_CI
に置き換わっていることに注意してください。
すべての変数の現在の値を表示する
リリースの概要のパイプライン ビューを開き、目的のステージを選びます。 手順の一覧で、[ジョブの初期化] を選びます。
これにより、この手順のログが開きます。 下にスクロールして、このジョブのエージェントによって使われる値を確認します。
デバッグ モードでリリースを実行する
リリース全体、または個々のリリース ステージのタスクだけをデバッグ モードで実行することにより、リリースの実行時やログ ファイルに追加情報を表示します。 これは、問題やエラーを解決するのに役立ちます。
リリース全体のデバッグ モードを開始するには、リリース パイプラインの [変数] タブに
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 スクリプト タスクまたは 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)
フィードバック
https://aka.ms/ContentUserFeedback」を参照してください。
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「フィードバックの送信と表示