Interface CLI Azure DevOps dans le YAML de pipeline Azure

  • Article

Azure DevOps Services

Si vous souhaitez utiliser Azure DevOps CLI avec un pipeline YAML, vous pouvez utiliser l’exemple suivant pour comprendre comment YAML peut être utilisé pour installer Azure CLI, ajouter l’extension Azure DevOps et exécuter des commandes Azure DevOps CLI.

Remarque

Les étapes décrites dans cet article montrent comment s’authentifier auprès d’Azure DevOps et exécuter az devops des commandes à l’aide de l’extension Azure DevOps CLI. Si vous souhaitez utiliser Azure CLI pour interagir avec les ressources Azure, utilisez la tâche AzureCLI.

S’authentifier auprès d’Azure DevOps

Certaines commandes Azure DevOps CLI qui n’appellent pas Azure DevOps, comme az devops configure et az devops -h, ne nécessitent pas d’authentification, mais la plupart des commandes interagissent avec Azure DevOps et nécessitent une authentification. Vous pouvez vous authentifier à l’aide du jeton de sécurité System.AccessToken utilisé par le pipeline en cours d’exécution, en l’affectant à une variable d’environnement nommée AZURE_DEVOPS_EXT_PAT, comme illustré dans l’exemple suivant.

- bash: |
    az pipelines build list
  displayName: 'Show build list'
  env:
    AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)

Si vous avez plusieurs étapes qui nécessitent une authentification, ajoutez la AZURE_DEVOPS_EXT_PAT variable d’environnement à chaque étape.

Pour plus d’informations sur l’étendue du jeton de sécurité utilisé par le pipeline en cours d’exécution, consultez référentiels d’accès, artefacts et autres ressources.

Pour plus d’informations sur l’authentification à l’aide d’un jeton d’accès personnel, consultez Se connecter avec un jeton d’accès personnel (PAT).

Azure DevOps CLI avec des agents hébergés Windows et Linux

Les agents Windows et Linux hébergés par Microsoft sont préconfigurés avec Azure CLI et l’extension Azure DevOps CLI.

L’exemple suivant montre comment se connecter à Azure DevOps et exécuter quelques commandes. Cet exemple utilise l’image de l’agent ubuntu-latest hébergé par Microsoft, mais vous pouvez la remplacer par l’une des autres images hébergées par Windows ou Linux.

Cet exemple s’authentifie auprès d’Azure DevOps CLI à l’aide du jeton de sécurité System.AccessToken utilisé par le pipeline en cours d’exécution.

trigger:
- main

pool:
  vmImage: `ubuntu-latest`

steps:
- bash: az --version
  displayName: 'Show Azure CLI version'

- bash: az devops configure --defaults organization=$(System.TeamFoundationCollectionUri) project=$(System.TeamProject) --use-git-aliases true
  displayName: 'Set default Azure DevOps organization and project'

- bash: |
    az pipelines build list
    git pr list
  displayName: 'Show build list and PRs'
  env:
    AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)

Azure DevOps CLI avec des agents hébergés macOS

Les agents hébergés par MacOS ont installé Azure CLI, mais pas l’extension Azure DevOps CLI. Pour installer l’extension Azure DevOps CLI, exécutez la commande suivante dans votre pipeline avant d’effectuer des appels Azure DevOps CLI.

# Install Azure DevOps extension
- bash: az extension add -n azure-devops
  displayName: 'Install Azure DevOps extension'

Version d’Azure CLI de l’agent hébergé

Les agents hébergés par Microsoft déploient généralement des mises à jour hebdomadaires sur le logiciel sur les environnements virtuels. Pour certains outils, la dernière version au moment du déploiement est utilisée ; pour d’autres, l’outil est épinglé à des versions spécifiques.

  • Pour case activée les logiciels inclus et leurs versions pour les agents hébergés par Microsoft, y compris la version installée d’Azure CLI et l’extension Azure DevOps CLI, suivez les liens Logiciels inclus dans la table Logiciel.
  • Pour case activée la version actuelle d’Azure CLI, consultez Comment installer Azure CLI.

Si une version plus récente d’Azure CLI est publiée et que les images hébergées n’ont pas encore la dernière version, vous pouvez mettre à niveau la version d’Azure CLI vers la dernière version en exécutant les commandes suivantes dans votre pipeline.

# Specify python version
- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.x'
    architecture: 'x64'

# Update to latest Azure CLI version
- bash: pip install --pre azure-cli
  displayName: 'Upgrade Azure CLI'

Installer de manière conditionnelle l’extension CLI Azure DevOps

Si vous disposez d’un pipeline qui s’exécute sur plusieurs images de machine virtuelle hébergées par Microsoft, dont certaines n’ont pas installé l’extension AZURE DevOps CLI, vous pouvez effectuer cette étape de manière conditionnelle, comme illustré dans l’exemple suivant.

trigger:
- main

# Run on multiple Microsoft-hosted agent images
strategy:
  matrix:
    linux22:
      imageName: "ubuntu-22.04"
    linux20:
      imageName: "ubuntu-20.04"
    mac13:
      imageName: "macos-13"
    mac12:
      imageName: "macos-12"
    mac11:
      imageName: "macos-11"
    windows2019:
      imageName: "windows-2019"
    windows2022:
      imageName: "windows-2022"
  maxParallel: 3

