Fork & Register existing template

The main work of setting up Coral is the creation of a template. So using the community to grow and improve templates will be important. If you want to get something quickly you can follow this how-to or if this is not the template you are looking for you can start a template from scratch so you have full control.

This how-to aims to get you started with forking an existing template and register it in your own project so that others can create Software Delivery Pipelines from it. The how-to will use a .NET Core template which was built to produce libraries and publish them in one or more NuGet packages.

Assuming that you have installed the Coral Azure DevOps extension, you should be ready to continue.

Best practices for templates in your Azure DevOps instance

Coral uses Azure DevOps git repositories to store templates. When dealing with templates in git repositories, the recommended way is to manage them in a separate project. In this how-to we will have a project named CoralTemplates.

Further, even though Coral separates the template from the baseline repository. It can be handy to keep the baselines in the same project as the templates.

Steps

In order to complete this how-to the following will have to be done:

  1. Walk through the template with regards to what dependencies it has and whether it can be reused easily.
  2. Fork the template repository into our CoralTemplates project.
  3. Fork the baseline repository into the same project.
  4. Register the template to the project where it will be available for pipeline creation.

Template walk-through

The .NET Core template is an actual template which the Coral team actively uses themselves so this walk-through may be somewhat out-of-date, but the purpose is to highlight some of the aspects that may or may not make the template shareable.

Coral Architecture

As any Coral template, this template have a README.md and two folders: artifacts and namespaces.

The README.md is to give a description to the users of the template after it has been registered. The artifacts are files used to ait the creation of the resources and namespaces defines the resources that the template will create.

The Respository.yml defines the Azure DevOps repository to create and also the policies that will be attached to it.

The Pipelines.yml defines the Azure DevOps pipelines for build and release.

The first thing to look at is what input the template requires from the user. We can deduce this by looking at the non-hidden parameters of each namespace.

parameters: # Repository.yml
- id: RepositoryName
  type: string
  display: Repository name
- id: RequiredReviewers
  type: validator
  display: Required reviewers email
  valueProvider: local://aad/parameters/email?type=group&mailenabled=true&security=true

parameters: # Pipelines.yml
- id: QueueId
  display: Agent Queue
  valueProvider: local://vsts/parameters/agentqueues
  placeHolder: Select the queue for build and release pipelines with linux container support
- id: SecureFileId
  display: Strong name key file
  placeHolder: Select the secure file to use for strong name signing
  valueProvider: local://vsts/parameters/securefiles
- id: EsrpEndpointId
  display: Esrp Service Endpoint
  placeHolder: Select the endpoint to use for signing
  valueProvider: local://vsts/parameters/serviceendpoints?type=PRSS

So in total there are 5 inputs required by a user of this template that can have impact on how easy it is to reuse. The two from the Repository.yml has little impact, but all three from the Pipelines.yml indicates dependencies:

  • There is a requirement for an agent queue with linux container support.
  • A secure file that has the strong name signing key (.snk)
  • An ESRP service endpoint to do the signing.

So for this template to work out-of-the-box these dependencies will have to be present for the project.

Other things to look for are hard-coded values in the artifacts and namespace folders. This template should not have any of those.

Forking the template

In order to fork a template repository, whether it is in the same account or not, we recommend the following approach:

  1. Create a repository in the CoralTemplates project of your account.
  2. Clone the empty repository to your local machine.
  3. Add the existing template as a remote and fetch all branches. git remote add msfast https://msfast.visualstudio.com/DefaultCollection/Coral/_git/DotNet-Template && git fetch msfast
  4. Merge the master branch of the remote and push it back to Azure DevOps. git merge msfast/master && git push origin master

You should now have your own copy of the template, but you can, at any time remerge with the remote, as they now share a common history.

Forking a baseline

You might have noticed, as you browsed the template that the Repository.yml referred to a baseline in the repository resource declaration.

payload:
  repositories:
  - id: repository
    name: '{RepositoryName}'
    stage: Incubation
    # This is the baseline
    baseline: 'https://msfast.visualstudio.com/DefaultCollection/Coral/_git/DotNet-Baseline'
    defaultBranch: master

As you can see this refers back to the account from which the template originated. The reason this cannot be reused, is that Coral is unable to authenticate across accounts. Hence, the baseline must also be forked into your own account. To do this, follow the same steps as for the template.

  1. Create a repository in the CoralTemplates project of your account.
  2. Clone the empty repository to your local machine.
  3. Add the existing template as a remote and fetch all branches. git remote add msfast https://msfast.visualstudio.com/DefaultCollection/Coral/_git/DotNet-Baseline && git fetch msfast
  4. Merge the master branch of the remote and push it back to Azure DevOps. git merge msfast/master && git push origin master
  5. The final thing to do is to update the reference to the msfast baseline in the template, with the baseline you just created a fork of.

Registering the forked template with Coral

Refer to the how-to register template in Coral and register the Dotnet-Template repository from the CoralTemplates project.