Use upstream build in Azure DevOps

Introduction

Say you want to combine the documentation of all your projects into one project. Whenever one of your projects is build it should trigger a new build of the documentation project so that one can also be updated.

In simple words: trigger downstream builds when your project is build.

The situation

We have a project: apple
And a project: fruit-basket that depends on apple
Whenever apple is build a build of fruit-basket must be triggered.

Apple

This project just does his thing.
Build your Apple project based on your needs, nothing special.
Maybe make sure to tag the sources if you want to make sure u use the same version later on.

If the documentation that you want to show needs to be build and you don't want to do that in fruit-basket make sure to upload the build-artefact.

Fruit-basket

This project needs a trigger that when apple is build it also executed the build.

You can do this by adding a pipeline resource.
Open your azure-pipelines.yaml (based on the name you gave it, or create a new one)

Then add the following:

resources:
  pipelines:
    - pipeline: appleBuild # Identifier
      source: 'apple-build' # This needs to be the name of the pipeline, including spaces if needed!
      trigger: # When do we want it to be triggered?
        branches:
          include: # When these branches are build
          - releases/*
          - main
          - master
        stages:
          - Publish # But only after this stages from apple build

Now whenever a master build is executed on Apple and the Publish is succeeded it will trigger the fruit-basket build :)

And inside that build you can then combine the Apple documentation and others to create one documentation.

Using apple

There are two ways to do this.

• Checkout the source code of apple
• Download the build artefact of the apple build

Checkout the source code.

For this you need to do two things.

1. Add the apple sources as repository
2. Checkout the apple sources at each job

At the resources part you need to add a repositories option:

resources: # Already there
  repositories:
    - repository: apple # Identifier to be used in this build
      type: git
      name: FruitCompany/apple # Name of the Azure DevOps repo
      ref: refs/heads/master # Branch to checkout
# As we are going to checkout multiple repositories, we also need to define that we want to use our own sources (apple-basket, ie: self)
    - repository: self
      type: git
      name: self

Now in order to actually use it, at the beginning of each job you need to checkout the sources.

Example stage:

stages:
  - stage: generate_documentation
    jobs:
      - job:
        pool:
          vmImage: 'ubuntu-latest'
        steps:
          - checkout: self # Checkout apple-basket

          - checkout: apple
            path: 'apple'
            fetchDepth: 1

         # Here you can then do whatever you want with the two sources :)

Download build artefact

Inside a job/step you need to add the following:
(For instance instead of the apple checkout, or after when you want to use pear build artefact.

         - task: DownloadPipelineArtifact@2
            inputs:
              source: specific # We want to use a specific pipeline
              project: FruitCompany # Projectname in Azure DevOps
              pipeline: apple-build # Pipeline 
              artifact: documentation-dist # Name of the uploaded build artefact                

With patterns you can limit what it should download from the uploaded artefact

              patterns: |
                *.md

More information on the DownloadPipelineArtifact task can be found here

Other triggers

Maybe you want fruit-basket to build whenever code is pushed to apple?

You can do that by using the repositories resource option.
(Don't forget to 'checkout' the source code in each stage)

And there are a few other options that can trigger downstream build:

• containers # Whenever a new container is pushed to Azure Container Registry
• packages # Whenever a new package is released.
• webhooks # You can create whatever you want with this one.

Full description of all the possibilities and options here