Compartilhar via

CLI do Azure DevOps no YAML do Azure Pipeline

  • Artigo

Azure DevOps Services

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

Observação

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 exige 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 variável de AZURE_DEVOPS_EXT_PAT 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 autenticação usando um token de acesso pessoal, consulte Entrar com um PAT (token de acesso pessoal).

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 é autenticado 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 comando a seguir no pipeline antes de fazer qualquer chamada da 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 comandos a seguir 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ê executará 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 métodos a seguir 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 sempre que o pipeline é executado.

  • Para instalar a CLI do Azure em sua imagem de agente auto-hospedada, consulte Instalar a CLI. Existem instruções separadas para Windows, Linux e macOS.
  • Depois de instalar a CLI do Azure, instale a extensão da 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 DevOps da CLI do Azure
    • A CLI do Azure versão 2.10.1 ou superior está instalada.
    • Há uma versão de bash instalada 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 como trabalhar 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 da CLI do Azure usando uma consulta JMESPath.