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

最もシンプルなケースでは、パイプラインに 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 に配置タスクの手順を追加することもできますが、代わりに配置ジョブを使うことをお勧めします。 配置ジョブにはいくつかのベネフィットがあります。 たとえば、環境に配置できます。これには、配置した内容の履歴を確認できるなどのベネフィットがあります。

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

サーバー ジョブを指定する完全な構文:

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

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

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

ビルド パイプラインで複数のジョブを指定した場合、既定で並列で実行されます。 ジョブ間の依存関係を構成することで、ジョブの実行順序を指定できます。 リリース パイプラインでは、ジョブの依存関係はサポートされていません。 リリース パイプラインの複数のジョブは順番に実行されます。

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

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/main'))
  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

エージェントまたはサーバー ジョブで [このジョブを実行する] オプションを使うと、特定の条件を満たした場合にのみタスクを実行できます。 定義済みの条件を選ぶか、[カスタム] を選んで true または false と評価される式を入力します。 入れ子になった式を使用できます。また、式からは、リリース パイプラインで使用できる変数にアクセスできます。

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

配置タスクで前のタスクが失敗した場合に実行を継続するように設定している場合、cancelTimeoutInMinutes を使うと、ジョブのキャンセル時間に制限を設定できます。 指定しない場合、既定値は 5 分です。 この値の範囲は 1 分から 35,790 分です。

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

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

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

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

parallel 戦略を使うと、ジョブを何度も複製できます。 変数 System.JobPositionInPhase と System.TotalJobsInPhase が各ジョブに追加されます。 この変数をスクリプト内で使うことで、作業を複数のジョブに分割できます。 エージェント ジョブを使った並列および複数の実行に関する記事を参照してください。

次のジョブは 5 回ディスパッチされます。その際に System.JobPositionInPhase と System.TotalJobsInPhase の値は適切に設定されます。

jobs:
- job: Test
  strategy:
    parallel: 5

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

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"

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

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

- 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

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

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

   

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

   

# 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: $(Pipeline.Workspace)

  dependsOn: Build
  condition: succeeded()

また、リリースのジョブ実行中に、特定の成果物をダウンロードすることを選ぶこともできます。 特定のジョブのタスクが特定の成果物のみに依存している場合は、このオプションを使います。

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)