次の方法で共有

変数の定義

  • [アーティクル]

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

変数を使用すると、パイプラインのさまざまな部分に重要なデータを簡単に取り込むことができます。 変数の最も一般的な用途は、パイプラインで使用できる値を定義することです。 すべての変数は文字列であり、変更可能です。 変数の値は、パイプラインの実行ごと、またはジョブごとに変更できます。

同じ名前の複数の場所で同じ変数を定義すると、最もローカルスコープの変数が優先されます。 そのため、ジョブ レベルで定義された変数は、ステージ レベルで設定された変数をオーバーライドできます。 ステージ レベルで定義された変数は、パイプライン ルート レベルで設定された変数をオーバーライドします。 パイプライン ルート レベルで設定された変数は、パイプライン設定 UI で設定された変数をオーバーライドします。 ジョブ、ステージ、ルート レベルで定義された変数を操作する方法の詳細については、「変数スコープ」を参照してください。

変数と 式 を使用して、条件付きで値を割り当て、パイプラインをさらにカスタマイズできます。

変数は ランタイム パラメーターとは異なります。 ランタイム パラメーターは型指定され、テンプレートの解析中に使用できます。

ユーザー定義変数

変数を定義するときは、 さまざまな構文 (マクロ、テンプレート式、またはランタイム) を使用できます。また、使用する構文によって、変数がレンダリングされるパイプライン内の場所が決まります。

YAML パイプラインでは、ルート、ステージ、ジョブ レベルで変数を設定できます。 UI で YAML パイプラインの外部で変数を指定することもできます。 UI で変数を設定すると、その変数を暗号化してシークレットとして設定できます。

ユーザー定義変数は 読み取り専用として設定できます。 変数には名前付けの制限事項があります (例: 変数名の先頭に secret を使用することはできません)。

変数グループを使用 すると、複数のパイプライン間で変数を使用できるようになります。

テンプレート を使用して、複数のパイプラインで使用される 1 つのファイルで変数を定義します。

ユーザー定義の複数行変数

Azure DevOps では複数行の変数がサポートされていますが、いくつかの制限があります。

パイプライン タスクなどのダウンストリーム コンポーネントでは、変数値が正しく処理されない場合があります。

Azure DevOps では、ユーザー定義変数の値は変更されません。 変数値は、複数行の変数として渡す前に、正しく書式設定する必要があります。 変数を書式設定するときは、特殊文字を使用しないようにし、制限付き名前を使用しないでください。また、エージェントのオペレーティング システムに適した行末書式設定を使用してください。

複数行変数の動作は、オペレーティング システムによって異なります。 これを回避するには、複数行の変数がターゲット オペレーティング システムに合わせて正しく書式設定されていることを確認してください。

サポートされていない書式を指定した場合でも、Azure DevOps によって変数値が変更されることはありません。

システム変数

Azure Pipelines には、ユーザー定義変数に加えて、定義済みの値を持つシステム変数があります。 たとえば、定義済みの変数 Build.BuildId は、各ビルドの ID を提供するものであり、異なるパイプライン実行を識別するために使用できます。 一意の値が必要な場合は、スクリプトまたはタスクで Build.BuildId 変数を使用できます。

YAML またはクラシック ビルド パイプラインを使用している場合は、システム変数の包括的なリストについては、「定義済みの変数」をご覧ください。

クラシック リリース パイプラインを使用している場合は、「リリース変数」を参照してください。

パイプラインを実行すると、システム変数に現在の値が設定されます。 一部の変数は自動的に設定されます。 パイプラインの作成者またはエンド ユーザーは、パイプラインを実行する前にシステム変数の値を変更します。

システム変数は読み取り専用です。

環境変数

環境変数は、使用しているオペレーティング システムに固有のものです。 これらは、プラットフォーム固有の方法でパイプラインに挿入されます。 この形式は、環境変数が特定のスクリプト プラットフォーム用に書式設定される方法に対応します。

UNIX システム (macOS および Linux) では、環境変数の形式は $NAME です。 Windows では、バッチの形式は %NAME%、PowerShell の形式は $env:NAME です。

システム変数とユーザー定義変数も、プラットフォームの環境変数として挿入されます。 変数が環境変数に変換されると、変数名は大文字になり、ピリオドはアンダースコアになります。 たとえば、変数名 any.variable は 変数名 $ANY_VARIABLE になります。

環境変数には 変数の名前付けの制限事項 があります (例: 変数名の先頭に secret を使用することはできません)。

変数の名前付けに関する制限事項

ユーザー定義変数と環境変数は、文字、数字、 .、および _ 文字で構成できます。 システムによって予約されている変数のプレフィックスは使用しないでください。 それらは、 endpoint、 input、 secret、 path、および securefileです。 これらの文字列のいずれかで始まる変数 (大文字/小文字の区別に関係なく) は、タスクとスクリプトでは使用できません。

変数の構文を理解する

Azure Pipelines では、マクロ、テンプレート式、ランタイム式の 3 つの異なる方法で変数を参照できます。 各構文は異なる目的で使用でき、それぞれにいくつかの制限があります。

パイプラインでは、ランタイムが開始される前に、テンプレート式変数 (${{ variables.var }}) がコンパイル時に処理されます。 マクロ構文変数 ($(var)) は、タスクの実行前にランタイム中に処理されます。 ランタイム式 ($[variables.var]) も実行時に処理されますが、 条件 と 式で使用することを目的としています。 ランタイム式を使用する場合は、定義の右側全体を占める必要があります。

