Spécifier des travaux dans votre pipeline

Dans le cas le plus simple, un pipeline comporte un seul travail. Il n’est alors pas nécessaire d’utiliser explicitement le mot clé job, à moins de recourir à un modèle. Vous pouvez spécifier directement les étapes dans votre fichier YAML.

Ce fichier YAML comprend un travail qui s’exécute sur un agent hébergé par Microsoft et génère Hello world.

pool:
  vmImage: 'ubuntu-latest'
steps:
- bash: echo "Hello world"

Vous pouvez spécifier d’autres propriétés sur ce travail. Dans ce cas, utilisez le mot clé job.

jobs:
- job: myJob
  timeoutInMinutes: 10
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - bash: echo "Hello world"

Votre pipeline peut comporter plusieurs travaux. Dans ce cas, utilisez le mot clé jobs.

jobs:
- job: A
  steps:
  - bash: echo "A"

- job: B
  steps:
  - bash: echo "B"

Votre pipeline peut comprendre plusieurs phases, chacune décomposée en plusieurs travaux. Dans ce cas, utilisez le mot clé stages.

stages:
- stage: A
  jobs:
  - job: A1
  - job: A2

- stage: B
  jobs:
  - job: B1
  - job: B2

La syntaxe complète pour spécifier un travail est la suivante :

- job: string  # name of the job, A-Z, a-z, 0-9, and underscore
  displayName: string  # friendly name to display in the UI
  dependsOn: string | [ string ]
  condition: string
  strategy:
    parallel: # parallel strategy
    matrix: # matrix strategy
    maxParallel: number # maximum number simultaneous matrix legs to run
    # note: `parallel` and `matrix` are mutually exclusive
    # you may specify one or the other; including both is an error
    # `maxParallel` is only valid with `matrix`
  continueOnError: boolean  # 'true' if future jobs should run even if this job fails; defaults to 'false'
  pool: pool # agent pool
  workspace:
    clean: outputs | resources | all # what to clean up before the job runs
  container: containerReference # container to run this job inside
  timeoutInMinutes: number # how long to run the job before automatically cancelling
  cancelTimeoutInMinutes: number # how much time to give 'run always even if cancelled tasks' before killing them
  variables: { string: string } | [ variable | variableReference ] 
  steps: [ script | bash | pwsh | powershell | checkout | task | templateReference ]
  services: { string: string | container } # container resources to run as a service container

La syntaxe complète pour spécifier un travail est la suivante :

- job: string  # name of the job, A-Z, a-z, 0-9, and underscore
  displayName: string  # friendly name to display in the UI
  dependsOn: string | [ string ]
  condition: string
  strategy:
    parallel: # parallel strategy
    matrix: # matrix strategy
    maxParallel: number # maximum number simultaneous matrix legs to run
    # note: `parallel` and `matrix` are mutually exclusive
    # you may specify one or the other; including both is an error
    # `maxParallel` is only valid with `matrix`
  continueOnError: boolean  # 'true' if future jobs should run even if this job fails; defaults to 'false'
  pool: pool # agent pool
  workspace:
    clean: outputs | resources | all # what to clean up before the job runs
  container: containerReference # container to run this job inside
  timeoutInMinutes: number # how long to run the job before automatically cancelling
  cancelTimeoutInMinutes: number # how much time to give 'run always even if cancelled tasks' before killing them
  variables: { string: string } | [ variable | variableReference ] 
  steps: [ script | bash | pwsh | powershell | checkout | task | templateReference ]
  services: { string: string | container } # container resources to run as a service container
  uses: # Any resources (repos or pools) required by this job that are not already referenced
    repositories: [ string ] # Repository references to Azure Git repositories
    pools: [ string ] # Pool names, typically when using a matrix strategy for the job

Si l’objectif principal de votre travail consiste à déployer votre application (par opposition à générer ou tester votre application), vous pouvez utiliser un type de travail spécial appelé travail de déploiement.

La syntaxe d’un travail de déploiement est la suivante :

