Specify jobs in your pipeline

TFS 2017

Note

In Microsoft Team Foundation Server (TFS) 2018 and previous versions, build and release pipelines are called definitions, runs are called builds, service connections are called service endpoints, stages are called environments, and jobs are called phases.

You can organize your release pipeline into jobs. Every release pipeline has at least one job. Jobs are not supported in a build pipeline in this version of TFS.

Note

You must install Update 2 to use jobs in a release pipeline in TFS 2017. Jobs in build pipelines are available in Azure Pipelines, TFS 2018.2, and newer versions.

Define a single job

YAML

YAML is not supported in TFS 2017.

Classic

To add jobs to your build pipeline, edit the pipeline on the Pipelines page. Select ... to add a job.

To add jobs to your release pipeline, edit the pipeline from Pipelines > Releases. View the stage tasks in the stage where you want to add your job. Select ... to add a job.

Types of jobs

Jobs can be of different types, depending on where they run.

• Agent pool jobs run on an agent in the agent pool. These jobs are only available release pipelines.

Agent pool jobs

These are the most common type of jobs and they run on an agent in an agent pool.

• When using Microsoft-hosted agents, each job in a pipeline gets a fresh agent.
• Use demands with self-hosted agents to specify what capabilities an agent must have to run your job. You may get the same agent for consecutive jobs, depending on whether there is more than one agent in your agent pool that matches your pipeline's demands. If there is only one agent in your pool that matches the pipeline's demands, the pipeline will wait until this agent is available.

Note

Demands and capabilities are designed for use with self-hosted agents so that jobs can be matched with an agent that meets the requirements of the job. When using Microsoft-hosted agents, you select an image for the agent that matches the requirements of the job, so although it is possible to add capabilities to a Microsoft-hosted agent, you don't need to use capabilities with Microsoft-hosted agents.

YAML

YAML is not supported in TFS 2017.

Classic

You have the option to specify demands in the pipeline, in the jobs, or both. If you specify demands in both the pipeline and in a job, the union of the two sets of demands is required for the system to select an agent.

Learn more about agent capabilities.

Server jobs

Tasks in a server job are orchestrated by and executed on the server (Azure Pipelines or TFS). A server job does not require an agent or any target computers. Only a few tasks are supported in a server job at present.

Agentless jobs supported tasks

Currently, only the following tasks are supported out of the box for agentless jobs:

• Delay task
• Invoke Azure Function task
• Invoke REST API task
• Manual Validation task
• Publish To Azure Service Bus task
• Query Azure Monitor Alerts task
• Query Work Items task

Because tasks are extensible, you can add more agentless tasks by using extensions. The default timeout for agentless jobs is 60 minutes.

YAML

YAML is not supported in TFS 2017.

Classic

Server jobs are not supported in TFS 2017.

Dependencies

When you define multiple jobs in a single stage, you can specify dependencies between them. Pipelines must contain at least one job with no dependencies.

Note

Each agent can run only one job at a time. To run multiple jobs in parallel you must configure multiple agents. You also need sufficient parallel jobs.

YAML

YAML builds are not yet available on TFS.

Classic

To add a new job, select '...' on the pipeline channel in the Tasks tab of the pipeline. The conditions and order of execution for a job are displayed when you select the job in the editor.

Multiple jobs you add to a release pipeline run in sequence. You cannot configure the order of dependencies between jobs in this version of TFS. You cannot also use jobs with build pipelines.

For example, the pipeline shown below divides the overall release execution into separate execution jobs by using two agent jobs and a server job.

In the example above:

1. The tasks in the first job of the release run on an agent and, after this job is complete, the agent is released.

2. The server job contains a Manual Intervention task that runs on the Azure Pipelines or TFS. The job does not execute on, or require, an agent or any target servers. The Manual Intervention task displays its message and waits for a "resume" or "reject" response from the user. In this example, if the configured timeout is reached, the task will automatically reject the deployment (set the timeout in the control options section to zero if you do not want an automated response to be generated).

3. If the release is resumed, tasks in the third job run - possibly on a different agent. If the release is rejected, this job does not run and the release is marked as failed.

It's important to understand some of the consequences of phased execution:

• Each job may use different agents. Do not assume that the state from an earlier job is available during subsequent jobs.

• The Continue on Error and Always run options for tasks in each job do not have any effect on tasks in subsequent jobs. For example, setting Always run on a task at the end of the first job will not guarantee that tasks in subsequent jobs will run.

Conditions

You can specify the conditions under which each job runs. By default, a job runs if it does not depend on any other job, or if all of the jobs that it depends on have completed and succeeded. You can customize this behavior by forcing a job to run even if a previous job fails or by specifying a custom condition.

YAML

YAML builds are not available on TFS 2017.

Classic

Conditions are not supported in this version of TFS.

Timeouts

To avoid taking up resources when your job is unresponsive or waiting too long, it's a good idea to set a limit on how long your job is allowed to run. Use the job timeout setting to specify the limit in minutes for running the job. Setting the value to zero means that the job can run:

• Forever on self-hosted agents

The timeout period begins when the job starts running. It does not include the time the job is queued or is waiting for an agent.

YAML

