Skip to content

pipeline-good-practices.md

Latest commit

 

History

History
120 lines (88 loc) · 3.83 KB

pipeline-good-practices.md

File metadata and controls

120 lines (88 loc) · 3.83 KB

Azure DevOps Pipelines: Good Practices

Azure DevOps Pipelines are well documented in the official documentation.

Besides the official documentation, this document provides some good practices for Azure DevOps Pipelines.

Getting started

Well structured file

One main thought in structuring your Azure DevOps YAML files is to apply Clean Code and SOLID principles to your YAML files.

This means that you should separate concerns and responsibilities in your YAML files.

This can be achieved by using parameters, variables, resources, and templates.

Example: azure-pipelines.yml

# Example: azure-pipelines.yml

trigger:
  include: 
pr:
  branches:
    include:
      - main

pool:

parameters:
  - name: parameter
    value: value      


variables: # Can be derived from parameters
  - group: Library in Azure DevOps
  - name: some
    value: some-value
  - name: derived-from-parameter
    value: some${{ parameters.parameter }}
  - ${{ if eq(variables['Build.SourceBranch'], 'refs/heads/main') }}:
      - name: environment
        value: Production
  - ${{ elseif eq(variables['Build.Reason'], 'PullRequest') }}:
      - name: environment
        value: Consolidation
  - ${{ else }}:
      - name: environment
        value: Integration
       

resources: # Binding of template repositories
  repositories:
    - repository: sharedTemplates
      type: git
      name: Central.PipelineTemplates
      ref: refs/tags/v1.1.2

# now only templates
stages:
  - template: path/to/template
    parameters:
      debug: $(some) # This doesn't work with dynamically created variables in a step
  • Separate stages for separate concerns
  • Use separated stages for purposes like Test, Build, Publishing

Templates

Naming

use-kebab-case for file names and folder names, e.g. build-docker-image.yml, test-application.yml, publish-release.yml.

Folder structure

The folder structure should be organized in a way that reflects the purpose of the templates. A common structure is:

- 🚀 azure-pipelines.yml
- 📁 .azure-pipelines or template purpose e. g. test/build/ 
  - 📁 variables
  - 📁 stages
    - contains stage templates
    - should only contain very small jobs or referencing job templates
  - 📁 jobs
    - contains job templates
    - should only contain very small amount of steps
    - or better: step templates
  - 📁 steps
    - contains step templates
    - should not be too big and precise in the naming

VSC extension

For editing Azure DevOps YAML files in Visual Studio Code, I recommend the following setup:

"files.associations": {
  "**/*.yml": "azure-pipelines"
},
"azure-pipelines.tenant": "your-tenant-id",
"[azure-pipelines]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
},

Automated versioning

  • Use GitVersion to automatically generate semantic versioning based on your git history and commit messages.
  • Gitversion template is based on semvver
  • Write your commit messages according to Conventional Commits.
  • Configure your pipeline to use the GitVersion task to set the version variables.