パイプラインにジョブを指定する

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

注意

Microsoft Team Foundation Server (TFS) 2018 以前のバージョンでは、ビルドとリリースの "パイプライン" は "定義"、"実行" は "ビルド"、"サービス接続" は "サービス エンドポイント"、"ステージ" は "環境"、"ジョブ" は "フェーズ" と呼ばれます。

パイプラインをジョブに整理できます。 すべてのパイプラインには、少なくとも 1 つのジョブがあります。 ジョブは、1 つのユニットとして順番に実行される一連のステップです。 つまり、ジョブは、実行するようにスケジュールできる最小の作業単位です。

ビルドまたはリリース パイプラインをジョブに整理することができます。 すべてのパイプラインには、少なくとも 1 つのジョブがあります。 ジョブは、1 つのユニットとして順番に実行される一連のステップです。 つまり、ジョブは、実行するようにスケジュールできる最小の作業単位です。

注意

ビルド プロセスでジョブを使用するには、TFS 2018.2 をインストールする必要があります。 TFS 2018 RTM では、リリース展開プロセスでジョブを使用できます。

1 つのジョブを定義する

最も単純な場合、パイプラインには 1 つのジョブがあります。 その場合、テンプレートを使用しない限り、 キーワードをjob明示的に使用する必要はありません。 YAML ファイルで手順を直接指定できます。

この YAML ファイルには、Microsoftホステッド エージェントで実行され、 が出力されるジョブがありますHello world

pool:
  vmImage: 'ubuntu-latest'
steps:
- bash: echo "Hello world"

そのジョブに追加のプロパティを指定することもできます。 その場合は、 キーワードを job 使用できます。

jobs:
- job: myJob
  timeoutInMinutes: 10
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - bash: echo "Hello world"

パイプラインに複数のジョブが含まれる場合があります。 その場合は、 キーワードを使用します jobs

jobs:
- job: A
  steps:
  - bash: echo "A"

- job: B
  steps:
  - bash: echo "B"

パイプラインには複数のステージがあり、それぞれが複数のジョブを持つ場合があります。 その場合は、 キーワードを使用します stages

stages:
- stage: A
  jobs:
  - job: A1
  - job: A2

- stage: B
  jobs:
  - job: B1
  - job: B2

ジョブを指定する完全な構文は次のとおりです。

- job: string  # name of the job, A-Z, a-z, 0-9, and underscore
  displayName: string  # friendly name to display in the UI
  dependsOn: string | [ string ]
  condition: string
  strategy:
    parallel: # parallel strategy
    matrix: # matrix strategy
    maxParallel: number # maximum number simultaneous matrix legs to run
    # note: `parallel` and `matrix` are mutually exclusive
    # you may specify one or the other; including both is an error
    # `maxParallel` is only valid with `matrix`
  continueOnError: boolean  # 'true' if future jobs should run even if this job fails; defaults to 'false'
  pool: pool # agent pool
  workspace:
    clean: outputs | resources | all # what to clean up before the job runs
  container: containerReference # container to run this job inside
  timeoutInMinutes: number # how long to run the job before automatically cancelling
  cancelTimeoutInMinutes: number # how much time to give 'run always even if cancelled tasks' before killing them
  variables: { string: string } | [ variable | variableReference ] 
  steps: [ script | bash | pwsh | powershell | checkout | task | templateReference ]
  services: { string: string | container } # container resources to run as a service container

ジョブを指定する完全な構文は次のとおりです。

- job: string  # name of the job, A-Z, a-z, 0-9, and underscore
  displayName: string  # friendly name to display in the UI
  dependsOn: string | [ string ]
  condition: string
  strategy:
    parallel: # parallel strategy
    matrix: # matrix strategy
    maxParallel: number # maximum number simultaneous matrix legs to run
    # note: `parallel` and `matrix` are mutually exclusive
    # you may specify one or the other; including both is an error
    # `maxParallel` is only valid with `matrix`
  continueOnError: boolean  # 'true' if future jobs should run even if this job fails; defaults to 'false'
  pool: pool # agent pool
  workspace:
    clean: outputs | resources | all # what to clean up before the job runs
  container: containerReference # container to run this job inside
  timeoutInMinutes: number # how long to run the job before automatically cancelling
  cancelTimeoutInMinutes: number # how much time to give 'run always even if cancelled tasks' before killing them
  variables: { string: string } | [ variable | variableReference ] 
  steps: [ script | bash | pwsh | powershell | checkout | task | templateReference ]
  services: { string: string | container } # container resources to run as a service container
  uses: # Any resources (repos or pools) required by this job that are not already referenced
    repositories: [ string ] # Repository references to Azure Git repositories
    pools: [ string ] # Pool names, typically when using a matrix strategy for the job

