Links

Definitions

Term	Definition
Artifact	item from a git repository or a build pipeline
Stages	steps to deploy and validate a software a stage contains jobs
Job	subparts of a stage, contains tasks to execute listed as steps a job runs on a agent or can be manually ran
Tasks / Steps	subparts of a job, those are the concreate action to execute
Release pipeline definition	steps to execute to get the artefacts, install and validate the software template to run a release
Release agent	the one who execute the tasks defined in the release pipeline definition it is the same agent as the one used for the build

Steps of a release

Build the software with a pipeline
- validate product quality (unit tests, SonarCloud)
Deploy the software
- validate runtime stability (compare telemetry with previous version)
Release the feature
- validate feature usage

Release variables

Predefined variables

Name	Value
System.DefaultWorkingDirectory	E:\Agent\Release_INT_2\_work\24\s
System.ArtifactsDirectory	E:\Agent\Release_INT_2\_work\24\a
Pipeline.Workspace	E:\Agent\Release_INT_2\_work\24

Trigger pipeline for PR

Azure DevOps → MyProject → Project Settings (bottom left gear)
Repos → Repositories → MyRepo
Policies → Branch Policies → master
Build Validation → +

Artifact

YAML

Create a new pipeline

From an existing YAML file

Pipelines → New pipeline
Azure Repo Git YAML → Select your repo → Existing Azure pipelines YAML file

Exemple

# do not trigger the pipeline on events
trigger: none

parameters:
- name: myStepList
  type: stepList
  default:
    - bash: echo "We are on $(MyVar)"

# If you have a single stage, you can omit the stages keyword and directly specify the jobs keyword
stages:
- stage: CI
  displayName: CI stage
  # remove implicite depency on the previous stage, the stages will run in parallel
  dependsOn: []
  jobs:
  - job: ci_job
    pool: MyPool
    # If you have a single stage and a single job, you can omit the stages and jobs keywords and directly specify the steps keyword
    steps:
    - powershell: Write-Host "We are on CI"
      enabled: false  # disable the task

- stage: PROD
  displayName: PROD stage
  dependsOn: []
  jobs:
  # use deployment job with environment and strategy to use the approval mechanism
  - deployment: prod_job
    environment: PROD
    strategy:
      runOnce:
        deploy:
          steps: ${{ parameters.myStepList }}

Trigger

If you specify no push trigger, pushes to any branch trigger a build.

