CLI de Azure DevOps en YAML de Azure Pipelines

Azure DevOps Services

Note

Esta característica se está implementando esta semana y la próxima. Si aún no ve la característica en el proyecto de Azure DevOps Services, vuelva a comprobar en unos días.

Azure DevOps CLI le permite administrar Azure DevOps recursos desde la línea de comandos. Ejecute comandos de la CLI en una canalización de YAML con la tarea AzureCLI@3 para automatizar tareas comunes de DevOps como parte del flujo de trabajo de CI/CD. Los agentes de Windows y Linux hospedados por Microsoft ya incluyen Azure CLI y la extensión de la CLI de Azure DevOps.

Para la autenticación, use una conexión de servicio de Azure DevOps respaldada por la federación de identidades de carga de trabajo de Microsoft Entra. Se recomienda este enfoque porque elimina la administración de credenciales. Use un token de acceso personal (PAT) solo cuando una conexión de servicio no esté disponible.

Autenticación con Azure DevOps

Algunos comandos de la CLI de Azure DevOps, como az devops configure y az devops --help, no requieren ninguna autenticación. No se conectan a Azure DevOps. La mayoría de los comandos interactúan con Azure DevOps y requieren autenticación.

Puede autenticarse mediante el token de seguridad System.AccessToken que usa la canalización de ejecución; para ello, asígnelo a una variable de entorno denominada AZURE_DEVOPS_EXT_PAT, como se muestra en el ejemplo siguiente.

El uso de System.AccessToken se basa en tener un PAT. Como alternativa más segura, use una conexión de servicio. Para obtener instrucciones de configuración, consulte Administración de conexiones de servicio.

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

Si tiene varios pasos que requieren autenticación, añada la variable de entorno AZURE_DEVOPS_EXT_PAT a cada paso.

Para obtener más información sobre el ámbito del token de seguridad que usa la canalización de ejecución, consulte Acceso a repositorios, artefactos y otros recursos.

Para obtener más información sobre la autenticación mediante un token de acceso personal (PAT), consulte Inicio de sesión con un token de acceso personal.

Inicio de sesión en Azure DevOps CLI con agentes hospedados de Windows y Linux

Los agentes de Windows y Linux hospedados en Microsoft están preconfigurados con Azure CLI y la extensión de la CLI de Azure DevOps.

En el ejemplo siguiente se muestra cómo iniciar sesión en Azure DevOps y ejecutar algunos comandos. En este ejemplo se usa la imagen del agente hospedado ubuntu-latest Microsoft. Puede reemplazarlo por cualquiera de las otras imágenes alojadas en Windows o Linux.

En este ejemplo se autentica con Azure DevOps CLI. Usa el token de seguridad System.AccessToken usado por la canalización en ejecución.

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)

Instalar la extensión de la CLI de Azure DevOps con agentes alojados en macOS

Los agentes de Microsoft alojados en macOS tienen Azure CLI instalado, pero no tienen la extensión de Azure DevOps CLI. Para instalar la extensión de la CLI de Azure DevOps, ejecute el siguiente comando en la canalización antes de realizar llamadas a la CLI de Azure DevOps.

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

Actualización de la versión de Azure CLI del agente hospedado

Los agentes alojados por Microsoft suelen implementar actualizaciones semanales en el software de los entornos virtuales. Para algunas herramientas, se usa la versión más reciente en el momento de la implementación. En otros casos, la herramienta está anclada a versiones específicas.

  • Para comprobar el software incluido y sus versiones para agentes hospedados por Microsoft, incluida la versión instalada de Azure CLI y la extensión de Azure DevOps CLI, siga los enlaces de Included Software en la tabla Software.
  • Para comprobar la versión actual de Azure CLI, consulte Cómo instalar el Azure CLI.

Puede actualizar el Azure CLI en las imágenes hospedadas ejecutando los siguientes comandos en la canalización.

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

Instalación condicional de la extensión de la CLI de Azure DevOps

Si la canalización se ejecuta en varias imágenes de máquina virtual hospedadas por Microsoft, algunas de las cuales no tienen la extensión CLI de Azure DevOps instalada, puede instalarse de manera condicional.

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 con agentes autohospedados

Puede usar los métodos siguientes para instalar o actualizar la CLI de Azure DevOps en el agente autohospedado.

Instalación manual de Azure CLI y extensión de la CLI de Azure DevOps

La instalación de Azure CLI y la extensión de Azure DevOps CLI en el agente autohospedado al aprovisionar la imagen de máquina virtual para el agente es más rápida que instalarlas cada vez que se ejecuta el pipeline.

Para instalar Azure CLI en la imagen del agente autohospedado, consulte Instalar el Azure CLI. Hay instrucciones independientes para Windows, Linux y macOS.

Después de instalar Azure CLI, instale la extensión de la CLI Azure DevOps.

Instala Azure CLI y la extensión de Azure DevOps CLI en tu canalización.

El siguiente ejemplo de cómo configurar Azure CLI y la extensión de la CLI de Azure DevOps en un agente autohospedado usando una canalización requiere los siguientes requisitos previos.

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

Instale Azure CLI extensión de DevOps:

  • Azure CLI versión 2.10.1 o posterior está instalado.
  • Hay una versión de bash instalada en el agente y en la ruta de acceso. Se requiere una instalación de Bash para usar la tarea 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
# ...

En el ejemplo siguiente se instala Azure CLI seguido de la extensión 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
# ...

Asignación de los resultados de una llamada de Azure DevOps CLI a una variable

Para almacenar los resultados de una llamada de la CLI de Azure DevOps a una variable de canalización, use la sintaxis task.setvariable descrita en Establecer variables en scripts. En el ejemplo siguiente se obtiene el identificador de un grupo de variables denominado Fabrikam-2023 y se usa este valor en un paso posterior.

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'

Autentícate con una conexión de servicio

Cuando se utiliza una conexión de servicio, esta proporciona las credenciales necesarias para los comandos de Azure CLI y Azure DevOps CLI en la tarea AzureCLI@3, sin que sea necesario gestionar manualmente las credenciales en la canalización.

Note

Al usar una conexión de servicio para la autenticación con AzureCLI@3, debe agregar la entidad de servicio a la organización de Azure DevOps.

Para obtener instrucciones sin PAT y procedimientos recomendados para la conexión de servicios, consulte Gestión de conexiones de servicio.

Este ejemplo de código define un nuevo parámetro, serviceConnection, con el nombre de una conexión de servicio existente. Se hace referencia a ese parámetro en la AzureCLI@3 tarea. El script usa una conexión sin secretos para llamar a un punto de conexión REST y, a continuación, enumera los proyectos y los grupos.

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

Asignación de los resultados de una llamada de Azure DevOps CLI a una variable

Para almacenar los resultados de una llamada de la CLI de Azure DevOps a una variable de canalización, use la sintaxis task.setvariable descrita en Establecer variables en scripts. En el ejemplo siguiente se obtiene el identificador de un grupo de variables denominado kubernetes y se usa este valor en un paso posterior.

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

Para obtener más ejemplos sobre cómo trabajar con variables, incluido el trabajo con variables en trabajos y fases, consulte Definir variables. Para obtener ejemplos de la sintaxis de consulta usada en el ejemplo anterior, vea Cómo consultar Azure CLI salida del comando mediante una consulta JMESPath.

Contenido relacionado

  • Last updated on