ジョブの主な目的が (アプリのビルドやテストではなく) アプリをデプロイする場合は、 デプロイ ジョブと呼ばれる特殊な種類のジョブを使用できます。

デプロイ ジョブの構文は次のとおりです。

- deployment: string        # instead of job keyword, use deployment keyword
  pool:
    name: string
    demands: string | [ string ]
  environment: string
  strategy:
    runOnce:
      deploy:
        steps:
        - script: echo Hi!

では展開タスクの手順を job追加できますが、代わりに デプロイ ジョブを使用することをお勧めします。 デプロイ ジョブにはいくつかの利点があります。 たとえば、環境にデプロイできます。これには、デプロイした内容の履歴を表示できるなどの利点が含まれます。

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

ジョブの種類

ジョブの種類は、ジョブの実行場所によって異なります。

  • エージェント プール ジョブはエージェント プール内のエージェント上で実行されます。
  • サーバー ジョブは、Azure DevOps Server で実行されます。
  • コンテナー ジョブ は、エージェント プール内のエージェント上のコンテナーで実行されます。 コンテナーの選択の詳細については、「コンテナー ジョブの定義」を参照してください。
  • エージェント プール ジョブはエージェント プール内のエージェント上で実行されます。
  • サーバー ジョブは、Azure DevOps Server で実行されます。
  • エージェント プール ジョブは 、エージェント プール内のエージェントで実行されます。 これらのジョブは、ビルド パイプラインとリリース パイプラインで使用できます。
  • サーバー ジョブは TFS で実行されます。 これらのジョブは、ビルド パイプラインとリリース パイプラインで使用できます。
  • デプロイ グループ ジョブは、デプロイ グループ内のマシンで実行されます。 これらのジョブは、リリース パイプラインでのみ使用できます。

エージェント プール ジョブ

これらは最も一般的な種類のジョブであり、エージェント プール内のエージェントで実行されます。

  • Microsoftホステッド エージェントを使用する場合、パイプライン内の各ジョブは新しいエージェントを取得します。
  • セルフホステッド エージェントで 要求 を使用して、エージェントがジョブを実行するために必要な機能を指定します。 パイプラインの要求に一致するエージェントプールに複数のエージェントがあるかどうかに応じて、連続するジョブに対して同じエージェントを取得できます。 プール内にパイプラインの要求に一致するエージェントが 1 つしかない場合、パイプラインはこのエージェントが使用可能になるまで待機します。

注意

要求と機能は、ジョブの要件を満たすエージェントとジョブを照合できるように、セルフホステッド エージェントで使用するように設計されています。 Microsoftホステッド エージェントを使用する場合は、ジョブの要件に一致するエージェントのイメージを選択します。そのため、Microsoftホステッド エージェントに機能を追加することはできますが、Microsoftホストされたエージェントで機能を使用する必要はありません。

pool:
  name: myPrivateAgents    # your job runs on an agent in this pool
  demands: agent.os -equals Windows_NT    # the agent must have this capability to run the job
steps:
- script: echo hello world

または、複数の要求:

pool:
  name: myPrivateAgents
  demands:
  - agent.os -equals Darwin
  - anotherCapability -equals somethingElse
steps:
- script: echo hello world

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

エージェント機能の詳細については、こちらを参照してください。

サーバー ジョブ

サーバー ジョブ内のタスクは によって調整され、サーバー (Azure Pipelines または TFS) で実行されます。 サーバー ジョブには、エージェントやターゲット コンピューターは必要ありません。 現時点では、サーバー ジョブでサポートされているタスクはごくわずかです。

