Azure DevOps CLI dans Azure PIPELINE YAML

Azure DevOps Services

Note

Cette fonctionnalité est déployée cette semaine et la prochaine. Si vous ne voyez pas encore la fonctionnalité sur votre projet Azure DevOps Services, revenez en quelques jours.

Azure DevOps CLI vous permet de gérer Azure DevOps ressources à partir de la ligne de commande. Exécutez des commandes CLI dans un pipeline YAML avec la tâche AzureCLI@3 pour automatiser les tâches DevOps courantes dans le cadre de votre flux de travail CI/CD. les agents Microsoft hébergés Windows et Linux incluent déjà Azure CLI et l’extension CLI Azure DevOps.

Pour l’authentification, utilisez une connexion de service Azure DevOps prise en charge par la fédération des identités de charges de travail de Microsoft Entra. Nous vous recommandons cette approche, car elle élimine la gestion des informations d’identification. Utilisez un jeton d’accès personnel (PAT) uniquement lorsqu’une connexion de service n’est pas disponible.

S’authentifier avec Azure DevOps

Certaines commandes CLI Azure DevOps, telles que az devops configure et az devops --help, ne nécessitent aucune authentification. Ils ne se connectent pas à Azure DevOps. 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 :

L’utilisation de System.AccessToken s’appuie sur un PAT. En guise d’alternative plus sécurisée, utilisez une connexion de service. Pour obtenir des conseils d’installation, consultez Gérer les connexions de service.

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

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

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

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

Connectez-vous à Azure DevOps CLI avec des agents hébergés par Windows et Linux

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

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

Cet exemple s’authentifie avec Azure DevOps CLI. Il utilise le 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)

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

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

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

Mettre à niveau la version Azure CLI de l’agent hébergé

les agents hébergés par Microsoft déploient des mises à jour hebdomadaires de logiciels sur les environnements virtuels. Pour certains outils, la dernière version au moment du déploiement est utilisée. Dans d’autres cas, l’outil est épinglé à des versions spécifiques.

  • Pour vérifier les logiciels inclus et leurs versions pour les agents hébergés par Microsoft, y compris la version installée de Azure CLI et l’extension CLI Azure DevOps, suivez la table Included Software liens dans la table Software.
  • Pour vérifier la version actuelle de Azure CLI, consultez How to install the Azure CLI.

Vous pouvez mettre à niveau les Azure CLI sur vos images hébergées 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 votre pipeline s'exécute sur plusieurs images de machine virtuelle hébergées Microsoft, dont certaines n'ont pas installé l'extension CLI Azure DevOps, vous pouvez l'installer de manière conditionnelle.

trigger:
- main

# Run on multiple Microsoft-hosted agent images
strategy:
  matrix:
    linux24:
      imageName: "ubuntu-24.04"
    linux22:
      imageName: "ubuntu-22.04"
    mac15:
      imageName: "macos-15"
    mac14:
      imageName: "macos-14"
    windows2025:
      imageName: "windows-2025"
  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

Vous pouvez utiliser les méthodes suivantes pour installer ou mettre à niveau l’interface CLI Azure DevOps dans votre agent auto-hébergé.

Installer manuellement Azure CLI et l’extension CLI Azure DevOps

L’installation Azure CLI et l’extension CLI Azure DevOps sur votre agent auto-hébergé lorsque vous approvisionnez l’image de machine virtuelle pour l’agent est 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ée, consultez Installer le Azure CLI. Il existe des instructions distinctes pour Windows, Linux et macOS.

Après avoir installé Azure CLI, installez l’extension CLI Azure DevOps.

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

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

# 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'

Installez Azure CLI extension DevOps :

  • Azure CLI version 2.10.1 ou ultérieure est installée.
  • Une version de bash est 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 CLI Azure DevOps.

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 CLI Azure DevOps à une variable

Pour stocker les résultats d’un appel CLI Azure DevOps à une variable de pipeline, utilisez la syntaxe task.setvariable décrite dans Set variables dans les scripts. L’exemple suivant obtient l’ID d’un groupe de variables nommé Fabrikam-2023 et 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'

S’authentifier avec une connexion de service

Lorsque vous utilisez une connexion de service, la connexion de service fournit les informations d’identification nécessaires pour Azure CLI et Azure DevOps commandes CLI dans la tâche AzureCLI@3 sans nécessiter de gestion manuelle des informations d’identification dans le pipeline.

Note

Lorsque vous utilisez une connexion de service pour l’authentification avec AzureCLI@3, vous devez ajouter le principal de service à votre organisation Azure DevOps.

Pour obtenir des conseils sur les bonnes pratiques de connexion aux services sans besoin de jetons d'accès personnel (PAT), consultez Gérer les connexions de service.

Cet exemple de code définit un nouveau paramètre, serviceConnectionavec le nom d’une connexion de service existante. Ce paramètre est référencé dans la AzureCLI@3 tâche. Le script utilise une connexion sans secret pour appeler un point de terminaison REST, puis répertorie les projets et les pools.

trigger:
  - main

parameters:
- name: serviceConnection
  displayName: Azure DevOps Service Connection Name
  type: string
  default: my-service-connection

steps:
  - task: AzureCLI@3
    displayName: Secret-less
    inputs:
      connectionType: 'azureDevOps'
      azureDevOpsServiceConnection: '${{ parameters.serviceConnection }}'
      scriptType: 'pscore'
      scriptLocation: 'inlineScript'
      inlineScript: |
        az rest --method get `
                --url "https://status.dev.azure.com/_apis/status/health?api-version=7.1-preview.1" `
                --resource 499b84ac-1321-427f-aa17-267ca6975798 `
                --query "sort_by(services[?id=='Pipelines'].geographies | [], &name)" `
                -o table

        az devops configure -l

        az devops project list --query "value[].{Name:name, Id:id}" `
                              -o table

        az pipelines pool list --query "[].{Id:id, Name:name}" `
                              -o table
      failOnStandardError: true

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

Pour stocker les résultats d’un appel CLI Azure DevOps à une variable de pipeline, utilisez la syntaxe task.setvariable décrite dans Set variables dans les scripts. L’exemple suivant obtient l’ID d’un groupe de variables nommé kubernetes et utilise cette valeur dans une étape suivante.

trigger:
  - main

variables:
- name: variableGroupId

parameters:
- name: serviceConnection
  displayName: Azure DevOps Service Connection Name
  type: string
  default: my-service-connection

steps:
  - task: AzureCLI@3
    displayName: Set variable group ID
    inputs:
      connectionType: 'azureDevOps'
      azureDevOpsServiceConnection: '${{ parameters.serviceConnection }}'
      scriptType: 'pscore'
      scriptLocation: 'inlineScript'
      inlineScript: |
        az devops configure -l

        $id = az pipelines variable-group list --group-name kubernetes --query [].id -o tsv
        Write-Host "##vso[task.setvariable variable=variableGroupId]$id"

  - task: AzureCLI@3
    displayName: List variable group variables
    inputs:
      connectionType: 'azureDevOps'
      azureDevOpsServiceConnection: '${{ parameters.serviceConnection }}'
      scriptType: 'pscore'
      scriptLocation: 'inlineScript'
      inlineScript: |
        az pipelines variable-group variable list --group-id '$(variableGroupId)'

Pour obtenir d’autres exemples d’utilisation de variables, notamment l’utilisation de variables sur plusieurs travaux et phases, 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 Azure CLI sortie de commande à l’aide d’une requête JMESPath.

Contenu connexe

  • Last updated on