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"

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

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

- 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

- 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

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

Pour ajouter des travaux à votre pipeline de build, modifiez ce dernier sur la page Pipelines. Sélectionnez … pour ajouter un travail.

Pour ajouter des travaux à votre pipeline de mise en production, modifiez ce dernier dans Pipelines>Mises en production. Affichez les tâches dans la phase où vous souhaitez ajouter votre travail. Sélectionnez … pour ajouter un travail.

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

Vous pouvez spécifier des demandes dans le pipeline, dans les jobs, ou les deux. Si vous spécifiez des demandes dans les deux, l’union des deux ensembles de demandes est nécessaire pour que le système sélectionne un agent.

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

Pour ajouter un travail de serveur dans l’éditeur, sélectionnez « … » dans le canal Pipeline dans l’onglet Tâches d’un pipeline. Les propriétés du travail de serveur s’affichent lorsque vous le sélectionnez dans l’éditeur.

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

Exemple de fan-out :

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

Pour ajouter un nouveau travail, sélectionnez « … » sur le canal de pipeline dans l’onglet Tâches du pipeline. Les conditions et l’ordre d’exécution d’un travail s’affichent lorsque vous sélectionnez le travail dans l’éditeur.

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.

Par exemple, le pipeline divise l’exécution globale de la mise en production en tâches d’exécution distinctes, utilisant deux tâches d’agent et une tâche serveur .

1. Les tâches du premier job de la version sont exécutées sur un agent. L’agent est libéré une fois le travail terminé.

2. Le travail serveur contient une tâche d’intervention manuelle qui s’exécute sur Azure Pipelines ou DevOps Server. Il ne s’exécute pas sur un agent ni des serveurs cibles, qui ne sont par conséquent pas nécessaires. La tâche d’intervention manuelle affiche son message et attend une réponse « reprendre » ou « rejeter » de l’utilisateur. Dans cet exemple, si la tâche atteint le délai d’expiration configuré, la tâche rejette automatiquement le déploiement. Définissez le délai d’expiration dans la section options de contrôle sur zéro si vous ne souhaitez pas générer de réponse automatisée.

3. Les tâches du troisième job sont exécutées si le lancement est repris, éventuellement sur un autre agent. Si elle est rejetée, ce travail ne s’exécute pas. La mise en production est alors marquée comme ayant échoué.

Il est important de comprendre les conséquences de l’exécution par phases :

• Chaque travail peut utiliser des agents différents. Ne partez pas du principe que l’état d’un travail antérieur est disponible pendant les travaux suivants.

• Les options Continuer en cas d’erreur et Toujours exécuter des tâches d’un travail restent sans effet sur les tâches des travaux suivants. Par exemple, l'option Toujours exécuter une tâche à la fin du premier travail ne garantit pas l'exécution des tâches dans les travaux suivants.

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. Lorsque 0 est spécifié, la limite maximale est utilisée.

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

Sélectionnez le travail, puis la valeur de délai d’expiration.

Dans l’onglet Options, vous pouvez définir des valeurs par défaut pour tous les travaux du pipeline. Si la valeur du délai d’expiration du travail est différente de zéro, elle remplace toute valeur spécifiée dans les options du pipeline. Dans le cas où elle est égale à zéro, la valeur utilisée est le délai d’expiration provenant des options du pipeline. Si la valeur du pipeline est également définie sur zéro, il n’y a pas de délai d’expiration.

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 méthode peut être pratique si vous devez générer la matrice à l’aide d’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 suivant, nous avons codé en dur la chaîne JSON, mais vous pouvez la générer avec 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

Pour exécuter plusieurs travaux selon l’option multiconfiguration, vous identifiez une variable nommée multiplicateur et lui spécifiez une liste de valeurs. Un travail distinct est exécuté pour chaque valeur de la liste. Si vous souhaitez utiliser des multiplicateurs pour la build ou le déploiement, vous devez effectuer les opérations suivantes :

• Définissez une ou plusieurs variables dans l’onglet Variables du pipeline ou dans un groupe de variables. Chaque variable, appelée dans ce contexte variable multiplicateur, doit être définie sous la forme d’une liste délimitée par des virgules des valeurs que vous souhaitez transmettre individuellement aux agents.

• Entrez le nom de la variable multiplicateur, sans $ et les parenthèses, comme valeur du paramètre Multipliers. Le recours à une variable secrète comme variable multipicateur n’est pas pris en charge.

• Si vous souhaitez exécuter le travail pour plusieurs variables multiplicateurs, entrez leur nom sous la forme d’une liste délimitée par des virgules, en omettant pour chacune d’elles $ et les parenthèses.

• Si vous souhaitez limiter le nombre d’agents utilisés pendant le déploiement à un nombre inférieur à celui que vous avez configuré pour votre abonnement, entrez cette valeur en tant que nombre maximal d’agents paramètre.

Par exemple, vous pouvez définir deux variables nommées Emplacement et Navigateur comme suit :

• Emplacement = US,Europe
• Navigateur = IE,Chrome,Edge,Firefox

La configuration suivante exécute le déploiement huit fois avec quatre agents maximum à la fois :

• Multiplicateurs = Location,Browser
• Nombre maximal d’agents = 4

Avec la multiconfiguration, vous pouvez exécuter plusieurs travaux, chacun avec une valeur différente pour une ou plusieurs variables (multiplicateurs). Si vous souhaitez exécuter le même travail sur plusieurs agents, utilisez l’option de parallélisme multiagent. L’exemple précédent de découpage de test peut être effectué via l’option multi-agent.

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

Spécifiez l’option multiagent sur un travail d’agent pour appliquer le découpage. Le travail est réparti autant de fois que vous avez spécifié d’agents, et les variables System.JobPositionInPhase et System.TotalJobsInPhase sont automatiquement définies dans chaque travail.

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"

Les variables de travail ne sont pas encore prises en charge dans l’éditeur web.

Les $(Build.ArtifactStagingDirectory) et les $(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. Par conséquent, vous pouvez effectuer des builds et des déploiements incrémentiels, si des tâches sont implémentées pour les utiliser. 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. Lorsque vous spécifiez clean: true, vous exécutez git clean -ffdx suivi de git reset --hard HEAD avant la récupération 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.

   

Lorsque vous exécutez un pipeline sur un agent autohébergé, aucun des sous-répertoires n’est par défaut nettoyé entre deux exécutions consécutives. Par conséquent, vous pouvez exécuter des builds et des déploiements incrémentiels, si des tâches sont implémentées pour ce faire. Toutefois, il est possible de remplacer ce comportement en utilisant l’option Clean build sous la tâche Get sources. Les options varient en fonction du type de référentiel.

• GitHub
• Azure Repos Git
• TFVC

# 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()

Dans un pipeline de validation, vous pouvez choisir de ne pas télécharger les artefacts pendant l'exécution du travail. Utilisez cette option si vous souhaitez implémenter votre propre logique personnalisée pour télécharger des artefacts à l’aide de tâches, ou si les tâches d’un travail particulier ne reposent pas sur les artefacts.

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)

Sélectionnez l’option Autoriser les scripts à accéder au jeton OAuth dans les options de contrôle du travail. Le jeton est disponible en tant que variable d’environnement SYSTEM_ACCESSTOKEN.