YAML builds are not available on TFS 2017.

Classic

Select the job and then specify the timeout value.

On the Options tab, you can specify default values for all jobs in the pipeline. If you specify a non-zero value for the job timeout, then it overrides any value that is specified in the pipeline options. If you specify a zero value, then the timeout value from the pipeline options is used. If the pipeline value is also set to zero, then there is no timeout.

You can also set the timeout for each task individually - see task control options.

Multi-job configuration

From a single job you author, you can run multiple jobs on multiple agents in parallel. Some examples include:

• Multi-configuration builds: You can build multiple configurations in parallel. For example, you could build a Visual C++ app for both debug and release configurations on both x86 and x64 platforms. To learn more, see Visual Studio Build - multiple configurations for multiple platforms.

• Multi-configuration deployments: You can run multiple deployments in parallel, for example, to different geographic regions.

• Multi-configuration testing: You can run test multiple configurations in parallel.

• Multi-configuration will always generate at least one job, even if a multi-configuration variable is empty.

YAML

YAML builds are not available on TFS 2017.

Classic

To run multiple jobs using multi-configuration option, you identify a variable named a multiplier, and specify a list of values for that multiplier. A separate job is run for each value in the list. To use multipliers for build or deployment, you must:

• Define one or more variables on the Variables tab of the pipeline or in a variable group. Each variable, known in this context as a multiplier variable, must be defined as a comma-delimited list of the values you want to pass individually to the agents.

• Enter the name of the multiplier variable, without the $ and parentheses, as the value of the Multipliers parameter. Using a secret variable as a multiplier variable is not supported.

• If you want to execute the job for more than one multiplier variable, enter the variable names as a comma-delimited list - omitting the $ and parentheses for each one.

• If you want to limit the number of agents used during the deployment to a number less than you have configured for your subscription, enter that value as the Maximum number of agents parameter.

For example, you might define two variables named Location and Browser as follows::

• Location = US,Europe
• Browser = IE,Chrome,Edge,Firefox

The following configuration will execute the deployment eight times using a maximum of four agents at any one time:

• Multipliers = Location,Browser
• Maximum number of agents = 4

With multi-configuration you can run multiple jobs, each with a different value for one, or more variables (multipliers). If you want to run the same job on multiple agents, then you can use multi-agent option of parallelism. The test slicing example above can be accomplished through multi-agent option.

Slicing

An agent job can be used to run a suite of tests in parallel. For example, you can run a large suite of 1000 tests on a single agent. Or, you can use two agents and run 500 tests on each one in parallel.

To leverage slicing, the tasks in the job should be smart enough to understand the slice they belong to.

The Visual Studio Test task is one such task that supports test slicing. If you have installed multiple agents, you can specify how the Visual Studio Test task will run in parallel on these agents.

YAML

YAML builds are not available on TFS 2017.

Classic

Specify the multi-agent option on an agent job to leverage slicing. The job is dispatched as many times as the number of agents you specify, and the variables System.JobPositionInPhase and System.TotalJobsInPhase are automatically set in each job.

Job variables

If you are using YAML, variables can be specified on the job. The variables can be passed to task inputs using the macro syntax $(variableName), or accessed within a script using the stage variable.

YAML

YAML builds are not available on TFS 2017.

Classic

Job variables are not yet supported in the web editor.

For information about using a condition, see Specify conditions.

Workspace

When you run an agent pool job, it creates a workspace on the agent. The workspace is a directory in which it downloads the source, runs steps, and produces outputs. The workspace directory can be referenced in your job using Agent.BuildDirectory variable. Under this, various subdirectories are created:

• Build.SourcesDirectory is where tasks download the application's source code.
• Build.ArtifactStagingDirectory is where tasks download artifacts needed for the pipeline or upload artifacts before they are published.
• Build.BinariesDirectory is where tasks write their outputs.
• Common.TestResultsDirectory is where tasks upload their test results.

YAML

YAML builds are not available on TFS 2017.

Classic

When you run a pipeline on a self-hosted agent, by default, none of the subdirectories are cleaned in between two consecutive runs. As a result, you can run incremental builds and deployments, provided that tasks are implemented to do that. However, you can override this behavior using the Clean build option under Get sources task. The options vary depending on the type of repository that you use.

• GitHub
• Azure Repos Git
• TFVC

Artifact download

This example YAML file publishes the artifact WebSite and then downloads the artifact to $(Pipeline.Workspace). The Deploy job only runs if the Build job is successful.

YAML

YAML builds are not available on TFS 2017.

Classic

In a release pipeline, you may choose to skip the download of artifacts during the job execution. Use this option if you want to implement your own custom logic for downloading artifacts by using tasks, or if the tasks in a particular job do not rely on the artifacts.

For information about using dependsOn and condition, see Specify conditions.

Access to OAuth token

You can allow scripts running in a job to access the current Azure Pipelines or TFS OAuth security token. The token can be use to authenticate to the Azure Pipelines REST API.

YAML

YAML builds are not available on TFS 2017.

Classic

Select the Allow scripts to access OAuth token option in the control options for the job. The token will be available as the environment variable SYSTEM_ACCESSTOKEN.

What's next

• Deployment group jobs
• Conditions