次の方法で共有


クラシック リリース パイプラインで変数を使用する

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

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

テンプレートの解析時にのみ使用できるランタイム パラメーターとは異なり、クラシック リリース パイプラインの変数はデプロイ プロセス全体を通じてアクセスできます

クラシック リリース パイプラインの各ステージにアプリケーションをデプロイするタスクを設定する場合、変数を使用することで次のことが可能です。

  • カスタマイズの簡略化: 一般的なデプロイ パイプラインを一度定義すれば、さまざまなステージに簡単に適応できます。 たとえば、変数を使用して Web デプロイの接続文字列を表し、必要に応じて各ステージの値を調整します。 これらは、カスタム変数と呼ばれます。

  • コンテキスト情報の活用: ステージ成果物、またはデプロイを実行しているエージェントなど、リリース コンテキストに関する詳細にアクセスします。 たとえば、スクリプトによっては、ダウンロード用のビルド場所や、一時ファイルを作成するためのエージェントの作業ディレクトリが必要になる場合があります。 これらは、既定の変数と呼ばれます。

Note

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.{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: 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: 20170112.1
TFVC: Changeset 3
Git: 38629c964
GitHub: 38629c964
Release.Artifacts.{別名}.BuildId ビルド識別子。例:

Azure Pipelines: 130
Jenkins: 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
TFVC: TFVC
Git: Git
GitHub: 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 に置き換えられることに注意してください。

インライン PowerShell スクリプトで既定の変数を使用する方法を示すスクリーンショット。

カスタム変数

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

  • 変数グループ: 変数グループを使用して、プロジェクト内のすべての定義で値を共有します。 これは、プロジェクト内の定義、ステージ、タスク全体で同じ値を使用し、それらを 1 つの場所から管理する場合に便利です。 変数グループを [パイプライン]>[ライブラリ] で定義および管理します。

  • リリース パイプライン変数: リリース パイプライン変数を使用して、リリース パイプライン内のすべてのステージで値を共有します。 これは、ステージ間やタスク間で一貫性のある値を必要とするシナリオに最適で、1 つの場所から値を更新することもできます。 これらの変数は、リリース パイプラインの [変数] タブで定義および管理します。 変数を追加するときは、[パイプライン変数] ページで [範囲] ドロップダウン リストを [リリース] に設定します。

  • ステージ変数: ステージ変数を使用して、リリース パイプラインの特定のステージ内で値を共有します。 これは、ステージごとに異なるものの、ステージ内のすべてのタスクで一貫性のある値の場合に便利です。 これらの変数は、リリース パイプラインの [変数] タブで定義および管理します。 変数を追加するときは、[パイプライン変数] ページで [範囲] ドロップダウン リストを適切な環境に設定します。

プロジェクト、リリース パイプライン、ステージ レベルでカスタム変数を使用すると、次のことが可能です。

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

  • ユーザーが表示したり変更したりできないようにして、機密値をセキュリティで保護します。 変数をセキュリティで保護された (シークレット) としてマークするには、変数の横にある 南京錠 アイコンを選択します。

    重要

    非表示の変数 (シークレット) の値はサーバー上に安全に格納されており、保存後にユーザーが表示することはできません。 デプロイ中、これらの値がタスクによって参照されると、Azure Pipelines は値の解読を行い、セキュリティで保護された HTTPS チャネル経由で値をエージェントに渡します。

Note

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

カスタム変数の使用

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

Note

同じ範囲 (ジョブやステージなど) でパイプラインにリンクされている異なるグループの変数は競合する可能性があり、その場合は予期しない結果が生じます。 これを回避するには、すべての変数グループで変数に一意の名前を付けるようにします。

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

スクリプトから変数を定義または変更するには、task.setvariable ログ コマンドを使います。 更新された変数の値は、実行されているジョブに範囲が設定されます。そして、ジョブ間やステージ間では保持されません。 変数名は大文字に変換され、"." と " " が "_" に置き換えられます。

たとえば、Agent.WorkFolderAGENT_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)

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

  1. [パイプライン]>[リリース] を選択します。

  2. リリースの概要ビューを開き、関心のあるステージを選択します。 手順の一覧で、[ジョブの初期化] を選びます。

    ジョブの初期化の手順を示すスクリーンショット。

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

    エージェントによって使用される変数を示すスクリーンショット。

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

リリースをデバッグ モードで実行すると、リリース実行中に追加情報が表示されるため、問題や障害を診断して解決することができます。 デバッグ モードは、リリース全体で有効にすることも、特定のリリース ステージ内のタスクに対してのみ有効にすることもできます。

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

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

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

ヒント

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