この例では、変数が更新された後も、テンプレート式に変数の初期値が残っていることがわかります。 マクロ構文変数の値が更新されます。 すべてのテンプレート式変数は、タスクが実行される前のコンパイル時に処理されるため、テンプレート式の値は変更されません。 これに対し、マクロ構文変数は、各タスクを実行する前に評価されます。

variables:
- name: one
  value: initialValue 

steps:
  - script: |
      echo ${{ variables.one }} # outputs initialValue
      echo $(one)
    displayName: First variable pass
  - bash: echo "##vso[task.setvariable variable=one]secondValue"
    displayName: Set new variable value
  - script: |
      echo ${{ variables.one }} # outputs initialValue
      echo $(one) # outputs secondValue
    displayName: Second variable pass

マクロ構文変数

ほとんどのドキュメント例では、マクロ構文 ($(var)) を使用しています。 マクロ構文は、変数の値をタスク入力や他の変数に補間するように設計されています。

マクロ構文を持つ変数は、実行時にタスクが実行される前に処理されます。 ランタイムは、 テンプレートの展開後に発生します。 システムは、マクロ式を検出すると、式を変数の内容に置き換えます。 その名前の変数がない場合、マクロ式は変更されません。 たとえば、 $(var) を置き換えることができない場合、 $(var) は何にも置き換えられません。

マクロ構文変数は、値がなくても変更されません。 $() のような空の値は、実行中のタスクに何か意味があるかもしれず、エージェントはその値の置き換えを望んでいると想定してはいけないからです。 たとえば、 $(foo) を使用して Bash タスクの変数 foo を参照する場合、タスクへの入力内のすべての $() 式を置き換えると、Bash スクリプトが中断される可能性があります。

マクロ変数は、キーワードとしてではなく、値として使用される場合にのみ展開されます。 値は、パイプライン定義の右側に表示されます。 次は有効です: key: $(value)。 次は無効です: $(key): value。 マクロ変数は、ジョブ名をインラインで表示するときに展開されません。 代わりに、 displayName プロパティを使用する必要があります。

注意

マクロ構文変数は、 stages、 jobs、および stepsに対してのみ展開されます。 たとえば、 resource または trigger 内でマクロ構文を使用することはできません。

この例では、Bash、PowerShell、およびスクリプト タスクでマクロ構文を使用します。 マクロ構文を使用して変数を呼び出す構文は、3 つすべてで同じです。

variables:
 - name: projectName
   value: contoso

steps: 
- bash: echo $(projectName)
- powershell: echo $(projectName)
- script: echo $(projectName)

テンプレート式の構文

テンプレート式の構文を使用して、 テンプレート パラメーター と変数 (${{ variables.var }}) の両方を展開できます。 テンプレート変数はコンパイル時に処理され、ランタイムが開始される前に置き換えられます。 テンプレート式は、YAML の一部をテンプレートとして再利用するために設計されています。

置換値が見つからない場合、テンプレート変数は自動的に空の文字列に結合されます。 テンプレート式は、マクロ式やランタイム式とは異なり、キー (左側) または値 (右側) として表示できます。 次は有効です: ${{ variables.key }} : ${{ variables.value }}。

ランタイム式の構文

ランタイム ($[variables.var]) に展開される変数には、ランタイム式構文を使用できます。 置換値が見つからない場合、ランタイム式変数は自動的に空の文字列に結合されます。 ジョブ条件でランタイム式を使用して、ジョブまたはステージ全体の条件付き実行をサポートします。

ランタイム式変数は、キーワードとしてではなく、値として使用される場合にのみ展開されます。 値は、パイプライン定義の右側に表示されます。 次は有効です: key: $[variables.value]。 次は無効です: $[variables.key]: value。 ランタイム式は、キーと値のペアの右側全体を占める必要があります。 たとえば、 key: $[variables.value] は有効ですが、 key: $[variables.value] foo は有効ではありません。

構文 例 いつ処理されますか? パイプライン定義のどこで展開されますか? 見つからない場合、どのようにレンダリングされますか?
マクロ $(var) タスクが実行される前のランタイム 値 (右側) $(var) を出力します
テンプレート式 ${{ variables.var }} コンパイル時間 (compile time) キーまたは値 (左側または右側) 空の文字列
ランタイム式 $[variables.var] ランタイム 値 (右側) 空の文字列

どのような構文を使用する必要がありますか?

セキュリティで保護された文字列または 定義済みの変数 入力をタスクに指定する場合は、マクロ構文を使用します。

条件 と 式を使用している場合は、ランタイム式を選択します。 ただし、空の変数を出力しない場合は、ランタイム式を使用しないでください (例: $[variables.var])。 たとえば、特定の値を持つ変数または値を持たない変数に依存する条件付きロジックがある場合です。 その場合は、マクロ式を使用する必要があります。

通常、テンプレート変数は使用する標準です。 テンプレート変数を利用することで、パイプラインはパイプラインのコンパイル時に変数の値をパイプラインに完全に挿入します。 これは、パイプラインをデバッグする際に役立ちます。 ログ ファイルをダウンロードし、置き換えられる完全に展開された値を評価できます。 変数は置き換えられることから、機密性の高い値にテンプレート構文を利用しないでください。

