変数グループの追加と使用

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

変数グループには、YAML パイプラインに渡すか、複数のパイプラインで使用できるようにする可能性がある値とシークレットが格納されます。 同じプロジェクト内の複数のパイプラインで変数グループを共有および使用できます。

変数グループ内のシークレット変数は、保護されたリソースです。 承認、チェック、パイプラインのアクセス許可の組み合わせを追加して、変数グループ内のシークレット変数へのアクセスを制限できます。 シークレット以外の変数へのアクセスは、承認、チェック、パイプラインのアクセス許可によって制限されません。

Note

Microsoft Visual Studio Team Foundation Server 2018 以前のバージョンでは、名前付けに次の違いがあります。

  • ビルドとリリースのためのパイプラインはビルドとリリースのためのパイプラインです。そしてそれらは定義と呼ばれます。
  • 実行ビルドと呼ばれます。
  • サービス接続サービスエンドポイントと呼ばれます。
  • ステージ環境と呼ばれます
  • ジョブは(フェーズと呼ばれます。

変数グループを作成する

YAML で変数グループを作成することはできませんが、「変数グループを使用する」の説明に従って使用できます。

変数グループを使用する

変数グループからの変数を使用するには、YAML ファイルでグループへの参照を追加します。

variables:
- group: my-variable-group

その後、YAML ファイルで変数グループからの変数を使用できます。

変数と変数グループの両方を使用する場合は、グループ化されていない個々の変数に対して name/value 構文を使用します。

variables:
- group: my-variable-group
- name: my-bare-variable
  value: 'value of my-bare-variable'

変数グループを参照するには、マクロ構文またはランタイム式を使用します。 次の例では、グループ my-variable-group に、myhello という名前の変数が与えられています。

variables:
- group: my-variable-group
- name: my-passed-variable
  value: $[variables.myhello] # uses runtime expression

steps:
- script: echo $(myhello) # uses macro syntax
- script: echo $(my-passed-variable) 

同じパイプライン内の複数の変数グループを参照できます。 複数の変数グループに同じ変数が含まれている場合、YAML ファイルに最後に含まれる変数グループによって変数の値が設定されます。

variables:
- group: my-first-variable-group
- group: my-second-variable-group

テンプレート内の変数グループを参照することもできます。 テンプレート variables.ymlでは、グループ my-variable-group が参照されます。 変数グループには、myhello という名前の変数が含まれています。

# variables.yml
variables:
- group: my-variable-group

このパイプラインでは、変数グループ my-variable-group からの変数 $(myhello) が含まれており、variables.yml が参照されます。

# azure-pipeline.yml
stages:
- stage: MyStage
  variables:
  - template: variables.yml
  jobs:
  - job: Test
    steps:
    - script: echo $(myhello)

変数グループを承認する

変数グループを操作するには、グループを承認する必要があります。 YAML で変数グループのみに名前を付けると、リポジトリにコードをプッシュできるすべてのユーザーが、変数グループ内のシークレットの内容を抽出できます。 グループを承認するには、次のいずれかの手法を使用します。

  • 変数グループを使用するパイプラインを承認するには、Azure Pipelines に移動します。 これは、グループにシークレットがない場合に適したオプションになる可能性があります。 [ライブラリ]>[変数グループ] を選択し、対象の変数グループを選択し、[すべてのパイプラインへのアクセスを許可] 設定を有効にします。

  • 特定のパイプラインの変数グループを承認するには、パイプラインを開き、[編集] を選択し、ビルドを手動でキューに入れます。 リソース承認エラーと、エラーに対する [リソースの承認] アクションが表示されます。 このアクションを選択して、変数グループの承認済みユーザーとしてパイプラインを明示的に追加します。

注意

変数グループをパイプラインに追加しても、必要なときにビルドでリソース承認エラーが発生しない場合は、[すべてのパイプラインへのアクセスを許可] 設定をオフにします。

TFS では、YAML ビルドは使用できません。

リンクされた変数グループ内の変数値に、パイプライン自体で定義する変数と同じ方法でアクセスします。 たとえば、パイプラインにリンクされた変数グループ内の customer という名前の変数の値にアクセスするには、タスク パラメーターまたはスクリプトで $(customer) を使用します。 ただし、シークレット変数 (暗号化された変数とキー コンテナー変数) にスクリプトで直接アクセスすることはできません。代わりに、タスクに引数として渡す必要があります。 詳細については、「シークレット」を参照してください

変数グループに対して行った変更は、変数グループがリンクされているすべての定義またはステージで自動的に使用できます。

変数グループを一覧表示する

CLI を使用して、az pipelines variable-group list コマンドでパイプライン実行の変数グループを一覧表示します。 CLI 用の Azure DevOps 拡張機能を初めて使用する場合は、「Azure DevOps CLI の概要」を参照してください。

az pipelines variable-group list [--action {manage, none, use}]
                                 [--continuation-token]
                                 [--group-name]
                                 [--org]
                                 [--project]
                                 [--query-order {Asc, Desc}]
                                 [--top]

省略可能なパラメーター

  • action: 変数グループに対して実行できるアクションを指定します。 指定できる値は managenoneuse です。
  • continuation-token: 継続トークンが指定された後の変数グループを一覧表示します。
  • group-name: 変数グループの名前。 new-var* などの、ワイルドカードを使用できます。
  • org: Azure DevOps 組織の URL。 az devops configure -d organization=ORG_URL を使用して、既定の組織を構成します。 既定として設定されていない場合、または git config を使用して取得された場合は必須です。 例: --org https://dev.azure.com/MyOrganizationName/.
  • project: プロジェクトの名前または ID。 az devops configure -d project=NAME_OR_ID を使用して、既定のプロジェクトを構成します。 既定として設定されていない場合、または git config を使用して取得された場合は必須です。
  • query-order: 結果を昇順または降順 (既定) で一覧表示します。 指定できる値は Asc および Desc です。
  • top: 一覧表示する変数グループの数。

次のコマンドによって、上位 3 つの変数グループが昇順で一覧表示され、結果がテーブル形式で返されます。

az pipelines variable-group list --top 3 --query-order Asc --output table

ID    Name               Type    Number of Variables
----  -----------------  ------  ---------------------
1     myvariables        Vsts    2
2     newvariables       Vsts    4
3     new-app-variables  Vsts    3

変数グループの詳細を表示する

az pipelines variable-group show コマンドを使用して、プロジェクト内の変数グループの詳細を表示します。 CLI 用の Azure DevOps 拡張機能を初めて使用する場合は、「Azure DevOps CLI の概要」を参照してください。

az pipelines variable-group show --group-id
                                 [--org]
                                 [--project]

パラメーター

  • group-id: 必須。 変数グループの ID。 変数グループ ID を見つけるには、「変数グループを一覧表示する」を参照してください。
  • org: Azure DevOps 組織の URL。 az devops configure -d organization=ORG_URL を使用して、既定の組織を構成します。 既定として設定されていない場合、または git config を使用して取得された場合は必須です。 例: --org https://dev.azure.com/MyOrganizationName/.
  • project: プロジェクトの名前または ID。 az devops configure -d project=NAME_OR_ID を使用して、既定のプロジェクトを構成します。 既定として設定されていない場合、または git config を使用して取得された場合は必須です。

次のコマンドによって、ID 4 の変数グループの詳細が示され、結果が YAML 形式で返されます。

az pipelines variable-group show --group-id 4 --output yaml

authorized: false
description: Variables for my new app
id: 4
name: MyNewAppVariables
providerData: null
type: Vsts
variables:
  app-location:
    isSecret: null
    value: Head_Office
  app-name:
    isSecret: null
    value: Fabrikam

変数グループを削除する

az pipelines variable-group delete コマンドを使用して、プロジェクト内の変数グループを削除します。 CLI 用の Azure DevOps 拡張機能を初めて使用する場合は、「Azure DevOps CLI の概要」を参照してください。

az pipelines variable-group delete --group-id
                                   [--org]
                                   [--project]
                                   [--yes]

パラメーター

  • group-id: 必須。 変数グループの ID。 変数グループ ID を見つけるには、「変数グループを一覧表示する」を参照してください。
  • org: Azure DevOps 組織の URL。 az devops configure -d organization=ORG_URL を使用して、既定の組織を構成します。 既定として設定されていない場合、または git config を使用して取得された場合は必須です。 例: --org https://dev.azure.com/MyOrganizationName/.
  • project: プロジェクトの名前または ID。 az devops configure -d project=NAME_OR_ID を使用して、既定のプロジェクトを構成します。 既定として設定されていない場合、または git config を使用して取得された場合は必須です。
  • yes: 省略可能。 確認のプロンプトは表示されません。

次のコマンドによって、ID 1 の変数グループが削除されますが、確認のプロンプトは表示されません。

az pipelines variable-group delete --group-id 1 --yes

Deleted variable group successfully.

変数グループに変数を追加する

Azure DevOps CLI では、az pipelines variable-group variable create コマンドを使用して、パイプライン内の変数グループに変数を追加できます。 CLI 用の Azure DevOps 拡張機能を初めて使用する場合は、「Azure DevOps CLI の概要」を参照してください。

az pipelines variable-group variable create --group-id
                                            --name
                                            [--org]
                                            [--project]
                                            [--secret {false, true}]
                                            [--value]

パラメーター

  • group-id: 必須。 変数グループの ID。 変数グループ ID を見つけるには、「変数グループを一覧表示する」を参照してください。
  • name:必須。 追加する変数の名前。
  • org: Azure DevOps 組織の URL。 az devops configure -d organization=ORG_URL を使用して、既定の組織を構成します。 既定として設定されていない場合、または git config を使用して取得された場合は必須です。 例: --org https://dev.azure.com/MyOrganizationName/.
  • project: プロジェクトの名前または ID。 az devops configure -d project=NAME_OR_ID を使用して、既定のプロジェクトを構成します。 既定として設定されていない場合、または git config を使用して取得された場合は必須です。
  • secret: 省略可能。 変数の値がシークレットかどうかを示します。 指定できる値は falsetrue です。
  • value: シークレット以外の変数に必要です。 変数の値。 シークレット変数の場合、value パラメーターが指定されていない場合は、AZURE_DEVOPS_EXT_PIPELINE_VAR_ というプレフィックスが付いた環境変数から選択されるか、または、ユーザーが標準入力を使用して入力するように求められます。 たとえば、MySecret という名前の変数は、環境変数 AZURE_DEVOPS_EXT_PIPELINE_VAR_MySecret を使用して入力できます。

次のコマンドによって、4 の ID を持つ変数グループの変数が作成されます。 新しい変数の名前は requires-login で、値は True であり、結果はテーブル形式で表示されます。

az pipelines variable-group variable create --group-id 4 --name requires-login --value True --output table

Name            Is Secret    Value
--------------  -----------  -------
requires-login  False        True

変数グループ内の変数を一覧表示する

az pipelines variable-group variable list コマンドを使用して、変数グループ内の変数を一覧表示できます。 CLI 用の Azure DevOps 拡張機能を初めて使用する場合は、「Azure DevOps CLI の概要」を参照してください。

az pipelines variable-group variable list --group-id
                                          [--org]
                                          [--project]

パラメーター

  • group-id: 必須。 変数グループの ID。 変数グループ ID を見つけるには、「変数グループを一覧表示する」を参照してください。
  • org: Azure DevOps 組織の URL。 az devops configure -d organization=ORG_URL を使用して、既定の組織を構成します。 既定として設定されていない場合、または git config を使用して取得された場合は必須です。 例: --org https://dev.azure.com/MyOrganizationName/.
  • project: プロジェクトの名前または ID。 az devops configure -d project=NAME_OR_ID を使用して、既定のプロジェクトを構成します。 既定として設定されていない場合、または git config を使用して取得された場合は必須です。

次のコマンドによって、ID が 4 の変数グループ内のすべての変数が一覧表示され、結果がテーブル形式で示されます。

az pipelines variable-group variable list --group-id 4 --output table

Name            Is Secret    Value
--------------  -----------  -----------
app-location    False        Head_Office
app-name        False        Fabrikam
requires-login  False        True

変数グループ内の変数を更新する

az pipelines variable-group variable update コマンドを使用して変数グループ内の変数を更新します。 CLI 用の Azure DevOps 拡張機能を初めて使用する場合は、「Azure DevOps CLI の概要」を参照してください。

az pipelines variable-group variable update --group-id
                                            --name
                                            [--new-name]
                                            [--org]
                                            [--project]
                                            [--prompt-value {false, true}]
                                            [--secret {false, true}]
                                            [--value]

パラメーター

  • group-id: 必須。 変数グループの ID。 変数グループ ID を見つけるには、「変数グループを一覧表示する」を参照してください。
  • name:必須。 追加する変数の名前。
  • new-name: 省略可能。 変数の名前の変更を指定します。
  • org: Azure DevOps 組織の URL。 az devops configure -d organization=ORG_URL を使用して、既定の組織を構成します。 既定として設定されていない場合、または git config を使用して取得された場合は必須です。 例: --org https://dev.azure.com/MyOrganizationName/.
  • project: プロジェクトの名前または ID。 az devops configure -d project=NAME_OR_ID を使用して、既定のプロジェクトを構成します。 既定として設定されていない場合、または git config を使用して取得された場合は必須です。
  • prompt-value: 環境変数または標準入力によるプロンプトを使用してシークレット変数の値を更新するには、true に設定します。 指定できる値は falsetrue です。
  • secret: 省略可能。 変数の値がシークレットのままかどうかを示します。 指定できる値は falsetrue です。
  • value: 変数の値を更新します。 シークレット変数の場合は、prompt-value パラメーターを使用して、標準入力を使用して入力するように求めます。 非対話型コンソールの場合は、AZURE_DEVOPS_EXT_PIPELINE_VAR_ というプレフィックスが付いた環境変数から選択できます。 たとえば、MySecret という名前の変数は、環境変数 AZURE_DEVOPS_EXT_PIPELINE_VAR_MySecret を使用して入力できます。

次のコマンドによって、ID が 4 の変数グループ内で、新しい値 False を使用して requires-login 変数が更新されます。 変数が シークレット であることが指定され、結果が YAML 形式で表示されます。 シークレットの非表示の値であるため、出力に False ではなく null として値が表示されていることに注意してください。

az pipelines variable-group variable update --group-id 4 --name requires-login --value False --secret true --output yaml

requires-login:
  isSecret: true
  value: null

変数グループから変数を削除する

az pipelines variable-group variable delete コマンドを使用して変数グループから変数を削除します。 CLI 用の Azure DevOps 拡張機能を初めて使用する場合は、「Azure DevOps CLI の概要」を参照してください。

az pipelines variable-group variable delete --group-id
                                            --name
                                            [--org]
                                            [--project]
                                            [--yes]

パラメーター

  • group-id: 必須。 変数グループの ID。 変数グループ ID を見つけるには、「変数グループを一覧表示する」を参照してください。
  • name:必須。 削除する変数の名前。
  • org: Azure DevOps 組織の URL。 az devops configure -d organization=ORG_URL を使用して、既定の組織を構成します。 既定として設定されていない場合、または git config を使用して取得された場合は必須です。 例: --org https://dev.azure.com/MyOrganizationName/.
  • project: プロジェクトの名前または ID。 az devops configure -d project=NAME_OR_ID を使用して、既定のプロジェクトを構成します。 既定として設定されていない場合、または git config を使用して取得された場合は必須です。
  • yes: 省略可能。 確認のプロンプトは表示されません。

次のコマンドによって、ID が 4 の変数グループから requires-login 変数が削除され、確認のプロンプトが表示されます。

az pipelines variable-group variable delete --group-id 4 --name requires-login

Are you sure you want to delete this variable? (y/n): y
Deleted variable 'requires-login' successfully.

Note

Azure ロールベースのアクセス制御 (Azure RBAC) を使用する Key Vault はサポートされていません。

既存の Azure Key Vault を変数グループにリンクし、選択したコンテナー シークレットを変数グループにマップします。

  1. [変数グループ] ページで、[シークレットを Azure Key Vault から変数としてリンクする] を有効にします。 シークレットを含む既存のキー コンテナーが必要です。 Azure portal を使用してキー コンテナーを作成します。

    Screenshot of variable group with Azure key vault integration.

  2. Azure サブスクリプションのエンドポイントと、シークレットを含むコンテナーの名前を指定します。

    Azure サービス接続に、シークレット用のコンテナーに対する少なくとも GetList の管理アクセス許可があることを確認します。 コンテナー名の横にある [承認] を選択して、Azure Pipelines でこれらのアクセス許可を設定できるようにします。 または、次の手順に従い、Azure portal でアクセス許可を手動で設定します。

    1. コンテナーの [設定] を開き、[アクセス ポリシー]>[新規追加] の順に選択します。
    2. [プリンシパルの選択] を選択し、クライアント アカウントのサービス プリンシパルを選択します。
    3. [シークレットのアクセス許可] を選択し、GetList にチェック マークがあることを確認します。
    4. [OK] を選択して変更を保存します。
  3. [変数グループ] ページで、[+ 追加] を選択し、コンテナーの特定のシークレットを選択して、この変数グループにマップします。

キー コンテナー シークレットを管理する

以下では、シークレットの管理に役立つヒントをいくつか示します。

  • シークレットの "名前" のみが変数グループにマップされ、シークレットの値はマップされません。 コンテナーからフェッチされた最新のシークレット値が、変数グループにリンクされているパイプライン実行で使用されます。

  • キー コンテナー内の "既存" のシークレットに対して行われた変更は、変数グループが使用されているすべてのパイプラインで自動的に使用できます。

  • コンテナーに新しいシークレットが追加されたり、コンテナーから削除されたりしても、関連付けられている変数グループは自動的には更新されません。 変数グループに含まれるシークレットは、変数グループを使用しているパイプラインが正しく実行されるように、明示的に更新される必要があります。

  • Azure Key Vault では、Azure での暗号化キーとシークレットの格納と管理がサポートされています。 現在、Azure Pipelines 変数グループ統合では、Azure Key Vault のシークレットのみのマッピングがサポートされています。 暗号化キーと証明書はサポートされていません。

グループ内の変数を展開する

グループで変数を設定し、YAML ファイルで使用する場合、その変数は、YAML ファイル内の他の定義された変数と同等です。 変数の優先順位の詳細については、「変数」を参照してください。

TFS では YAML はサポートされていません。