Use upstream build in Azure DevOps
Tags: azure, azuredevops, build, tooling
Published: 2023-08-02 06:41:45

## 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](https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/download-pipeline-artifact-v2?view=azure-pipelines)

## 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](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/resources?view=azure-devops&tabs=schema)