パイプラインで変数を設定する

最も一般的なケースでは、変数を設定し、YAML ファイル内でそれらを使用します。 これにより、バージョン コントロール システムで変数への変更を追跡できます。 パイプライン設定 UI で変数を定義し ([クラシック] タブを参照)、YAML で参照することもできます。

2 つの変数 configuration と platform を設定し、後のステップで使用する方法を次に示します。 YAML ステートメントで変数を使用するには、 $()でラップします。 変数を使用して YAML ステートメントで repository を定義することはできません。

# Set variables once
variables:
  configuration: debug
  platform: x64

steps:

# Use them once
- task: MSBuild@1
  inputs:
    solution: solution1.sln
    configuration: $(configuration) # Use the variable
    platform: $(platform)

# Use them again
- task: MSBuild@1
  inputs:
    solution: solution2.sln
    configuration: $(configuration) # Use the variable
    platform: $(platform)

変数スコープ

YAML ファイルでは、さまざまなスコープで変数を設定できます。

  • ルート レベルで、パイプライン内のすべてのジョブで使用できるようにします。
  • ステージ レベルでは、特定のステージでのみ使用できるようにします。
  • ジョブ レベルでは、特定のジョブでのみ使用できるようにします。

YAML の先頭で変数を定義すると、その変数はパイプライン内のすべてのジョブとステージで使用でき、グローバル変数になります。 YAML で定義されたグローバル変数は、パイプライン設定 UI には表示されません。

ジョブ レベルの変数は、ルート レベルとステージ レベルの変数をオーバーライドします。 ステージ レベルの変数は、ルート レベルで変数をオーバーライドします。

variables:
  global_variable: value    # this is available to all jobs

jobs:
- job: job1
  pool:
    vmImage: 'ubuntu-latest'
  variables:
    job_variable1: value1    # this is only available in job1
  steps:
  - bash: echo $(global_variable)
  - bash: echo $(job_variable1)
  - bash: echo $JOB_VARIABLE1 # variables are available in the script environment too

- job: job2
  pool:
    vmImage: 'ubuntu-latest'
  variables:
    job_variable2: value2    # this is only available in job2
  steps:
  - bash: echo $(global_variable)
  - bash: echo $(job_variable2)
  - bash: echo $GLOBAL_VARIABLE

両方のジョブからの出力は次のようになります。

# job1
value 
value1
value1

# job2
value
value2
value

変数を指定する

前の例では、variables キーワードの後にキーと値のペアの一覧が続きます。 キーは変数名であり、値は変数の値です。

変数または 変数グループの テンプレート を使用する場合に便利な別の構文があります。

テンプレートを使用すると、複数の変数を 1 つの YAML で定義し、別のテンプレートに含めることができます。

変数グループは、複数のパイプラインで使用できる変数セットです。 これにより、さまざまなステージに共通する変数の管理と整理が 1 か所でできます。

この構文は、パイプラインのルート レベルの変数テンプレートと変数グループに使用します。

この代替構文では、 variables キーワードは変数指定子のリストを受け取ります。 変数指定子は、通常の変数の場合は name、変数グループの場合は group、変数テンプレートを含める場合は template です。 次の例は、3 つすべての使用方法を示したものです。

variables:
# a regular variable
- name: myvariable
  value: myvalue
# a variable group
- group: myvariablegroup
# a reference to a variable template
- template: myvariabletemplate.yml

テンプレートを使用した変数の再利用の詳細を参照してください。

環境を介して変数にアクセスする

変数は、環境変数を使用してスクリプトでも使用できるようになることに注意してください。 これらの環境変数を使用するための構文は、スクリプト言語によって異なります。

名前は大文字で、 . は _に置き換えられます。 これはプロセス環境に自動的に挿入されます。 次に例をいくつか示します。

  • バッチ スクリプト: %VARIABLE_NAME%
  • PowerShell スクリプト: $env:VARIABLE_NAME
  • Bash スクリプト: $VARIABLE_NAME

重要

ファイル パスを含む定義済みの変数は、エージェントのホストの種類とシェルの種類に基づいて、適切なスタイル (Windows スタイル C:\foo\ と Unix スタイル /foo/) に変換されます。 Windows で bash スクリプト タスクを実行している場合は、パイプライン変数メソッドではなく環境変数メソッドを使用してこれらの変数にアクセスし、ファイル パスのスタイルが正しいことを確認する必要があります。

シークレット変数を設定する

ヒント

シークレット変数は、環境変数として自動的にエクスポートされません。 スクリプトでシークレット変数を使用するには、それらを環境変数に明示的にマップします。 詳細については、「シークレット変数を設定する」を参照してください。

YAML ファイルにシークレット変数を設定しないでください。 オペレーティング システムでは、実行するプロセスのコマンドをログに記録することがよくありますが、入力として渡したシークレットがログに含まれないようにします。 スクリプトの環境を使用するか、 variables ブロック内の変数をマップして、シークレットをパイプラインに渡します。

注意

Azure Pipelines は、パイプライン ログにデータを出力するときにシークレットをマスクする作業を行うため、シークレットとして設定されていない出力とログに追加でマスクされた変数とデータが表示される場合があります。

