パイプラインにジョブを指定する
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 はサポートされていません。
ジョブの種類
ジョブの種類は、ジョブの実行場所によって異なります。
- エージェント プール ジョブは 、エージェント プール内のエージェントで実行されます。 これらのジョブは、ビルド パイプラインとリリース パイプラインで使用できます。
- サーバー ジョブは 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) で実行されます。 サーバー ジョブには、エージェントやターゲット コンピューターは必要ありません。 現時点では、サーバー ジョブでサポートされているタスクはごくわずかです。
エージェントレス ジョブでサポートされているタスク
現在、エージェントレス ジョブでは、次のタスクのみがすぐにサポートされています。
- 遅延タスク
- Azure 関数タスクを呼び出す
- REST API タスクの呼び出し
- 手動検証タスク
- 発行先Azure Service Busタスク
- Azure Monitor アラートのクエリ タスク
- 作業項目のクエリ タスク
タスクは拡張可能であるため、拡張機能を使用してエージェントレス タスクを追加できます。 エージェントレス ジョブの既定のタイムアウトは 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 つのジョブから、複数のエージェントで複数のジョブを並列で実行できます。 次に例をいくつか示します。
マルチ構成ビルド: 複数の構成を並列で構築できます。 たとえば、 と の両方
debug
release
の構成用の 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.JobPositionInPhase
と System.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
。 [クリーン] 設定を構成するには:
パイプラインを編集し、[ ...] を選択し、[トリガー] を選択 します。
[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 はサポートされていません。
dependsOn と condition の使用の詳細については、「条件の指定」を参照してください。
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 はサポートされていません。