pool:
  vmImage: $(imageName)

steps:
- bash: az --version
  displayName: 'Show Azure CLI version'

# Install Azure DevOps CLI extension only on macOS images
- bash: az extension add -n azure-devops
  condition: contains(variables.imageName, 'mac')
  displayName: 'Install Azure DevOps extension'

# Azure DevOps CLI extension call that does not require login or credentials
# since it configures the local environment
- bash: az devops configure --defaults organization=$(System.TeamFoundationCollectionUri) project=$(System.TeamProject) --use-git-aliases true
  displayName: 'Set default Azure DevOps organization and project'

# Call that does require credentials, use the System.AccessToken PAT
# and assign to AZURE_DEVOPS_EXT_PAT which is known to Azure DevOps CLI extension
- bash: |
    az pipelines build list
    git pr list
  env:
    AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)
  displayName: 'Show build list and PRs'

Azure DevOps CLI avec des agents auto-hébergés

Si votre agent auto-hébergé n’est pas configuré avec le logiciel requis pour utiliser Azure DevOps CLI ou si vous souhaitez vous assurer que vous disposez des dernières versions, vous pouvez installer le logiciel requis en procédant comme suit.

Installer manuellement Azure CLI et l’extension Azure DevOps CLI

L’installation d’Azure CLI et de l’extension Azure DevOps CLI sur votre agent auto-hébergé lorsque vous approvisionnez l’image de machine virtuelle pour l’agent est beaucoup plus rapide que de les installer chaque fois que le pipeline est exécuté.

  • Pour installer Azure CLI sur votre image d’agent auto-hébergé, consultez Installer Azure CLI. Il existe des instructions distinctes pour Windows, Linux et macOS.
  • Après avoir installé Azure CLI, installez l’extension Azure DevOps CLI.

Installer l’extension Azure CLI et Azure DevOps CLI dans votre pipeline

L’exemple suivant de configuration de l’extension Azure CLI et Azure DevOps CLI sur un agent auto-hébergé à l’aide d’un pipeline présente les prérequis suivants.

  • Installer Azure CLI à l’aide de Python

    # Specify python version if you have side-by-side versions
- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.x'
    architecture: 'x64'

# Update pip to latest
- bash: python -m pip install --upgrade pip
  displayName: 'Upgrade pip'

# Update to latest Azure CLI version, min version required for Azure DevOps is 2.10.1
- bash: pip install --pre azure-cli
  displayName: 'Upgrade Azure CLI'

  • Installer l’extension Azure CLI DevOps

    • Azure CLI version 2.10.1 ou ultérieure est installé.
    • Une version est bash installée sur l’agent et dans le chemin d’accès. Une installation bash est requise pour utiliser la tâche bash.
    # Install Azure DevOps extension
- bash: az extension add -n azure-devops
  displayName: 'Install Azure DevOps extension'

# Now you can make calls into Azure DevOps CLI
# ...

L’exemple suivant installe Azure CLI suivi de l’extension Azure DevOps CLI.

steps:
# Specify python version if you have side-by-side versions
- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.x'
    architecture: 'x64'

# Update pip to latest
- bash: python -m pip install --upgrade pip
  displayName: 'Upgrade pip'

# Update to latest Azure CLI version, min version required for Azure DevOps is 2.10.1
- bash: pip install --pre azure-cli
  displayName: 'Upgrade Azure CLI'

# Install Azure DevOps extension
- bash: az extension add -n azure-devops
  displayName: 'Install Azure DevOps extension'

# Now you can make calls into Azure DevOps CLI
# ...

Affecter les résultats d’un appel Azure DevOps CLI à une variable

Pour stocker les résultats d’un appel Azure DevOps CLI à une variable de pipeline, utilisez la task.setvariable syntaxe décrite dans Définir des variables dans des scripts. L’exemple suivant récupère l’ID d’un groupe de variables nommé Fabrikam-2023 , puis utilise cette valeur dans une étape suivante.

variables:
- name: variableGroupId

trigger: none

pool:
  vmImage: "ubuntu-latest"

steps:
- bash: az devops configure --defaults organization=$(System.TeamFoundationCollectionUri) project=$(System.TeamProject) --use-git-aliases true
  displayName: 'Set default Azure DevOps organization and project'

- bash: echo "##vso[task.setvariable variable=variableGroupId]$(az pipelines variable-group list --group-name Fabrikam-2023 --query [].id -o tsv)"
  env:
    AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)
  displayName: 'Get Fabrikam-2023 variable group id'

- bash: az pipelines variable-group variable list --group-id $(variableGroupId)
  env:
    AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)
  displayName: 'List variables in Fabrikam-2023 variable group'

Pour obtenir d’autres exemples d’utilisation de variables, notamment l’utilisation de variables entre les travaux et les étapes, consultez Définir des variables. Pour obtenir des exemples de syntaxe de requête utilisées dans l’exemple précédent, consultez Comment interroger la sortie de commande Azure CLI à l’aide d’une requête JMESPath.