エージェントレス ジョブでサポートされているタスク

現在、エージェントレス ジョブでは、次のタスクのみがすぐにサポートされています。

タスクは拡張可能であるため、拡張機能を使用してエージェントレス タスクを追加できます。 エージェントレス ジョブの既定のタイムアウトは 60 分です。

サーバー ジョブを指定する完全な構文は次のとおりです。

jobs:
- job: string
  timeoutInMinutes: number
  cancelTimeoutInMinutes: number
  strategy:
    maxParallel: number
    matrix: { string: { string: string } }

  pool: server # note: the value 'server' is a reserved keyword which indicates this is an agentless job

簡略化された構文を使用することもできます。

jobs:
- job: string
  pool: server # note: the value 'server' is a reserved keyword which indicates this is an agentless job

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

依存関係

1 つのステージで複数のジョブを定義する場合は、それらの間の依存関係を指定できます。 パイプラインには、依存関係のないジョブが少なくとも 1 つ含まれている必要があります。

注意

各エージェントは、一度に 1 つのジョブのみを実行できます。 複数のジョブを並列で実行するには、複数のエージェントを構成する必要があります。 また、十分な 並列ジョブも必要です。

複数のジョブとその依存関係を定義するための構文は次のとおりです。

jobs:
- job: string
  dependsOn: string
  condition: string

順番にビルドされるジョブの例:

jobs:
- job: Debug
  steps:
  - script: echo hello from the Debug build
- job: Release
  dependsOn: Debug
  steps:
  - script: echo hello from the Release build

並列でビルドするジョブの例 (依存関係なし):

jobs:
- job: Windows
  pool:
    vmImage: 'windows-latest'
  steps:
  - script: echo hello from Windows
- job: macOS
  pool:
    vmImage: 'macOS-latest'
  steps:
  - script: echo hello from macOS
- job: Linux
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - script: echo hello from Linux

ファンアウトの例:

jobs:
- job: InitialJob
  steps:
  - script: echo hello from initial job
- job: SubsequentA
  dependsOn: InitialJob
  steps:
  - script: echo hello from subsequent A
- job: SubsequentB
  dependsOn: InitialJob
  steps:
  - script: echo hello from subsequent B

ファンインの例:

jobs:
- job: InitialA
  steps:
  - script: echo hello from initial A
- job: InitialB
  steps:
  - script: echo hello from initial B
- job: Subsequent
  dependsOn:
  - InitialA
  - InitialB
  steps:
  - script: echo hello from subsequent

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

条件

各ジョブを実行する条件を指定できます。 既定では、他のジョブに依存しない場合、または依存するすべてのジョブが完了して成功した場合、ジョブが実行されます。 この動作をカスタマイズするには、前のジョブが失敗した場合でもジョブを強制的に実行するか、カスタム条件を指定します。

前のジョブの実行状態に基づいてジョブを実行する例:

jobs:
- job: A
  steps:
  - script: exit 1

- job: B
  dependsOn: A
  condition: failed()
  steps:
  - script: echo this will run when A fails

- job: C
  dependsOn:
  - A
  - B
  condition: succeeded('B')
  steps:
  - script: echo this will run when B runs and succeeds

カスタム条件の使用例:

jobs:
- job: A
  steps:
  - script: echo hello

- job: B
  dependsOn: A
  condition: and(succeeded(), eq(variables['build.sourceBranch'], 'refs/heads/master'))
  steps:
  - script: echo this only runs for master

ジョブは、前のジョブで設定された出力変数の値に基づいて実行されるように指定できます。 この場合、直接依存ジョブで設定された変数のみを使用できます。

jobs:
- job: A
  steps:
  - script: "echo ##vso[task.setvariable variable=skipsubsequent;isOutput=true]false"
    name: printvar

- job: B
  condition: and(succeeded(), ne(dependencies.A.outputs['printvar.skipsubsequent'], 'true'))
  dependsOn: A
  steps:
  - script: echo hello from B

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

Timeouts