パイプラインのパイプライン設定 UI でシークレット変数を設定する必要があります。 これらの変数のスコープは、設定されているパイプラインに限定されます。 また、 変数グループにシークレット変数を設定することもできます。

Web インターフェイスでシークレットを設定するには、次の手順に従います。

  1. [パイプライン] ページにアクセスし、適切なパイプラインを選択して、 [編集]を選択します。
  2. このパイプラインの [変数] を探します。
  3. 変数を追加または更新します。
  4. 変数を暗号化して保存するには、 この値を秘密にする オプションを選択します。
  5. パイプラインを保存します。

シークレット変数は、2048 ビット RSA キーを使用して保存時に暗号化されます。 エージェントで使用するタスクとスクリプトに対してシークレットを利用できます。 パイプラインを変更するアクセス権を持つユーザーには注意してください。

重要

Azure Pipelines の出力に表示されないようにシークレットのマスクに努めますが、引き続き予防策を講じる必要があります。 シークレットを出力としてエコーしないでください。 一部のオペレーティング システムでは、コマンド ライン引数がログに記録されます。 コマンド ラインでシークレットを渡さないでください。 代わりに、シークレットを環境変数にマップすることをお勧めします。

シークレットの部分文字列をマスクすることはありません。 たとえば、"abc123" がシークレットとして設定されている場合、"abc" はログからマスクされません。 これは、レベルが細かすぎてログが読み取れなくなるシークレットのマスクを回避するためです。 このため、シークレットには構造化データを含めることはできません。 たとえば、"{ "foo": "bar" }" がシークレットとして設定されている場合、"bar" はログからマスクされません。

通常の変数とは異なり、スクリプトの環境変数には自動的に復号化されません。 シークレット変数を明示的にマップする必要があります。

次の例は、PowerShell スクリプトと Bash スクリプトで mySecret と呼ばれるシークレット変数をマップして使用する方法を示しています。 2 つのグローバル変数が定義されています。 GLOBAL_MYSECRET にはシークレット変数 mySecret の値が割り当てられ、 GLOBAL_MY_MAPPED_ENV_VAR にはシークレット以外の変数 nonSecretVariable の値が割り当てられます。 通常のパイプライン変数とは異なり、 MYSECRETという環境変数はありません。

PowerShell タスクは、変数を印刷するスクリプトを実行します。

  • $(mySecret): これはシークレット変数への直接参照であり、機能します。
  • $env:MYSECRET: これは環境変数としてシークレット変数へのアクセスを試みますが、シークレット変数は環境変数に自動的にマップされないため、機能しません。
  • $env:GLOBAL_MYSECRET: これはグローバル変数を介してシークレット変数へのアクセスを試みますが、シークレット変数はこのようにマップできないため、これも機能しません。
  • $env:GLOBAL_MY_MAPPED_ENV_VAR: これはグローバル変数を介してシークレット以外の変数にアクセスします。機能します。
  • $env:MY_MAPPED_ENV_VAR: これはタスク固有の環境変数を介してシークレット変数にアクセスします。シークレット変数を環境変数にマップするための推奨される方法です。
variables:
 GLOBAL_MYSECRET: $(mySecret) # this will not work because the secret variable needs to be mapped as env
 GLOBAL_MY_MAPPED_ENV_VAR: $(nonSecretVariable) # this works because it's not a secret.

steps:

- powershell: |
    Write-Host "Using an input-macro works: $(mySecret)"
    Write-Host "Using the env var directly does not work: $env:MYSECRET"
    Write-Host "Using a global secret var mapped in the pipeline does not work either: $env:GLOBAL_MYSECRET"
    Write-Host "Using a global non-secret var mapped in the pipeline works: $env:GLOBAL_MY_MAPPED_ENV_VAR" 
    Write-Host "Using the mapped env var for this task works and is recommended: $env:MY_MAPPED_ENV_VAR"
  env:
    MY_MAPPED_ENV_VAR: $(mySecret) # the recommended way to map to an env variable

- bash: |
    echo "Using an input-macro works: $(mySecret)"
    echo "Using the env var directly does not work: $MYSECRET"
    echo "Using a global secret var mapped in the pipeline does not work either: $GLOBAL_MYSECRET"
    echo "Using a global non-secret var mapped in the pipeline works: $GLOBAL_MY_MAPPED_ENV_VAR" 
    echo "Using the mapped env var for this task works and is recommended: $MY_MAPPED_ENV_VAR"
  env:
    MY_MAPPED_ENV_VAR: $(mySecret) # the recommended way to map to an env variable

上記のスクリプトの両方のタスクからの出力は次のようになります。

Using an input-macro works: ***
Using the env var directly does not work:
Using a global secret var mapped in the pipeline does not work either:
Using a global non-secret var mapped in the pipeline works: foo
Using the mapped env var for this task works and is recommended: ***

スクリプトの外部でシークレット変数を使用することもできます。 たとえば、 variables 定義を使用して、シークレット変数をタスクにマップできます。 この例では、シークレット変数 $(vmsUser) と $(vmsAdminPass) を Azure ファイル コピー タスクで使用する方法を示します。

