CLI do Azure DevOps no Azure Pipeline YAML

  • Artigo

Serviços de DevOps do Azure

Se desejar usar a CLI do Azure DevOps com um pipeline YAML, você pode usar os exemplos a seguir para instalar a CLI do Azure, adicionar a extensão Azure DevOps e executar comandos da CLI do Azure DevOps.

Nota

As etapas neste artigo mostram como autenticar com o Azure DevOps e executar az devops comandos usando a extensão da CLI do Azure DevOps. Se você quiser usar a CLI do Azure para interagir com os recursos do Azure, use a tarefa AzureCLI.

Autenticar com o Azure DevOps

Alguns comandos da CLI do Azure DevOps que não chamam o Azure DevOps, como az devops configure e az devops -h, não exigem nenhuma autenticação, mas a maioria dos comandos interage com o Azure DevOps e requer autenticação. Você pode autenticar usando o token de segurança System.AccessToken usado pelo pipeline em execução, atribuindo-o a uma variável de ambiente chamada AZURE_DEVOPS_EXT_PAT, conforme mostrado no exemplo a seguir.

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

Se você tiver várias etapas que exigem autenticação, adicione a AZURE_DEVOPS_EXT_PAT variável de ambiente a cada etapa.

Para obter mais informações sobre o escopo do token de segurança usado pelo pipeline em execução, consulte Acessar repositórios, artefatos e outros recursos.

Para obter mais informações sobre a autenticação usando um token de acesso pessoal, consulte Entrar com um token de acesso pessoal (PAT).

CLI do Azure DevOps com agentes hospedados no Windows e Linux

Os agentes Windows e Linux hospedados pela Microsoft são pré-configurados com a CLI do Azure e a extensão da CLI do Azure DevOps.

O exemplo a seguir mostra como fazer logon no Azure DevOps e executar alguns comandos. Este exemplo usa a imagem do agente hospedado pela ubuntu-latest Microsoft, mas você pode substituí-la por qualquer uma das outras imagens hospedadas no Windows ou Linux.

Este exemplo se autentica com a CLI do Azure DevOps usando o token de segurança System.AccessToken usado pelo pipeline em execução.

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 do Azure DevOps com agentes hospedados no macOS

Os agentes hospedados pela Microsoft do macOS têm a CLI do Azure instalada, mas não a extensão da CLI do Azure DevOps. Para instalar a extensão da CLI do Azure DevOps, execute o seguinte comando em seu pipeline antes de fazer qualquer chamada à CLI do Azure DevOps.

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

Versão da CLI do Azure do agente hospedado

Os agentes hospedados pela Microsoft normalmente implantam atualizações semanais no software nos ambientes virtuais. Para algumas ferramentas, a versão mais recente no momento da implantação é usada; para outros, a ferramenta é fixada em versões específicas.

  • Para verificar o software incluído e suas versões para agentes hospedados pela Microsoft, incluindo a versão instalada da CLI do Azure e a extensão da CLI do Azure DevOps, siga os links Software incluído na tabela Software.
  • Para verificar a versão atual da CLI do Azure, consulte Como instalar a CLI do Azure.

Você pode atualizar a CLI do Azure em suas imagens hospedadas executando os seguintes comandos em seu 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'

Instalar condicionalmente a extensão da CLI do Azure DevOps

Se o pipeline for executado em várias imagens de VM hospedadas pela Microsoft, algumas das quais não têm a extensão da CLI do Azure DevOps instalada, você executa a instalação condicionalmente.

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 do Azure DevOps com agentes auto-hospedados

Você pode usar os seguintes métodos para instalar ou atualizar a CLI do Azure DevOps em seu agente auto-hospedado.

Instalar manualmente a CLI do Azure e a extensão da CLI do Azure DevOps

Instalar a CLI do Azure e a extensão da CLI do Azure DevOps em seu agente auto-hospedado quando você provisiona a imagem da máquina virtual para o agente é mais rápido do que instalá-los cada vez que o pipeline é executado.

  • Para instalar a CLI do Azure em sua imagem de agente auto-hospedada, consulte Instalar a CLI do Azure. Existem instruções separadas para Windows, Linux e macOS.
  • Depois de instalar a CLI do Azure, instale a extensão CLI do Azure DevOps.

Instalar a CLI do Azure e a extensão da CLI do Azure DevOps em seu pipeline

O exemplo a seguir de configuração da CLI do Azure e da extensão da CLI do Azure DevOps em um agente auto-hospedado usando um pipeline tem os seguintes pré-requisitos.

# 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'
  • Instalar a extensão Azure CLI DevOps
    • A CLI do Azure versão 2.10.1 ou superior está instalada.
    • Há uma versão do bash instalado no agente e no caminho. Uma instalação bash é necessária para usar a tarefa 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
# ...

O exemplo a seguir instala a CLI do Azure seguida pela extensão da CLI do 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
# ...

Atribuir os resultados de uma chamada da CLI do Azure DevOps a uma variável

Para armazenar os resultados de uma chamada da CLI do Azure DevOps para uma variável de pipeline, use a task.setvariable sintaxe descrita em Definir variáveis em scripts. O exemplo a seguir recupera a ID de um grupo de variáveis chamado Fabrikam-2023 e usa esse valor em uma etapa subsequente.

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 obter mais exemplos de trabalho com variáveis, incluindo o trabalho com variáveis entre trabalhos e estágios, consulte Definir variáveis. Para obter exemplos da sintaxe de consulta usada no exemplo anterior, consulte Como consultar a saída do comando CLI do Azure usando uma consulta JMESPath.