Compartilhar via

CLI do Azure DevOps no Azure Pipeline YAML

Azure DevOps Services

Note

Este recurso será lançado esta semana e na próxima. Se você ainda não vir o recurso em seu projeto Azure DevOps Services, verifique novamente em alguns dias.

Azure DevOps CLI permite gerenciar Azure DevOps recursos da linha de comando. Execute comandos da CLI em um pipeline YAML com a tarefa AzureCLI@3 para automatizar tarefas comuns do DevOps como parte do fluxo de trabalho de CI/CD. Os agentes Windows e Linux hospedados pela Microsoft já incluem o CLI do Azure e a extensão da CLI do Azure DevOps.

Para autenticação, use uma conexão de serviço do Azure DevOps respaldada pela federação de identidade de carga de trabalho do Microsoft Entra. Recomendamos essa abordagem porque elimina o gerenciamento de credenciais. Use um PAT (token de acesso pessoal) somente quando uma conexão de serviço não estiver disponível.

Autenticar com Azure DevOps

Alguns comandos da CLI Azure DevOps, como az devops configure e az devops --help, não exigem nenhuma autenticação. Eles não se conectam a Azure DevOps. A maioria dos comandos interagem com Azure DevOps e exigem 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.

Usar System.AccessToken depende de ter um PAT. Como alternativa mais segura, use uma conexão de serviço. Para obter diretrizes de configuração, consulte Gerenciar conexões de serviço.

- 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 ambiente AZURE_DEVOPS_EXT_PAT 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 PAT (token de acesso pessoal), consulte Entrar com um token de acesso pessoal.

Fazer login na CLI do Azure DevOps usando agentes hospedados no Windows e Linux

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

O exemplo a seguir mostra como entrar no Azure DevOps e executar alguns comandos. Este exemplo usa a imagem do agente hospedado pela Microsoft ubuntu-latest. Você pode substituí-lo por qualquer uma das outras imagens hospedadas em Windows ou Linux.

Este exemplo é autenticado com Azure DevOps CLI. Ele usa 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)

Instalar a extensão CLI do Azure DevOps com agentes hospedados no macOS

Os agentes do macOS hospedados pela Microsoft têm o CLI do Azure instalado, mas não a extensão Azure DevOps CLI. Para instalar a extensão CLI do Azure DevOps, execute o seguinte comando no 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'

Atualizar a versão do CLI do Azure do agente hospedado

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

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

Você pode atualizar o 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 Azure DevOps

Se o pipeline for executado em várias imagens de máquina virtual hospedadas por Microsoft, algumas das quais não têm a extensão da CLI Azure DevOps instalada, você poderá instalar condicionalmente.

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

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

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

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

Para instalar CLI do Azure na imagem do agente auto-hospedado, consulte Instale o CLI do Azure. Há instruções separadas para Windows, Linux e macOS.

Depois de instalar CLI do Azure, instale a extensão Azure DevOps CLI.

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

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

  • Instale CLI do Azure usando Python. Python deve ser instalado no agente de acordo com as instruções na tarefa de versão Python – Como posso configurar um agente auto-hospedado para usar essa tarefa?. A tarefa UsePythonVersion@0 não instala Python em seu agente autogerenciado. Se você tiver apenas uma versão do Python instalada em seu agente auto-hospedado e ela estiver no PATH, você não precisará usar a tarefa UsePythonVersion@0.
# 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 CLI do Azure extensão de DevOps:

  • 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 CLI do Azure seguido pela extensão da 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
# ...

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

Para armazenar os resultados de uma chamada da Azure DevOps CLI para uma variável de pipeline, use a sintaxe task.setvariable descrita em definir variáveis em scripts. O exemplo a seguir obtém 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'

Autenticar com uma conexão de serviço

Quando você usa uma conexão de serviço, a conexão de serviço fornece as credenciais necessárias para comandos da CLI CLI do Azure e Azure DevOps na tarefa AzureCLI@3 sem a necessidade de gerenciamento manual de credenciais no pipeline.

Note

Ao usar uma conexão de serviço para autenticação com AzureCLI@3, você precisa adicionar manualmente a entidade de serviço à sua organização no Azure DevOps.

Para obter diretrizes sem PAT e práticas recomendadas de conexão de serviço, consulte Gerenciar conexões de serviço.

Este exemplo de código define um novo parâmetro, serviceConnectioncom o nome de uma conexão de serviço existente. Esse parâmetro é referenciado na AzureCLI@3 tarefa. O script usa uma conexão sem necessidade de segredo para chamar um endpoint REST e, em seguida, lista projetos e 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

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

Para armazenar os resultados de uma chamada da CLI do Azure DevOps em uma variável de pipeline, use a sintaxe task.setvariable descrita em Set variables em scripts. O exemplo a seguir obtém a ID de um grupo de variáveis chamado kubernetes e usa esse valor em uma etapa subsequente.

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 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 CLI do Azure saída de comando usando uma consulta JMESPath.

Conteúdo relacionado

  • Last updated on