variables:
  VMS_USER: $(vmsUser)
  VMS_PASS: $(vmsAdminPass)

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: AzureFileCopy@4
  inputs:
    SourcePath: 'my/path'
    azureSubscription: 'my-subscription'
    Destination: 'AzureVMs'
    storage: 'my-storage'
    resourceGroup: 'my-rg'
    vmsAdminUserName: $(VMS_USER)
    vmsAdminPassword: $(VMS_PASS)

変数グループのシークレット変数を参照する

この例では、YAML ファイルで変数グループを参照する方法と、YAML 内で変数を追加する方法を示します。 変数グループからは 2 つの変数 user と token が使用されています。 token 変数はシークレットであり、YAML で参照できるように環境変数 $env:MY_MAPPED_TOKEN にマップされます。

この YAML は REST 呼び出しを行ってリリースの一覧を取得し、結果を出力します。

variables: 
- group: 'my-var-group' # variable group
- name: 'devopsAccount' # new variable defined in YAML
  value: 'contoso'
- name: 'projectName' # new variable defined in YAML
  value: 'contosoads'

steps:
- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: |
        # Encode the Personal Access Token (PAT)
        # $env:USER is a normal variable in the variable group
        # $env:MY_MAPPED_TOKEN is a mapped secret variable
        $base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $env:USER,$env:MY_MAPPED_TOKEN)))

        # Get a list of releases
        $uri = "https://vsrm.dev.azure.com/$(devopsAccount)/$(projectName)/_apis/release/releases?api-version=5.1"

        # Invoke the REST call
        $result = Invoke-RestMethod -Uri $uri -Method Get -ContentType "application/json" -Headers @{Authorization=("Basic {0}" -f $base64AuthInfo)}

        # Output releases in JSON
        Write-Host $result.value
  env:
    MY_MAPPED_TOKEN: $(token) # Maps the secret variable $(token) from my-var-group

重要

GitHub リポジトリでは、既定では、パイプラインに関連付けられているシークレット変数は、フォークの pull request ビルドでは使用できません。 詳細については、「フォークからのコントリビューション」を参照してください。

パイプライン間で変数を共有する

プロジェクト内の複数のパイプライン間で変数を共有するには、Web インターフェイスを使用します。 [ライブラリ] で、 [変数グループ] を使用します。

タスクからの出力変数を使用する

一部のタスクでは、ダウンストリーム ステップ、ジョブ、ステージで使用できる出力変数を定義します。 YAML では、依存関係を使用して、ジョブやステージ間で変数にアクセスできます。

ダウンストリーム タスクでマトリックス ジョブを参照する場合は、別の構文を使用する必要があります。 「複数ジョブ出力変数を設定する」を参照してください。 また、デプロイ ジョブの変数には別の構文を使用する必要があります。 「デプロイ ジョブでの出力変数のサポート」を参照してください。

一部のタスクでは出力変数を定義します。これは、同じステージ内のダウンストリームのステップおよびジョブで使用できます。 YAML では、 依存関係を使用して、ジョブ間で変数にアクセスできます。

  • 同じジョブ内の別のタスクから変数を参照するには、 TASK.VARIABLEを使用します。
  • 別のジョブのタスクから変数を参照するには、 dependencies.JOB.outputs['TASK.VARIABLE']を使用します。

注意

既定では、パイプライン内の各ステージは、YAML ファイル内の直前のステージによって異なります。 現在のステージの直前ではないステージを参照する必要がある場合は、ステージに dependsOn セクションを追加することで、この自動既定値をオーバーライドできます。

注意

次の例では、標準パイプライン構文を使います。 配置パイプラインを使っている場合、変数と条件変数の構文は両方とも異なります。 使用する特定の構文の詳細については、「デプロイ ジョブ」を参照してください。

これらの例では、 MyVarという出力変数を設定する MyTaskというタスクがあると仮定します。 構文の詳細については、「式 - 依存関係」を参照してください。

同じジョブで出力を使用する

steps:
- task: MyTask@1  # this step generates the output variable
  name: ProduceVar  # because we're going to depend on it, we need to name the step
- script: echo $(ProduceVar.MyVar) # this step uses the output variable

別のジョブで出力を使用する

jobs:
- job: A
  steps:
  # assume that MyTask generates an output variable called "MyVar"
  # (you would learn that from the task's documentation)
  - task: MyTask@1
    name: ProduceVar  # because we're going to depend on it, we need to name the step
- job: B
  dependsOn: A
  variables:
    # map the output variable from A into this job
    varFromA: $[ dependencies.A.outputs['ProduceVar.MyVar'] ]
  steps:
  - script: echo $(varFromA) # this step uses the mapped-in variable

別のステージで出力を使用する

別のステージの出力を使用するには、変数を参照する形式を stageDependencies.STAGE.JOB.outputs['TASK.VARIABLE'] にします。 ジョブ レベルでは使用できませんが、ステージ レベルでは条件での変数の使用ができます。

出力変数は、次のダウンストリーム ステージでのみ使用できます。 複数のステージで同じ出力変数を使用する場合は、 dependsOn 条件を使用します。

stages:
- stage: One
  jobs:
  - job: A
    steps:
    - task: MyTask@1  # this step generates the output variable
      name: ProduceVar  # because we're going to depend on it, we need to name the step

- stage: Two
  dependsOn:
  - One
  jobs:
  - job: B
    variables:
      # map the output variable from A into this job
      varFromA: $[ stageDependencies.One.A.outputs['ProduceVar.MyVar'] ]
    steps:
    - script: echo $(varFromA) # this step uses the mapped-in variable