- deployment: string        # instead of job keyword, use deployment keyword
  pool:
    name: string
    demands: string | [ string ]
  environment: string
  strategy:
    runOnce:
      deploy:
        steps:
        - script: echo Hi!

Bien qu’il soit possible d’ajouter des étapes de tâches de déploiement dans un job, nous vous recommandons d’utiliser plutôt un travail de déploiement. Un travail de déploiement présente quelques avantages. Par exemple, vous pouvez effectuer un déploiement dans un environnement, ce qui permet notamment de voir l’historique de ce que vous avez déployé.

pool:
  name: myPrivateAgents    # your job runs on an agent in this pool
  demands: agent.os -equals Windows_NT    # the agent must have this capability to run the job
steps:
- script: echo hello world

Le code se présente ainsi dans le cas de demandes multiples :

pool:
  name: myPrivateAgents
  demands:
  - agent.os -equals Darwin
  - anotherCapability -equals somethingElse
steps:
- script: echo hello world

La syntaxe complète pour spécifier un travail de serveur est la suivante :

jobs:
- job: string
  timeoutInMinutes: number
  cancelTimeoutInMinutes: number
  strategy:
    maxParallel: number
    matrix: { string: { string: string } }

  pool: server # note: the value 'server' is a reserved keyword which indicates this is an agentless job

Vous pouvez également utiliser la syntaxe simplifiée :

jobs:
- job: string
  pool: server # note: the value 'server' is a reserved keyword which indicates this is an agentless job

La syntaxe pour définir plusieurs travaux et leurs dépendances est la suivante :

jobs:
- job: string
  dependsOn: string
  condition: string

Voici quelques exemples de travaux générés séquentiellement :

jobs:
- job: Debug
  steps:
  - script: echo hello from the Debug build
- job: Release
  dependsOn: Debug
  steps:
  - script: echo hello from the Release build

Voici quelques exemples de travaux générés en parallèle (sans dépendance) :

jobs:
- job: Windows
  pool:
    vmImage: 'windows-latest'
  steps:
  - script: echo hello from Windows
- job: macOS
  pool:
    vmImage: 'macOS-latest'
  steps:
  - script: echo hello from macOS
- job: Linux
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - script: echo hello from Linux

Voici un exemple de distribution ramifiée :

jobs:
- job: InitialJob
  steps:
  - script: echo hello from initial job
- job: SubsequentA
  dependsOn: InitialJob
  steps:
  - script: echo hello from subsequent A
- job: SubsequentB
  dependsOn: InitialJob
  steps:
  - script: echo hello from subsequent B

Exemple de distribution non ramifiée :

jobs:
- job: InitialA
  steps:
  - script: echo hello from initial A
- job: InitialB
  steps:
  - script: echo hello from initial B
- job: Subsequent
  dependsOn:
  - InitialA
  - InitialB
  steps:
  - script: echo hello from subsequent

Lorsque plusieurs travaux sont spécifiés dans un pipeline de build, ils s’exécutent en parallèle par défaut. Vous pouvez préciser l’ordre dans lequel ils doivent se lancer en configurant les dépendances entre les travaux. Ces dépendances ne sont pas prises en charge dans les pipelines de mise en production. Les travaux d’un pipeline de mise en production s’exécutent dans l’ordre.

Voici un exemple d’exécution d’un travail en fonction de l’état de l’exécution d’un travail précédent :

jobs:
- job: A
  steps:
  - script: exit 1

- job: B
  dependsOn: A
  condition: failed()
  steps:
  - script: echo this will run when A fails

- job: C
  dependsOn:
  - A
  - B
  condition: succeeded('B')
  steps:
  - script: echo this will run when B runs and succeeds

Voici un exemple d’utilisation d’une condition personnalisée :

jobs:
- job: A
  steps:
  - script: echo hello

- job: B
  dependsOn: A
  condition: and(succeeded(), eq(variables['build.sourceBranch'], 'refs/heads/main'))
  steps:
  - script: echo this only runs for master

Vous pouvez spécifier qu’un travail s’exécute en fonction de la valeur d’une variable de sortie définie dans un travail précédent. Dans ce cas, seules les variables définies dans des travaux directement dépendants peuvent être utilisées :

