Jobs in Azure Pipelines - Azure Pipelines (2024)

In the simplest case, a pipeline has a single job. In that case, you don't have to explicitly use the job keyword unless you're using a template. You can directly specify the steps in your YAML file.

This YAML file has a job that runs on a Microsoft-hosted agent and outputs Hello world.

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

You might want to specify more properties on that job. In that case, you can use the job keyword.

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

Your pipeline could have multiple jobs. In that case, use the jobs keyword.

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

Your pipeline may have multiple stages, each with multiple jobs. In that case, use the stages keyword.

stages:- stage: A jobs: - job: A1 - job: A2- stage: B jobs: - job: B1 - job: B2

The full syntax to specify a job is:

- 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

The full syntax to specify a job is:

- 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

If the primary intent of your job is to deploy your app (as opposed to build or test your app), then you can use a special type of job called deployment job.

The syntax for a deployment job is:

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

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 jobsteps:- script: echo hello world

Or multiple demands:

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

The full syntax to specify a server job is:

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

You can also use the simplified syntax:

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

The syntax for defining multiple jobs and their dependencies is:

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

Example jobs that build sequentially:

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

Example jobs that build in parallel (no dependencies):

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

Example of fan out:

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

Example of fan-in:

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

Example to run a job based upon the status of running a previous job:

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

Example of using a custom condition:

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

You can specify that a job run based on the value of an output variable set in a previous job. In this case, you can only use variables set in directly dependent jobs:

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

The timeoutInMinutes allows a limit to be set for the job execution time. When not specified, the default is 60 minutes. When 0 is specified, the maximum limit is used (described above).

The cancelTimeoutInMinutes allows a limit to be set for the job cancel time when the deployment task is set to keep running if a previous task failed. When not specified, the default is 5 minutes. The value should be in range from 1 to 35790 minutes.

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

The matrix strategy enables a job to be dispatched multiple times, with different variable sets. The maxParallel tag restricts the amount of parallelism. The following job is dispatched three times with the values of Location and Browser set as specified. However, only two jobs run at the same time.

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

It's also possible to use output variables to generate a matrix.This can be handy if you need to generate the matrix using a script.

matrix accepts a runtime expression containing a stringified JSON object.That JSON object, when expanded, must match the matrixing syntax.In the example below, we've hard-coded the JSON string, but it could be generated by a scripting language or command-line program.

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

The parallel strategy enables a job to be duplicated many times.Variables System.JobPositionInPhase and System.TotalJobsInPhase are added to each job. The variables can then be used within your scripts to divide work among the jobs.See Parallel and multiple execution using agent jobs.

The following job is dispatched five times with the values of System.JobPositionInPhase and System.TotalJobsInPhase set appropriately.

jobs:- job: Test strategy: parallel: 5

Here's an example of defining variables in a job and using them within tasks.

variables: mySimpleVar: simple var value "my.dotted.var": dotted var value "my var with spaces": var with spaces valuesteps:- 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"

The $(Build.ArtifactStagingDirectory) and $(Common.TestResultsDirectory) are always deleted and recreated prior to every build.

When you run a pipeline on a self-hosted agent, by default, none of the subdirectories other than $(Build.ArtifactStagingDirectory) and $(Common.TestResultsDirectory) are cleaned in between two consecutive runs. As a result, you can do incremental builds and deployments, provided that tasks are implemented to make use of that. You can override this behavior using the workspace setting on the job.

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

When you specify one of the clean options, they're interpreted as follows:

• outputs: Delete Build.BinariesDirectory before running a new job.
• resources: Delete Build.SourcesDirectory before running a new job.
• all: Delete the entire Pipeline.Workspace directory before running a new job.

 jobs: - deployment: MyDeploy pool: vmImage: 'ubuntu-latest' workspace: clean: all environment: staging

In addition to workspace clean, you can also configure cleaning by configuring the Clean setting in the pipeline settings UI. When the Clean setting is true, which is also its default value, it's equivalent to specifying clean: true for every checkout step in your pipeline. When you specify clean: true, you'll run git clean -ffdx followed by git reset --hard HEAD before git fetching. To configure the Clean setting:

1. Edit your pipeline, choose ..., and select Triggers.

   

2. Select YAML, Get sources, and configure your desired Clean setting. The default is true.

   

# test and upload my code as an artifact named WebSitejobs:- 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()

The OAuth token is always available to YAML pipelines.It must be explicitly mapped into the task or step using env.Here's an example:

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)