- stage: Three
  dependsOn:
  - One
  - Two
  jobs:
  - job: C
    variables:
      # map the output variable from A into this job
      varFromA: $[ stageDependencies.One.A.outputs['ProduceVar.MyVar'] ]
    steps:
    - script: echo $(varFromA) # this step uses the mapped-in variable

ファイル入力を使用してステージ間で変数を渡すこともできます。 そのためには、ジョブ レベルの第 2 ステージで変数を定義し、その変数を env: 入力として渡す必要があります。

## script-a.sh
echo "##vso[task.setvariable variable=sauce;isOutput=true]crushed tomatoes"

## script-b.sh
echo 'Hello file version'
echo $skipMe
echo $StageSauce

## azure-pipelines.yml
stages:

- stage: one
  jobs:
  - job: A
    steps:
    - task: Bash@3
      inputs:
          filePath: 'script-a.sh'
      name: setvar
    - bash: |
       echo "##vso[task.setvariable variable=skipsubsequent;isOutput=true]true"
      name: skipstep

- stage: two
  jobs:
  - job: B
    variables:
      - name: StageSauce
        value: $[ stageDependencies.one.A.outputs['setvar.sauce'] ]
      - name: skipMe
        value: $[ stageDependencies.one.A.outputs['skipstep.skipsubsequent'] ]
    steps:
    - task: Bash@3
      inputs:
        filePath: 'script-b.sh'
      name: fileversion
      env:
        StageSauce: $(StageSauce) # predefined in variables section
        skipMe: $(skipMe) # predefined in variables section
    - task: Bash@3
      inputs:
        targetType: 'inline'
        script: |
          echo 'Hello inline version'
          echo $(skipMe) 
          echo $(StageSauce)

前のパイプラインのステージからの出力は次のようになります。

Hello inline version
true
crushed tomatoes

変数を一覧表示する

az pipelines variable list コマンドを使用して、パイプライン内のすべての変数を一覧表示できます。 開始するには、「Azure DevOps CLI の概要」を参照してください。

az pipelines variable list [--org]
                           [--pipeline-id]
                           [--pipeline-name]
                           [--project]

パラメーター

  • org: Azure DevOps 組織の URL。 az devops configure -d organization=ORG_URL を使用して、既定の組織を構成できます。 既定として設定されていない場合、または git config を使用して取得された場合は必須です。 例: --org https://dev.azure.com/MyOrganizationName/.
  • pipeline-id: pipeline-name が指定されていない場合は必須です。 パイプラインの ID。
  • pipeline-name: pipeline-id が指定されていない場合は必須ですが、 pipeline-id が指定されている場合は無視されます。 パイプラインの名前。
  • project: プロジェクトの名前または ID。 az devops configure -d project=NAME_OR_ID を使用して、既定のプロジェクトを構成できます。 既定として設定されていない場合、または git config を使用して取得された場合は必須です。

例

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

az pipelines variable list --pipeline-id 12 --output table

Name           Allow Override    Is Secret    Value
-------------  ----------------  -----------  ------------
MyVariable     False             False        platform
NextVariable   False             True         platform
Configuration  False             False        config.debug

スクリプトで変数を設定する

スクリプトでは、パイプラインの後続のステップで使用される変数を定義できます。 このメソッドによって設定されたすべての変数は、文字列として扱われます。 スクリプトから変数を設定するには、コマンド構文を使用して stdout に出力します。

スクリプトからジョブ スコープ変数を設定する

スクリプトから変数を設定するには、ログ記録コマンド task.setvariable を使用します。 これにより、後続のジョブの環境変数が更新されます。 後続のジョブは、 マクロ構文 とタスク内の環境変数を使用して、新しい変数にアクセスできます。

issecret が true に設定されている場合、変数の値はシークレットとして保存され、ログからマスクされます。 シークレット変数の詳細については、「ログ コマンド」を参照してください。

steps:
# Create a variable
- bash: |
    echo "##vso[task.setvariable variable=sauce]crushed tomatoes" # remember to use double quotes

# Use the variable
# "$(sauce)" is replaced by the contents of the `sauce` variable by Azure Pipelines
# before handing the body of the script to the shell.
- bash: |
    echo my pipeline variable is $(sauce)

後続の手順では、パイプライン変数も環境に追加されます。 変数は、定義されているステップでは使用できません。

steps:
# Create a variable
# Note that this does not update the environment of the current script.
- bash: |
    echo "##vso[task.setvariable variable=sauce]crushed tomatoes"

# An environment variable called `SAUCE` has been added to all downstream steps
- bash: |
    echo "my environment variable is $SAUCE"
- pwsh: |
    Write-Host "my environment variable is $env:SAUCE"

前のパイプラインからの出力。

my environment variable is crushed tomatoes
my environment variable is crushed tomatoes

複数ジョブ出力変数を設定する

変数を今後のジョブで使用できるようにするには、 isOutput=trueを使用してその変数を出力変数としてマークする必要があります。 その後、 $[] 構文を使用し、変数を設定するステップ名を含めることで、それを今後のジョブにマップできます。 複数ジョブ出力変数は、同じステージ内のジョブに対してのみ機能します。