trigger:
  batch: true # batch changes if true; start a new build for every push if false (default)
  branches:
    include: # branch names which will trigger a build
    - master
    - release/*
    exclude: temp # branch names which will not
  paths:
    include: MyProject/* # file paths which must match to trigger a build
    exclude: temp # file paths which will not trigger a build

trigger: none # will disable CI builds entirely

Stage

stages:
- stage: stage_name  # (A-Z, a-z, 0-9, and underscore)
  # friendly name to display in the UI
  displayName: 'Stage name'

  variables: # ...
  condition: # ...

  jobs: [ job | templateReference]

Job

jobs:
- job: job_name  # (A-Z, a-z, 0-9, and underscore)
  # friendly name to display in the UI
  displayName: 'Job name'

  variables: # ...

  pool: PoolName

  dependsOn: job1
  dependsOn:
  - job1
  - job2

  condition: # ...

  # what to clean up before the job runs
  workspace:
    clean: outputs | resources | all

  steps: [ script | bash | pwsh | powershell | checkout | task | templateReference ]

Task

steps:

# step
- task: TaskToCall@Version  # VSBuild@1
  name: StepName  # A-Z, a-z, 0-9, and underscore
  displayName: 'My Step'
  timeoutInMinutes: 120
  inputs:
    key: 'value'
  enabled: boolean

# runs a script in Bash
- bash: |
    which bash
    echo Hello $(whoami)
  # friendly name displayed in the UI
  displayName: Multiline Bash script

# runs a script in PowerShell Core
- pwsh: Write-Host Hello $(name)

# runs a script in Windows PowerShell
- powershell: Write-Host Hello $(name)

# checkout git repo
- checkout: self | none | repository name # self represents the repo where the initial Pipelines YAML file was found
  clean: boolean  # if true, run `execute git clean -ffdx && git reset --hard HEAD` before fetching
  fetchDepth: number  # the depth of commits to ask Git to fetch

Shallow fetch

PowerShell task

- powershell: 'cmd'
# 4 blank characters before the command
- powershell: |
    cmd1
    cmd2

# pwsh runs PowerShell Core, which must be installed on the agent or container.
- pwsh: 'cmd'

- task: PowerShell@2
  displayName: 'PowerShell Script'
  inputs:
    targetType: filePath
    filePath: 'MyScript.ps1'
    arguments: '-Arg1 "Arg1"'

- task: PowerShell@2
  displayName: 'PowerShell Script'
  inputs:
    targetType: inline
    script: |
      cmd1
      cmd2

Publish artifact

steps:
- task: PublishPipelineArtifact@1
  inputs:
    # the path to the folder or file you want to publish
    targetPath: $(System.DefaultWorkingDirectory)/bin/WebApp
    artifactName: WebApp

Download pipeline artifact

steps:

# to stop artifacts from being downloaded automatically
- download: none

- task: DownloadPipelineArtifact@2
  inputs:
    artifact: ArtifactName

# artifact from another pipeline
- task: DownloadPipelineArtifact@2
  inputs:
    buildType: 'specific' # current (default), specific
    project: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' # Required when buildType = specific
    pipeline: '0000' # Required when source = specific
    buildVersionToDownload: 'specific'
    buildId: '000000' # Required when source = specific && RunVersion = specific
    artifact: ArtifactName
    downloadPath: '$(Pipeline.Workspace)' # relative path is concat to $(System.DefaultWorkingDirectory)

The Download Pipeline Artifact task can download both build artifacts (published with the Publish Build Artifacts task) and pipeline artifacts.
By default, files are downloaded to $(Pipeline.Workspace)/{artifact}
Downloading artifacts
Get project GUID: https://dev.azure.com/{organization}/_apis/projects
Get the pipeline definition ID: https://dev.azure.com/{organization}/{project}/_apis/build/definitions?name={pipeline name}
Get the build ID: https://dev.azure.com/{organization}/{project}/_apis/build/builds?definitions={pipeline definition ID}&buildNumber=x.x.xxxx.xxxxx
Get Artifact name: https://dev.azure.com/{organization}/{project}/_apis/build/builds/{buildId}/artifacts

Download Build Artifacts

- task: DownloadBuildArtifacts@0
  inputs:
    buildType: 'specific' # current (default), specific
    project: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' # Required when buildType = specific
    pipeline: '0000' # Required when source = specific
    buildVersionToDownload: 'specific'
    buildId: '000000' # Required when source = specific && RunVersion = specific
    artifactName: ArtifactName
    downloadPath: '$(System.ArtifactsDirectory)'

By default, files are downloaded to $(System.ArtifactsDirectory)/{artifact}

Windows Machine File Copy

- task: WindowsMachineFileCopy@2
  displayName: 'Copy Files'
  inputs:
    sourcePath: '$(sourcePath)'
    machineNames: '$(machineNames='
    adminUserName: '$(adminUserName)'
    adminPassword: '$(adminPassword)'
    targetPath: '$(targetPath)'
    additionalArguments: '/r:1 /w:10' # if a file copy fails, wait 10 seconds and retry 1 time
    cleanTargetBeforeCopy: true

PowerShell on Target Machines

- task: PowerShellOnTargetMachines@3
  inputs:
    machines: '$(machines)'
    userName: '$(userName)'
    userPassword: '$(userPassword)'
    scriptType: 'filePath' # inline by default
    scriptPath: '$(scriptPath)'
    scriptArguments: '-Arg1 $(Arg1Value)'
    communicationProtocol: http

- task: PowerShellOnTargetMachines@3
  inputs:
    machines: '$(machines)'
    userName: '$(userName)'
    userPassword: '$(userPassword)'
    scriptType: 'inline' # inline by default
    inlineScript: |
      echo 'Hello !'
    communicationProtocol: http

Pool

# if you use a private pool and don't need to specify demands
pool: PoolName

pool:
  name: PoolName
  demands:
  - myCustomCapability       # check for existence of capability
  - agent.os -equals Darwin  # check for specific string in capability

Variables

# scope: root, stage, job
variables:
  variable_name: 'value'

variables:
- name: variable_name
  value: 'value'
# groups are used to make variables inside that group available across multiple pipelines
- group: group_name

steps:
- powershell: 'echo $(System.StageName) - $(variable_name) - $(group_variable_name)'

Runtime parameters

Ces paramètres sont sélectionnable à chaque lancement de la pipeline.

parameters:
- name: my_parameter
  displayName: My parameter
  type: string
  default: Value1
  values:
  - Value1
  - Value2

Repositories

resources:
  repositories: 
  - repository: RepoId  # A-Z, a-z, 0-9, and underscore
    name: ProjectName/RepoName  # repository name (format depends on `type`)
    type: git 
    ref: master

steps:
  - checkout: self    # checkout in $(Build.SourcesDirectory)\CurrentRepoId (C:\agent\_work\1\s\CurrentRepoId)
  - checkout: RepoId  # checkout in $(Build.SourcesDirectory)\RepoId (C:\agent\_work\1\s\RepoId)

Condition

# scope: stage, job, task
condition: eq(variables.Var1, 'Value1')
# parameter
condition: eq('${{ parameters.Param1 }}', 'Value1')
# or
condition: or(eq(variables.Var1, 'Value1'), ne(variables.Var2, 'Value2'))
# in
condition: in(variables['Build.Reason'], 'IndividualCI', 'BatchedCI')

if statement

${{ if eq(variables['Build.SourceBranchName'], 'master') }}:

${{ if eq(parameters.MyParam, 'value') }}:

Template

Insert a template

Reuse stages, jobs ans tasks.

stages-template.yml

stages:
- stage: Stage1
  jobs:
  - job: Job1
    steps:
    - script: echo 'stages template'

jobs-template.yml

jobs:
- job: Job1
  steps:
  - script: echo 'jobs template'

tasks-template.yml

steps:
- script: echo 'tasks template'

my-pipeline.yml

stages:
- template: stages-template.yml
- stage: Stage2
  jobs:
  - template: jobs-template.yml
- stage: Stage3
  jobs:
  - job: ExcecuteTasks
    steps:
    - template: tasks-template.yml

Extend from a template

Copy the template in the pipeline.

my-template.yml

resources:
  repositories: 
  - repository: MyRepo
    type: git 
    name: MyProject/MyRepo

steps:
- script: echo "My template"

my-pipepline.yml

extends:
  template: my-template.yml

Parameters

tasks-template.yml

parameters:
  parameterName: 'parameter value'

steps:
- script: echo ${{ parameters.parameterName}}

my-pipepline.yml

variables:
  var: 'value'

steps:
  template: tasks-template.yml
  parameters:
    parameterName: 'value'
    parameterName: ${{ variables.var }}  # $(var) doesn't work

Condition on a template

It is not possible to set a condition on a template.

Solution 1: pass a parameter to the template.

steps-template.yml

parameters:
  enabled: true

steps:
- script: echo 'Task 1'
  condition: ${{ parameters.enabled }}

my-pipepline.yml

steps:
- template: steps-template.yml
  parameters:
      enabled: false

Solution 2: use if.

my-pipepline.yml

steps:
- ${{ if eq($(MyVar), 'value') }}:
  - template: steps-template.yml

Errors

Environment xxx could not be found

Pipelines → Environments → Select the env xxx → 3 dots button on top right → Security
Add the user with User role

Azure pipeline

Links

Definitions

Steps of a release

Trigger pipeline for PR

YAML

Create a new pipeline

Exemple

Repositories

Condition on a template

Errors

Menu de navigation

Rechercher