ジョブが応答しない場合や待ち時間が長すぎる場合にリソースを占有しないようにするには、ジョブの実行を許可する時間に制限を設定することをお勧めします。 ジョブのタイムアウト設定を使用して、ジョブを実行するための制限を分単位で指定します。 値を 0 に設定すると、ジョブを実行できます。

  • セルフホステッド エージェントで永遠に
  • パブリック プロジェクトとパブリック リポジトリを使用して、Microsoftホステッド エージェントで 360 分 (6 時間)
  • プライベート プロジェクトまたはプライベート リポジトリを使用するMicrosoftホストされたエージェントで 60 分間 (追加の容量が支払われる場合を除く)

タイムアウト期間は、ジョブの実行が開始されたときに開始されます。 ジョブがキューに入っているか、エージェントを待機している時間は含まれません。

では timeoutInMinutes 、ジョブの実行時間に制限を設定できます。 指定しない場合、既定値は 60 分です。 を指定すると 0 、上限が使用されます (前述)。

cancelTimeoutInMinutesでは、前のタスクが失敗した場合に実行を続けるためにデプロイ タスクが設定されているジョブの取り消し時間の制限を設定できます。 指定しない場合、既定値は 5 分です。 値の範囲は 1 ~ 35790 分である必要があります。

jobs:
- job: Test
  timeoutInMinutes: 10 # how long to run the job before automatically cancelling
  cancelTimeoutInMinutes: 2 # how much time to give 'run always even if cancelled tasks' before stopping them

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

Microsoftホステッド エージェントを対象とするジョブには、実行時間に関する追加の制限があります。

各タスクのタイムアウトを個別に設定することもできます。「 タスク制御オプション」を参照してください。

複数ジョブの構成

作成した 1 つのジョブから、複数のエージェントで複数のジョブを並列で実行できます。 次に例をいくつか示します。

  • マルチ構成ビルド: 複数の構成を並列で構築できます。 たとえば、 と の両方debugreleaseの構成用の Visual C++ アプリを、プラットフォームと x64 プラットフォームの両方x86でビルドできます。 詳細については、「 Visual Studio Build - 複数のプラットフォームの複数の構成」を参照してください。

  • 複数構成のデプロイ: たとえば、異なる地理的リージョンに対して、複数のデプロイを並列で実行できます。

  • マルチ構成テスト: 複数の構成を並列でテストできます。

  • 複数構成変数が空の場合でも、複数構成では常に少なくとも 1 つのジョブが生成されます。

この matrix 戦略により、異なる変数セットを使用してジョブを複数回ディスパッチできます。 タグは maxParallel 並列処理の量を制限します。 次のジョブは、Location と Browser の値が指定されたとおりに設定された状態で 3 回ディスパッチされます。 ただし、同時に実行されるジョブは 2 つだけです。

jobs:
- job: Test
  strategy:
    maxParallel: 2
    matrix: 
      US_IE:
        Location: US
        Browser: IE
      US_Chrome:
        Location: US
        Browser: Chrome
      Europe_Chrome:
        Location: Europe
        Browser: Chrome

注意

マトリックス構成名 (上記のような US_IE ) には、基本的なラテンアルファベット (A-Z、a-z)、数字、アンダースコア (_) のみを含める必要があります。 列名の先頭は文字である必要があります。 また、100 文字以下にする必要があります。

出力変数を使用してマトリックスを生成することもできます。 これは、スクリプトを使用してマトリックスを生成する必要がある場合に便利です。

matrix は、文字列化された JSON オブジェクトを含むランタイム式を受け入れます。 展開された JSON オブジェクトは、マトリックス構文と一致する必要があります。 次の例では、JSON 文字列をハードコーディングしましたが、スクリプト言語またはコマンド ライン プログラムによって生成される可能性があります。

jobs:
- job: generator
  steps:
  - bash: echo "##vso[task.setVariable variable=legs;isOutput=true]{'a':{'myvar':'A'}, 'b':{'myvar':'B'}}"
    name: mtrx
  # This expands to the matrix
  #   a:
  #     myvar: A
  #   b:
  #     myvar: B
- job: runner
  dependsOn: generator
  strategy:
    matrix: $[ dependencies.generator.outputs['mtrx.legs'] ]
  steps:
  - script: echo $(myvar) # echos A or B depending on which leg is running

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