異なるステージのジョブに変数を渡すには、 ステージの依存関係 構文を使用します。

注意

既定では、パイプライン内の各ステージは、YAML ファイル内の直前のステージによって異なります。 したがって、各ステージでは、前のステージの出力変数を使用できます。 さらにステージにアクセスするには、依存関係グラフを変更する必要があります。たとえば、ステージ 3 にステージ 1 の変数が必要な場合は、ステージ 1 に明示的な依存関係を宣言する必要があります。

複数ジョブ出力変数を作成する場合は、式を変数に割り当てる必要があります。 この YAML では、 $[ dependencies.A.outputs['setvarStep.myOutputVar'] ] が変数 $(myVarFromJobA)に割り当てられます。

jobs:
# Set an output variable from job A
- job: A
  pool:
    vmImage: 'windows-latest'
  steps:
  - powershell: echo "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is the value"
    name: setvarStep
  - script: echo $(setvarStep.myOutputVar)
    name: echovar

# Map the variable into job B
- job: B
  dependsOn: A
  pool:
    vmImage: 'ubuntu-latest'
  variables:
    myVarFromJobA: $[ dependencies.A.outputs['setvarStep.myOutputVar'] ]  # map in the variable
                                                                          # remember, expressions require single quotes
  steps:
  - script: echo $(myVarFromJobA)
    name: echovar

前のパイプラインからの出力。

this is the value
this is the value

あるステージから別のステージに変数を設定する場合は、stageDependencies を使用します。

stages:
- stage: A
  jobs:
  - job: A1
    steps:
     - bash: echo "##vso[task.setvariable variable=myStageOutputVar;isOutput=true]this is a stage output var"
       name: printvar

- stage: B
  dependsOn: A
  variables:
    myVarfromStageA: $[ stageDependencies.A.A1.outputs['printvar.myStageOutputVar'] ]
  jobs:
  - job: B1
    steps:
    - script: echo $(myVarfromStageA)

マトリックス または スライスから変数を設定する場合、ダウンストリーム ジョブからその変数にアクセスするときに変数を参照するには、次を含める必要があります。

  • ジョブの名前。
  • ステップ。
jobs:

# Set an output variable from a job with a matrix
- job: A
  pool:
    vmImage: 'ubuntu-latest'
  strategy:
    maxParallel: 2
    matrix:
      debugJob:
        configuration: debug
        platform: x64
      releaseJob:
        configuration: release
        platform: x64
  steps:
  - bash: echo "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is the $(configuration) value"
    name: setvarStep
  - bash: echo $(setvarStep.myOutputVar)
    name: echovar

# Map the variable from the debug job
- job: B
  dependsOn: A
  pool:
    vmImage: 'ubuntu-latest'
  variables:
    myVarFromJobADebug: $[ dependencies.A.outputs['debugJob.setvarStep.myOutputVar'] ]
  steps:
  - script: echo $(myVarFromJobADebug)
    name: echovar

jobs:

# Set an output variable from a job with slicing
- job: A
  pool:
    vmImage: 'ubuntu-latest'
    parallel: 2 # Two slices
  steps:
  - bash: echo "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is the slice $(system.jobPositionInPhase) value"
    name: setvarStep
  - script: echo $(setvarStep.myOutputVar)
    name: echovar

# Map the variable from the job for the first slice
- job: B
  dependsOn: A
  pool:
    vmImage: 'ubuntu-latest'
  variables:
    myVarFromJobsA1: $[ dependencies.A.outputs['job1.setvarStep.myOutputVar'] ]
  steps:
  - script: "echo $(myVarFromJobsA1)"
    name: echovar

デプロイ ジョブの出力変数には必ずジョブ名をプレフィックスとして付けてください。 この場合、ジョブ名は A です。

jobs:

# Set an output variable from a deployment
- deployment: A
  pool:
    vmImage: 'ubuntu-latest'
  environment: staging
  strategy:
    runOnce:
      deploy:
        steps:
        - bash: echo "##vso[task.setvariable variable=myOutputVar;isOutput=true]this is the deployment variable value"
          name: setvarStep
        - bash: echo $(setvarStep.myOutputVar)
          name: echovar

# Map the variable from the job for the first slice
- job: B
  dependsOn: A
  pool:
    vmImage: 'ubuntu-latest'
  variables:
    myVarFromDeploymentJob: $[ dependencies.A.outputs['A.setvarStep.myOutputVar'] ]
  steps:
  - bash: "echo $(myVarFromDeploymentJob)"
    name: echovar

式を使用して変数を設定する

式を使用して変数を設定できます。 変数を前のジョブから別のジョブの出力に設定するというこのケースは既に 1 件発生しました。

- job: B
  dependsOn: A
  variables:
    myVarFromJobsA1: $[ dependencies.A.outputs['job1.setvarStep.myOutputVar'] ] # remember to use single quotes

変数の設定には、サポートされている任意の式を使用できます。 100 から始まり、実行ごとに 1 ずつインクリメントされ、毎日 100 にリセットされるカウンターとして機能するように変数を設定する例を次に示します。

jobs:
- job:
  variables:
    a: $[counter(format('{0:yyyyMMdd}', pipeline.startTime), 100)]
  steps:
  - bash: echo $(a)

カウンター、依存関係、およびその他の式の詳細については、「式」を参照してください。