jobs:
- job: A
  steps:
  - script: "echo '##vso[task.setvariable variable=skipsubsequent;isOutput=true]false'"
    name: printvar

- job: B
  condition: and(succeeded(), ne(dependencies.A.outputs['printvar.skipsubsequent'], 'true'))
  dependsOn: A
  steps:
  - script: echo hello from B

Utilisez l’option Exécuter ce travail sur un agent ou un travail de serveur pour n’exécuter les tâches que lorsque des conditions spécifiques sont remplies. Sélectionnez une condition prédéfinie, ou sélectionnez « personnalisé » et entrez une expression qui prend la valeur true ou false. Des expressions imbriquées peuvent être utilisées. Par ailleurs, les expressions peuvent accéder aux variables disponibles dans le pipeline de mise en production.

timeoutInMinutes permet de fixer la limite du temps d’exécution du travail. Quand elle n’est pas spécifiée, la valeur par défaut est de 60 minutes. Si elle est égale à 0, la limite maximale est utilisée (cf. ci-dessus).

cancelTimeoutInMinutes permet de fixer la limite du délai d’annulation du travail lorsque la tâche de déploiement est définie de façon à continuer à s’exécuter en cas d’échec d’une tâche précédente. Quand elle n’est pas spécifiée, la valeur par défaut est de 5 minutes. La valeur doit être comprise entre 1 et 35 790 minutes.

jobs:
- job: Test
  timeoutInMinutes: 10 # how long to run the job before automatically cancelling
  cancelTimeoutInMinutes: 2 # how much time to give 'run always even if cancelled tasks' before stopping them

La stratégie matrix permet de répartir un travail plusieurs fois, avec différents ensembles de variables. La balise maxParallel limite la quantité de parallélisme. Le travail suivant est réparti trois fois avec les valeurs Emplacement et Navigateur définies comme spécifié. Toutefois, seuls deux travaux s’exécutent en même temps.

jobs:
- job: Test
  strategy:
    maxParallel: 2
    matrix: 
      US_IE:
        Location: US
        Browser: IE
      US_Chrome:
        Location: US
        Browser: Chrome
      Europe_Chrome:
        Location: Europe
        Browser: Chrome

Il est également possible d’utiliser des variables de sortie pour générer une matrice. Cette solution peut se révéler pratique si vous devez pour cela passer par un script.

matrix accepte une expression runtime contenant un objet JSON stringifié. Lorsqu’il est développé, cet objet JSON doit correspondre à la syntaxe de matrice. Dans l’exemple ci-dessous, la chaîne JSON est codée en dur, mais elle peut être générée par un langage de script ou un programme de ligne de commande.

jobs:
- job: generator
  steps:
  - bash: echo "##vso[task.setVariable variable=legs;isOutput=true]{'a':{'myvar':'A'}, 'b':{'myvar':'B'}}"
    name: mtrx
  # This expands to the matrix
  #   a:
  #     myvar: A
  #   b:
  #     myvar: B
- job: runner
  dependsOn: generator
  strategy:
    matrix: $[ dependencies.generator.outputs['mtrx.legs'] ]
  steps:
  - script: echo $(myvar) # echos A or B depending on which leg is running

La stratégie parallel permet de dupliquer un travail plusieurs fois. Les variables System.JobPositionInPhase et System.TotalJobsInPhase sont ajoutées à chaque travail. Les variables peuvent ensuite être utilisées dans les scripts pour répartir la charge entre les travaux (cf. Exécution parallèle et multiple à l’aide de travaux d’agent).

Le travail suivant est réparti cinq fois avec les valeurs de System.JobPositionInPhase et de System.TotalJobsInPhase correctement définies.

jobs:
- job: Test
  strategy:
    parallel: 5

Voici un exemple de définition de variables dans un travail et d’utilisation dans des tâches.

variables:
  mySimpleVar: simple var value
  "my.dotted.var": dotted var value
  "my var with spaces": var with spaces value

steps:
- script: echo Input macro = $(mySimpleVar). Env var = %MYSIMPLEVAR%
  condition: eq(variables['agent.os'], 'Windows_NT')
