So far we’ve been considering how you can define a yaml pipeline to define the steps required to build the code in a single repository. Create a .azure-pipelines.yml file, add the stages, jobs and steps and away you go. Cool.
What if you’re building multiple apps with the source code in multiple repositories though? You could just copy your pipeline definition from repo to repo. What happens when you want to make changes to the pipeline? Are you going to copy the changes here, there and everywhere?
No. You’ve got more self-respect than that. You want a single pipeline definition that is shared across the repos that need it. In which case, templates will be of interest.
Create a Template File
If you’ve got a yaml pipeline definition that already works for you you’re probably going to want to use that as the basis of your template. Copy and paste your pipeline into a new yaml file. You’ll probably want to create a new project or repo to hold this template file.
Remove Trigger
If you’ve got a trigger section in the pipeline you’re copying from (to trigger the pipeline when changes are pushed to certain branches) you can remove that from the template file.
Convert Variables to Parameters
If you have any variables in the pipeline you will need to convert them to parameters. Use the parameters keyword…simple enough. Notice that you can still provide default values for the parameters. If parameters values are not supplied by the pipeline that is using the template these default values will be used. For example:
parameters:
image_name: mcr.microsoft.com/businesscentral/sandbox
container_name: Build
company_name: My Company
user_name: admin
password: P@ssword1
Any references to variables in the steps will need to be changed to refer to the parameters instead. Rather than this:
-task: PowerShell@1
displayName: Create build container
inputs:
scriptType: inlineScript
inlineScript: >
Import-Module navcontainerhelper;
New-NavContainer -containerName $(container_name)...
Use ${{parameters.[parameter_name]}} like this:
-task: PowerShell@1
displayName: Create build container
inputs:
scriptType: inlineScript
inlineScript: >
Import-Module navcontainerhelper;
New-NavContainer -containerName ${{parameters.container_name}}...
I’ve called my template file build-template.yml and the first few lines look like this:
parameters:
image_name: mcr.microsoft.com/businesscentral/sandbox
container_name: Build
company_name: My Company
user_name: admin
password: P@ssword1
license_file: C:\Users\james.pearson\Desktop\Licence.flf
stages:
- stage: build
displayName: Build
jobs:
- job: Build
pool:
name: Default
steps:
- task: PowerShell@1
displayName: Create build container
inputs:
scriptType: inlineScript
inlineScript: >
Import-Module navcontainerhelper;
$Credential = [PSCredential]::new('${{parameters.user_name}}',(ConvertTo-SecureString '${{parameters.password}}' -AsPlainText -Force));
...
Change the Pipeline to Use the Template
Now you want to change the pipeline definition to use the template yaml file that you have created. Include a repository resource, specifying the name with repository key.
The type key refers to the host of the git repo. Confusingly, ‘git’ refers to an Azure DevOps project or you can also refer to templates in GitHub repos. Name is in the format Project/Repository – in my example both are called ‘Templates’. Define a ref (generally a branch or tag) in the template repo that specifies the version of the template you want.
trigger:
- '*'
resources:
repositories:
- repository: templates
type: git
name: Templates/Templates
ref: refs/heads/master
stages:
- template: build-template.yml@templates
parameters:
image_name: mcr.microsoft.com/businesscentral/sandbox
company_name: My Company
Templates can be used at different levels in the pipeline to specify stages, jobs, steps or variables – see here for more info. In my example the template file is specifying stages to use in the pipeline.
My pipeline simply becomes a template key beneath the stages key. The value is in the format [filename]@[repository]. The repository value here is taken from the repository key specified above. Supply parameter values with the parameters key. Any parameter values that are not supplied will take the default values from the template file.
And there you have it. A single template file that you can reuse across your different repos. Make changes to your pipeline once and have them used wherever the template is used.
James Pearson 