ステップの設定可能な変数を構成する

ステップ内で settableVariables を定義することも、変数を設定できないように指定することもできます。

この例では、スクリプトで変数を設定することはできません。

steps:
- script: echo This is a step
  target:
    settableVariables: none

この例では、スクリプトは変数 sauce を許可しますが、変数 secretSauce は許可しません。 パイプラインの実行ページに警告が表示されます。

secretSauce を設定できないことについての警告。 

steps:
  - bash: |
      echo "##vso[task.setvariable variable=Sauce;]crushed tomatoes"
      echo "##vso[task.setvariable variable=secretSauce;]crushed tomatoes with garlic"
    target:
     settableVariables:
      - sauce
    name: SetVars
  - bash: 
      echo "Sauce is $(sauce)"
      echo "secretSauce is $(secretSauce)"
    name: OutputVars

キュー時に許可する

変数が YAML ファイルの variables ブロックに表示される場合、その値は固定され、キュー時にオーバーライドすることはできません。 ベスト プラクティスは、YAML ファイルで変数を定義することですが、これが意味をなさない場合があります。 たとえば、シークレット変数を定義し、その変数を YAML で公開しないようにできます。 または、パイプラインの実行中に変数値を手動で設定することが必要な場合があります。

キュー時の値を定義するには 2 つのオプションがあります。 UI で変数を定義し、 [このパイプラインの実行時に、ユーザーがこの値をオーバーライドできるようにする] オプションを選択することも、代わりに ランタイム パラメーター を使用することもできます。 変数がシークレットでない場合のベスト プラクティスは、 ランタイム パラメーターを使用することです。

キュー時に変数を設定するには、パイプライン内に新しい変数を追加し、オーバーライド オプションを選択します。

キュー時に変数を設定します。

キュー時に変数を設定できるようにするには、その変数がパイプラインまたはジョブの variables ブロックにも表示されないようにしてください。 YAML の変数ブロックと UI の両方で変数を定義する場合、YAML の値が優先されます。

変数の拡張

複数のスコープで同じ名前の変数を設定すると、次の優先順位が適用されます (優先順位が最も高いものが最初です)。

  1. YAML ファイルに設定されたジョブ レベル変数
  2. YAML ファイルに設定されたステージ レベル変数
  3. YAML ファイルに設定されたパイプライン レベル変数
  4. キュー時に設定された変数
  5. パイプライン設定 UI で設定されたパイプライン変数

次の例では、YAML ファイルのパイプライン レベルとジョブ レベルで同じ変数 a が設定されています。 また、変数グループ G に設定され、パイプライン設定 UI の変数として設定されます。

variables:
  a: 'pipeline yaml'

stages:
- stage: one
  displayName: one
  variables:
  - name: a
    value: 'stage yaml'

  jobs:
  - job: A
    variables:
    - name: a
      value: 'job yaml'
    steps:
    - bash: echo $(a)        # This will be 'job yaml'

同じスコープに同じ名前の変数を設定すると、最後に設定した値が優先されます。

stages:
- stage: one
  displayName: Stage One
  variables: 
    - name: a
      value: alpha
    - name: a
      value: beta
  jobs: 
  - job: I
    displayName: Job I
    variables:
      - name: b
        value: uno
      - name: b
        value: dos
    steps: 
    - script: echo $(a) #outputs beta
    - script: echo $(b) #outputs dos

Note

YAML ファイルで変数を設定する場合は、Web エディターでキュー時に設定可能として変数を定義しないでください。 現在、キュー時に YAML ファイルで設定されている変数を変更することはできません。 キュー時に変数を設定可能にする必要がある場合は、YAML ファイルで設定しないでください。

変数は、実行の開始時に 1 回展開され、各ステップの開始時にもう一度展開されます。 次に例を示します。

jobs:
- job: A
  variables:
    a: 10
  steps:
  - bash: |
      echo $(a)            # This will be 10
      echo '##vso[task.setvariable variable=a]20'
      echo $(a)            # This will also be 10, since the expansion of $(a) happens before the step
  - bash: echo $(a)        # This will be 20, since the variables are expanded just before the step

前の例には 2 つのステップがあります。 $(a) の拡張は、ジョブの開始時に 1 回、2 つのステップの開始時に 1 回行われます。

変数はジョブの開始時に展開されるため、戦略で使用することはできません。 次の例では、変数 a を使用してジョブ マトリックスを展開することはできません。これは、変数が、展開された各ジョブの開始時でのみ使用できるためです。

jobs:
- job: A
  variables:
    a: 10
  strategy:
    matrix:
      x:
        some_variable: $(a)    # This does not work

変数 a が前のジョブからの出力変数である場合は、将来のジョブで使用できます。

- job: A
  steps:
  - powershell: echo "##vso[task.setvariable variable=a;isOutput=true]10"
    name: a_step

# Map the variable into job B
- job: B
  dependsOn: A
  variables:
    some_variable: $[ dependencies.A.outputs['a_step.a'] ]

再帰的な展開

エージェントでは、 $( ) 構文を使用して参照される変数が再帰的に展開されます。 次に例を示します。

variables:
  myInner: someValue
  myOuter: $(myInner)

steps:
- script: echo $(myOuter)  # prints "someValue"
  displayName: Variable is $(myOuter)  # display name is "Variable is someValue"