CLI de Azure DevOps en YAML de Azure Pipeline

  • Artículo

Azure DevOps Services

Si desea usar la CLI de Azure DevOps con una canalización YAML, puede usar el ejemplo siguiente para comprender cómo se puede usar YAML para instalar la CLI de Azure, agregar la extensión de Azure DevOps y ejecutar comandos de la CLI de Azure DevOps.

Nota:

Los pasos de este artículo muestran cómo autenticarse con Azure DevOps y ejecutar az devops comandos mediante la extensión de la CLI de Azure DevOps. Si desea usar la CLI de Azure para interactuar con los recursos de Azure, use la tarea AzureCLI.

Autenticación con Azure DevOps

Algunos comandos de la CLI de Azure DevOps que no llaman a Azure DevOps, como az devops configure y az devops -h, no requieren ninguna autenticación, pero la mayoría de los comandos interactúan con Azure DevOps y requieren autenticación. Puede autenticarse mediante el token de seguridad System.AccessToken usado por la canalización en ejecución; para ello, asígnelo a una variable de entorno denominada AZURE_DEVOPS_EXT_PAT, como se muestra en el ejemplo siguiente.

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

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

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

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

CLI de Azure DevOps con agentes hospedados en Windows y Linux

Los agentes de Windows y Linux hospedados por Microsoft están preconfigurados con la CLI de Azure 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 ubuntu-latest imagen del agente hospedado por Microsoft, pero puede reemplazarla por cualquiera de las demás imágenes hospedadas de Windows o Linux.

En este ejemplo se autentica con la CLI de Azure DevOps mediante 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)

CLI de Azure DevOps con agentes hospedados en macOS

Los agentes hospedados por Microsoft para macOS tienen instalada la CLI de Azure, pero no la extensión de la CLI de Azure DevOps. 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'

Versión de la CLI de Azure del agente hospedado

Normalmente, los agentes hospedados por Microsoft implementan actualizaciones semanales en el software en los entornos virtuales. Para algunas herramientas, se usa la versión más reciente en el momento de la implementación; para otros usuarios, 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 la CLI de Azure y la extensión de la CLI de Azure DevOps, siga los vínculos Software incluido en la tabla Software.
  • Para comprobar la versión actual de la CLI de Azure, consulte Instalación de la CLI de Azure.

Si se publica una versión más reciente de la CLI de Azure y las imágenes hospedadas aún no tienen la versión más reciente, puede actualizar la versión de la CLI de Azure a la versión más reciente 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 tiene una canalización que se ejecuta en varias imágenes de máquina virtual hospedadas por Microsoft, algunas de las cuales no tienen instalada la extensión de la CLI de Azure DevOps, puede realizar ese paso condicionalmente, como se muestra en el ejemplo siguiente.

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'

CLI de Azure DevOps con agentes autohospedados

Si el agente autohospedado no está configurado con el software necesario para usar la CLI de Azure DevOps o si desea asegurarse de que tiene las versiones más recientes, puede instalar el software necesario mediante los pasos siguientes.

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

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

  • Para instalar la CLI de Azure en la imagen del agente autohospedado, consulte Instalación de la CLI de Azure. Hay instrucciones independientes para Windows, Linux y macOS.
  • Después de instalar la CLI de Azure, instale la extensión de la CLI de Azure DevOps.

Instalación de la CLI de Azure y la extensión de la CLI de Azure DevOps en la canalización

El ejemplo siguiente de configuración de la CLI de Azure y la extensión de la CLI de Azure DevOps en un agente autohospedado mediante una canalización tiene los siguientes requisitos previos.

  • Instalación de la CLI de Azure mediante 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'

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

    • La VERSIÓN 2.10.1 o posterior de la CLI de Azure está instalada.
    • 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 la CLI de Azure seguida de la extensión de la CLI de 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
# ...

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

Para almacenar los resultados de una llamada de la CLI de Azure DevOps a una variable de canalización, use la task.setvariable sintaxis descrita en Establecer variables en scripts. En el ejemplo siguiente se recupera el identificador de un grupo de variables denominado Fabrikam-2023 y, a continuación, 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'

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