Customize your pipeline
Azure Pipelines | Azure DevOps Server 2020 | Azure DevOps Server 2019
This is a step-by-step guide on common ways to customize your pipeline.
Follow instructions in Create your first pipeline to create a working pipeline.
A pipeline is defined using a YAML file in your repo. Usually, this file is named
azure-pipelines.yml and is located at the root of your repo.
Navigate to the Pipelines page in Azure Pipelines and select the pipeline you created.
Select Edit in the context menu of the pipeline to open the YAML editor for the pipeline. Examine the contents of the YAML file.
trigger: - main pool: vmImage: 'Ubuntu-16.04' steps: - task: Maven@3 inputs: mavenPomFile: 'pom.xml' mavenOptions: '-Xmx3072m' javaHomeOption: 'JDKVersion' jdkVersionOption: '1.8' jdkArchitectureOption: 'x64' publishJUnitResults: false testResultsFiles: '**/surefire-reports/TEST-*.xml' goals: 'package'
The contents of your YAML file may be different depending on the sample repo you started with, or upgrades made in Azure Pipelines.
This pipeline runs whenever your team pushes a change to the main branch of your repo. It runs on a Microsoft-hosted Linux machine. The pipeline process has a single step, which is to run the Maven task.
Change the platform to build on
Navigate to the editor for your pipeline by selecting Edit pipeline action on the build, or by selecting Edit from the pipeline's main page.
Currently the pipeline runs on a Linux agent:
pool: vmImage: "ubuntu-16.04"
To choose a different platform like Windows or Mac, change the
pool: vmImage: "vs2017-win2016"
pool: vmImage: "macos-latest"
Select Save and then confirm the changes to see your pipeline run on a different platform.
You can add additional scripts or tasks as steps to your pipeline. A task is a pre-packaged script. You can use tasks for building, testing, publishing, or deploying your app. For Java, the Maven task we used handles testing and publishing results, however, you can use a task to publish code coverage results too.
Open the YAML editor for your pipeline.
Add the following snippet to the end of your YAML file.
- task: PublishCodeCoverageResults@1 inputs: codeCoverageTool: "JaCoCo" summaryFileLocation: "$(System.DefaultWorkingDirectory)/**/site/jacoco/jacoco.xml" reportDirectory: "$(System.DefaultWorkingDirectory)/**/site/jacoco" failIfCoverageEmpty: true
Select Save and then confirm the changes.
You can view your test and code coverage results by selecting your build and going to the Test and Coverage tabs.
Build across multiple platforms
You can build and test your project on multiple platforms. One way to do it is with
matrix. You can use variables to conveniently put data into various parts of a pipeline. For this example, we'll use a variable to pass in the name of the image we want to use.
azure-pipelines.ymlfile, replace this content:
pool: vmImage: "ubuntu-16.04"
with the following content:
strategy: matrix: linux: imageName: "ubuntu-16.04" mac: imageName: "macos-10.14" windows: imageName: "vs2017-win2016" maxParallel: 3 pool: vmImage: $(imageName)
Select Save and then confirm the changes to see your build run up to three jobs on three different platforms.
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.
Build using multiple versions
To build a project using different versions of that language, you can use a
matrix of versions and a variable. In this step you can either build the Java project with two different versions of Java on a single platform or run different versions of Java on different platforms.
If you want to build on a single platform and multiple versions, add the following matrix to your
azure-pipelines.ymlfile before the Maven task and after the vmImage.
strategy: matrix: jdk10: jdk_version: "1.10" jdk11: jdk_version: "1.11" maxParallel: 2
Then replace this line in your maven task:
with this line:
Make sure to change the
$(imageName)variable back to the platform of your choice.
If you want to build on multiple platforms and versions, replace the entire content in your
azure-pipelines.ymlfile before the publishing task with the following snippet:
trigger: - main strategy: matrix: jdk10_linux: imageName: "ubuntu-16.04" jdk_version: "1.10" jdk11_windows: imageName: "vs2017-win2016" jdk_version: "1.11" maxParallel: 2 pool: vmImage: $(imageName) steps: - task: Maven@3 inputs: mavenPomFile: "pom.xml" mavenOptions: "-Xmx3072m" javaHomeOption: "JDKVersion" jdkVersionOption: $(jdk_version) jdkArchitectureOption: "x64" publishJUnitResults: true testResultsFiles: "**/TEST-*.xml" goals: "package"
Select Save and then confirm the changes to see your build run two jobs on two different platforms and SDKs.
Customize CI triggers
You can use a
trigger: to specify the events when you want to run the pipeline. YAML pipelines are configured by default with a CI trigger on your default branch (which is usually main). You can set up triggers for specific branches or for pull request validation. For a pull request validation trigger just replace the
trigger: step with
pr: as shown in the two examples below.
If you'd like to set up triggers, add either of the following snippets at the beginning of your
trigger: - main - releases/*
pr: - main - releases/*
You can specify the full name of the branch (for example,
main) or a prefix-matching wildcard (for example,
There are pipeline settings that you wouldn't want to manage in your YAML file. Follow these steps to view and modify these settings:
- From your web browser, open the project for your organization in Azure DevOps and choose Pipelines / Pipelines from the navigation sidebar.
- Select the pipeline you want to configure settings for from the list of pipelines.
- Open the overflow menu by clicking the action button with the vertical ellipsis and select Settings.
Processing of new run requests
Sometimes you'll want to prevent new runs from starting on your pipeline.
- By default, the processing of new run requests is Enabled. This setting allows standard processing of all trigger types, including manual runs.
- Paused pipelines allow run requests to be processed, but those requests are queued without actually starting. When new request processing is enabled, run processing resumes starting with the first request in the queue.
- Disabled pipelines prevent users from starting new runs. All triggers are also disabled while this setting is applied.
- YAML file path. If you ever need to direct your pipeline to use a different YAML file, you can specify the path to that file. This setting can also be useful if you need to move/rename your YAML file.
- Automatically link work items included in this run. The changes associated with a given pipeline run may have work items associated with them. Select this option to link those work items to the run. When this option is selected, you'll need to specify a specific branch. Work items will only be associated with runs of that branch.
- To get notifications when your runs fail, see how to Manage notifications for a team
You've just learned the basics of customizing your pipeline. Next we recommend that you learn more about customizing a pipeline for the language you use:
To learn what else you can do in YAML pipelines, see YAML schema reference.