スライス

エージェント ジョブを使用して、一連のテストを並列で実行できます。 たとえば、1 つのエージェントで 1000 個の大規模なテスト スイートを実行できます。 または、2 つのエージェントを使用して、それぞれ 500 個のテストを並列で実行できます。

スライスを活用するには、ジョブ内のタスクが属しているスライスを理解するのに十分なスマートである必要があります。

Visual Studio テスト タスクは、テスト スライスをサポートするそのようなタスクの 1 つです。 複数のエージェントをインストールしている場合は、これらのエージェントで Visual Studio テスト タスクを並列に実行する方法を指定できます。

この parallel 戦略により、ジョブを何度も複製できます。 変数 System.JobPositionInPhaseSystem.TotalJobsInPhase が各ジョブに追加されます。 その後、スクリプト内で変数を使用して、ジョブ間で作業を分割できます。 「エージェント ジョブを使用した並列および複数の実行」を参照してください。

次のジョブは、 の値 System.JobPositionInPhase を使用して 5 回ディスパッチされ、 System.TotalJobsInPhase 適切に設定されます。

jobs:
- job: Test
  strategy:
    parallel: 5

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

ジョブ変数

YAML を使用している場合は、ジョブで変数を指定できます。 変数は、マクロ構文 $(variableName) を使用してタスク入力に渡すことも、ステージ変数を使用してスクリプト内でアクセスすることもできます。

ジョブで変数を定義し、タスク内で使用する例を次に示します。

variables:
  mySimpleVar: simple var value
  "my.dotted.var": dotted var value
  "my var with spaces": var with spaces value

steps:
- script: echo Input macro = $(mySimpleVar). Env var = %MYSIMPLEVAR%
  condition: eq(variables['agent.os'], 'Windows_NT')
- script: echo Input macro = $(mySimpleVar). Env var = $MYSIMPLEVAR
  condition: in(variables['agent.os'], 'Darwin', 'Linux')
- bash: echo Input macro = $(my.dotted.var). Env var = $MY_DOTTED_VAR
- powershell: Write-Host "Input macro = $(my var with spaces). Env var = $env:MY_VAR_WITH_SPACES"

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

条件の使用の詳細については、「 条件指定」を参照してください。

ワークスペース

エージェント プール ジョブを実行すると、エージェントにワークスペースが作成されます。 ワークスペースは、ソースをダウンロードし、ステップを実行し、出力を生成するディレクトリです。 ワークスペース ディレクトリは、変数を使用して Pipeline.Workspace ジョブで参照できます。 この下に、さまざまなサブディレクトリが作成されます。

エージェント プール ジョブを実行すると、エージェントにワークスペースが作成されます。 ワークスペースは、ソースをダウンロードし、ステップを実行し、出力を生成するディレクトリです。 ワークスペース ディレクトリは、変数を使用して Agent.BuildDirectory ジョブで参照できます。 この下に、さまざまなサブディレクトリが作成されます。

  • Build.SourcesDirectory は、タスクがアプリケーションのソース コードをダウンロードする場所です。
  • Build.ArtifactStagingDirectory は、タスクが発行される前にパイプラインに必要な成果物をダウンロードするか、成果物をアップロードする場所です。
  • Build.BinariesDirectory は、タスクが出力を書き込む場所です。
  • Common.TestResultsDirectory は、タスクがテスト結果をアップロードする場所です。

$(Common.TestResultsDirectory)$(Build.ArtifactStagingDirectory)常に削除され、すべてのビルドの前に再作成されます。

セルフホステッド エージェントでパイプラインを実行すると、既定では、 と 以外$(Build.ArtifactStagingDirectory)$(Common.TestResultsDirectory)のサブディレクトリは 2 回連続して実行される間にクリーンアップされません。 その結果、それを利用するためにタスクが実装されている場合は、増分ビルドとデプロイを実行できます。 この動作は、ジョブの 設定を workspace 使用してオーバーライドできます。

重要

ワークスペースのクリーン オプションは、セルフホステッド エージェントにのみ適用されます。 Microsoftホステッド エージェントを使用する場合、ジョブは常に新しいエージェントで実行されます。