- script: echo Input macro = $(mySimpleVar). Env var = $MYSIMPLEVAR
  condition: in(variables['agent.os'], 'Darwin', 'Linux')
- bash: echo Input macro = $(my.dotted.var). Env var = $MY_DOTTED_VAR
- powershell: Write-Host "Input macro = $(my var with spaces). Env var = $env:MY_VAR_WITH_SPACES"

$(Build.ArtifactStagingDirectory) et $(Common.TestResultsDirectory) sont toujours supprimés et recréés avant chaque build.

Lorsque vous exécutez un pipeline sur un agent autohébergé, par défaut, aucun des sous-répertoires autres que $(Build.ArtifactStagingDirectory) et $(Common.TestResultsDirectory) n’est nettoyé entre deux exécutions consécutives. Vous pouvez donc exécuter des builds et des déploiements incrémentiels, à condition que des tâches soient implémentées pour cela. Il est possible de remplacer ce comportement en utilisant le paramètre workspace sur le travail.

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

Les options clean spécifiées sont interprétées comme suit :

• outputs : supprimer le répertoire Build.BinariesDirectory avant d’exécuter un nouveau travail.
• resources : supprimer le répertoire Build.SourcesDirectory avant d’exécuter un nouveau travail.
• all : supprimez l’intégralité du répertoire Pipeline.Workspace avant d’exécuter un nouveau travail.

  jobs:
  - deployment: MyDeploy
    pool:
      vmImage: 'ubuntu-latest'
    workspace:
      clean: all
    environment: staging

En plus de l’option clean de l’espace de travail, vous pouvez également configurer le nettoyage en définissant le paramètre Nettoyer dans l’interface utilisateur des paramètres du pipeline. Lorsque le paramètre Nettoyer a la valeur true (qui constitue également sa valeur par défaut), il équivaut à spécifier clean: true pour chaque étape checkout du pipeline. Si vous spécifiez clean: true, vous exécutez git clean -ffdx suivi de git reset --hard HEAD avant la récupération (fetch) Git. Pour configurer le paramètre Nettoyer, procédez comme suit :

1. Modifiez votre pipeline, choisissez …, puis sélectionnez Déclencheurs.

   

2. Sélectionnez YAML et Obtenir des sources, puis configurez le paramètre Nettoyer souhaité. La valeur par défaut est true.

   

# test and upload my code as an artifact named WebSite
jobs:
- job: Build
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - script: npm test
  - task: PublishBuildArtifacts@1
    inputs:
      pathtoPublish: '$(System.DefaultWorkingDirectory)'
      artifactName: WebSite

# download the artifact and deploy it only if the build job succeeded
- job: Deploy
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - checkout: none #skip checking out the default repository resource
  - task: DownloadBuildArtifacts@0
    displayName: 'Download Build Artifacts'
    inputs:
      artifactName: WebSite
      downloadPath: $(Pipeline.Workspace)

  dependsOn: Build
  condition: succeeded()

Vous pouvez également choisir de télécharger des artefacts spécifiques pendant l’exécution du travail dans une mise en production. Utilisez cette option si les tâches d’un travail particulier ne reposent que sur des artefacts spécifiques.

Le jeton OAuth est toujours disponible pour les pipelines YAML. Il doit être mappé explicitement à la tâche ou à l’étape à l’aide de env. Voici un exemple :

steps:
- powershell: |
    $url = "$($env:SYSTEM_TEAMFOUNDATIONCOLLECTIONURI)$env:SYSTEM_TEAMPROJECTID/_apis/build/definitions/$($env:SYSTEM_DEFINITIONID)?api-version=4.1-preview"
    Write-Host "URL: $url"
    $pipeline = Invoke-RestMethod -Uri $url -Headers @{
      Authorization = "Bearer $env:SYSTEM_ACCESSTOKEN"
    }
    Write-Host "Pipeline = $($pipeline | ConvertTo-Json -Depth 100)"
  env:
    SYSTEM_ACCESSTOKEN: $(system.accesstoken)