- job: myJob
  workspace:
    clean: outputs | resources | all # what to clean up before the job runs

オプションのいずれかを clean 指定すると、次のように解釈されます。

  • outputs: 新しいジョブを実行する前に削除します Build.BinariesDirectory
  • resources: 新しいジョブを実行する前に削除します Build.SourcesDirectory
  • all: 新しいジョブを実行する前に、ディレクトリ全体 Pipeline.Workspace を削除します。
  jobs:
  - deployment: MyDeploy
    pool:
      vmImage: 'ubuntu-latest'
    workspace:
      clean: all
    environment: staging

注意

エージェントの機能とパイプラインの要求に応じて、各ジョブがセルフホステッド プール内の異なるエージェントにルーティングされる場合があります。 その結果、後続のパイプラインの実行 (または同じパイプライン内のステージまたはジョブ) 用の新しいエージェントが得られる可能性があるため、クリーニングは、後続の実行、ジョブ、またはステージが以前の実行、ジョブ、またはステージからの出力にアクセスできる保証 ではありません 。 エージェントの機能とパイプラインの要求を構成して、パイプライン ジョブの実行に使用するエージェントを指定できますが、要求を満たすエージェントがプールに 1 つしかない場合を除き、後続のジョブで以前のジョブと同じエージェントが使用される保証はありません。 詳細については、「要求の 指定」を参照してください。

ワークスペースのクリーンに加えて、パイプライン設定 UI で [クリーン ] 設定を構成してクリーニングを構成することもできます。 Clean 設定が true の場合 (既定値でもあります)、パイプライン内のすべてのチェックアウト ステップに clean: true を指定するのと同じです。 を指定 clean: trueすると、git フェッチの前に を実行 git clean -ffdx します git reset --hard HEAD[クリーン] 設定を構成するには:

  1. パイプラインを編集し、[ ...] を選択し、[トリガー] を選択 します

    トリガーを編集します。

  2. [YAML]、[ソースの取得] を選択し、目的の [クリーン] 設定を構成します。 既定値は trueです。

    クリーン設定。

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

成果物のダウンロード

この YAML ファイルの例では、成果物 WebSite を発行し、成果物を に $(Pipeline.Workspace)ダウンロードします。 デプロイ ジョブは、ビルド ジョブが成功した場合にのみ実行されます。

# test and upload my code as an artifact named WebSite
jobs:
- job: Build
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - script: npm test
  - task: PublishBuildArtifacts@1
    inputs:
      pathtoPublish: '$(System.DefaultWorkingDirectory)'
      artifactName: WebSite

# download the artifact and deploy it only if the build job succeeded
- job: Deploy
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - checkout: none #skip checking out the default repository resource
  - task: DownloadBuildArtifacts@0
    displayName: 'Download Build Artifacts'
    inputs:
      artifactName: WebSite
      downloadPath: $(System.DefaultWorkingDirectory)

  dependsOn: Build
  condition: succeeded()

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

dependsOncondition の使用の詳細については、「条件の指定」を参照してください。

OAuth トークンへのアクセス

ジョブで実行されているスクリプトが、現在の Azure Pipelines または TFS OAuth セキュリティ トークンにアクセスすることを許可できます。 トークンを使用して、Azure Pipelines REST API に対する認証を行うことができます。

OAuth トークンは常に YAML パイプラインで使用できます。 を使用して env、タスクまたはステップに明示的にマップする必要があります。 次に例を示します。

steps:
- powershell: |
    $url = "$($env:SYSTEM_TEAMFOUNDATIONCOLLECTIONURI)$env:SYSTEM_TEAMPROJECTID/_apis/build/definitions/$($env:SYSTEM_DEFINITIONID)?api-version=4.1-preview"
    Write-Host "URL: $url"
    $pipeline = Invoke-RestMethod -Uri $url -Headers @{
      Authorization = "Bearer $env:SYSTEM_ACCESSTOKEN"
    }
    Write-Host "Pipeline = $($pipeline | ConvertTo-Json -Depth 100)"
  env:
    SYSTEM_ACCESSTOKEN: $(system.accesstoken)

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

参照トピック