Azure Pipeline YAML 中的 Azure DevOps CLI

2025-08-28

Azure DevOps Services

如果要将 Azure DevOps CLI 与 YAML 管道配合使用，可以使用 Azure DevOps 扩展或使用 AzureCLI 任务。 Microsoft 托管的 Windows 和 Linux 代理预配置了 Azure CLI 和 Azure DevOps CLI 扩展。 Azure DevOps CLI 扩展运行 az devops 命令。

可以使用 PAT 进行身份验证，或者使用带有服务连接的 AzureCLI@2 任务。使用服务连接是更安全的选项，因为无需手动管理凭据。

通过 Azure DevOps 进行身份验证

某些 Azure DevOps CLI 命令，例如 az devops configure 和 az devops --help，不需要任何身份验证。它们无法连接到 Azure DevOps。大多数命令与 Azure DevOps 交互，并且确实需要身份验证。

可以使用正在运行的管道使用的 System.AccessToken 安全令牌进行身份验证，方法是将其分配给名为 AZURE_DEVOPS_EXT_PAT环境变量的环境变量，如以下示例所示。

使用 System.AccessToken 依赖于具有 PAT。作为更安全的替代方法，可以使用AzureCLI@2任务来填充服务连接。

Bash
PowerShell

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

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

如果有多个需要身份验证的步骤，请将 AZURE_DEVOPS_EXT_PAT 环境变量添加到每个步骤。

有关正在运行的管道所使用的安全令牌范围的详细信息，请参阅访问存储库、工件和其他资源。

有关使用个人访问令牌进行身份验证的详细信息（PAT），请参阅使用个人访问令牌登录。

Microsoft 托管的 Windows 和 Linux 代理预配置了 Azure CLI 和 Azure DevOps CLI 扩展。

以下示例演示如何登录到 Azure DevOps 并运行几个命令。此示例使用 ubuntu-latest Microsoft托管的代理映像。可以将它替换为任何其他 Windows 或 Linux 托管映像。

此示例使用 Azure DevOps CLI 进行身份验证。它使用正在运行的管道使用的 System.AccessToken 安全令牌。

Bash
PowerShell

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)

trigger:
- main

pool:
  vmImage: 'windows-latest'

steps:
- bash: az --version
  displayName: 'Show Azure CLI version'

- pwsh: az devops configure --defaults organization='$(System.TeamFoundationCollectionUri)' project='$(System.TeamProject)' --use-git-aliases true
  displayName: 'Set default Azure DevOps organization and project'

- pwsh: |
    az pipelines build list
    git pr list
  displayName: 'Show build list and PRs'
  env:
    AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)

使用 macOS 托管代理安装 Azure DevOps CLI 扩展

macOS Microsoft 托管代理已安装 Azure CLI，但未安装 Azure DevOps CLI 扩展。若要安装 Azure DevOps CLI 扩展，请在管道中运行以下命令，然后再调用任何 Azure DevOps CLI。

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

升级托管代理 Azure CLI 版本

Microsoft托管代理通常会将每周更新部署到虚拟环境中的软件。对于某些工具，使用部署时最新版本。在其他情况下，该工具被限定在特定版本。

若要检查 Microsoft 托管代理所包含的软件及其版本（包括已安装的 Azure CLI 和 Azure DevOps CLI 扩展版本），请在软件表中点击包含的软件链接进行操作。
若要检查 Azure CLI 的当前版本，请参阅如何安装 Azure CLI。

可以通过在管道中运行以下命令来升级托管映像上的 Azure CLI。

Bash
PowerShell

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

# Specify python version
- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.x'
    architecture: 'x64'

# Update to latest Azure CLI version
- pwsh: pip install --pre azure-cli
  displayName: 'Upgrade Azure CLI'

有条件地安装 Azure DevOps CLI 扩展

如果管道在多个Microsoft托管的虚拟机映像上运行，其中一些虚拟机映像未安装 Azure DevOps CLI 扩展，则可以有条件地安装。

Bash
PowerShell

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"
    mac13:
      imageName: "macos-13"
    windows2025:
      imageName: "windows-2025"
    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'

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"
    mac13:
      imageName: "macos-13"
    windows2025:
      imageName: "windows-2025"
    windows2022:
      imageName: "windows-2022"
  maxParallel: 3

pool:
  vmImage: $(imageName)

steps:
- pwsh: az --version
  displayName: 'Show Azure CLI version'

# Install Azure DevOps CLI extension only on macOS images
- pwsh: 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
- pwsh: 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
- pwsh: |
    az pipelines build list
    git pr list
  env:
    AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)
  displayName: 'Show build list and PRs'

使用自托管代理的 Azure DevOps CLI

可以使用以下方法在自托管代理中安装或升级 Azure DevOps CLI。

手动安装 Azure CLI 和 Azure DevOps CLI 扩展
在管道中安装 Azure CLI 和 Azure DevOps CLI 扩展

手动安装 Azure CLI 和 Azure DevOps CLI 扩展

在为自托管代理预配虚拟机映像时就预先安装好 Azure CLI 及其 DevOps CLI 扩展，会比在每次管道运行时再动态安装要快得多。

若要在自承载代理映像上安装 Azure CLI，请参阅安装 Azure CLI。 Windows、Linux 和 macOS 有单独的说明。

安装 Azure CLI 后，安装 Azure DevOps CLI 扩展。

在管道中安装 Azure CLI 和 Azure DevOps CLI 扩展

以下示例（使用管道在自托管代理上配置 Azure CLI 和 Azure DevOps CLI 扩展）具有以下先决条件。

使用 Python 安装 Azure CLI。必须根据 Python 版本任务中的说明在代理上安装 Python - 如何将自承载代理配置为使用此任务？该 UsePythonVersion@0 任务不会将 Python 安装到自承载代理上。如果自托管代理上只安装了一个版本的 Python，并且它位于路径中，则无需使用 UsePythonVersion@0 任务。

Bash
PowerShell

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

# Specify python version if you have side-by-side versions
- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.x'
    architecture: 'x64'

# Update pip to latest
- pwsh: 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
- pwsh: pip install --pre azure-cli
  displayName: 'Upgrade Azure CLI'

安装 Azure CLI DevOps 扩展：

已安装 Azure CLI 2.10.1 或更高版本。
代理和路径中都安装了一个版本的 bash。要使用 bash 任务，则需要安装 bash。

Bash
PowerShell

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

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

# Now you can make calls into Azure DevOps CLI
# ...

以下示例安装 Azure CLI，后接 Azure DevOps CLI 扩展。

Bash
PowerShell

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

steps:
# Specify python version if you have side-by-side versions
- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.x'
    architecture: 'x64'

# Update pip to latest
- pwsh: 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
- pwsh: pip install --pre azure-cli
  displayName: 'Upgrade Azure CLI'

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

# Now you can make calls into Azure DevOps CLI
# ...

将 Azure DevOps CLI 调用的结果分配给变量

若要存储对管道变量的 Azure DevOps CLI 调用的结果，请使用task.setvariable脚本中“设置变量”中所述的语法。以下示例获取名为 Fabrikam-2023 的变量组的 ID，并在后续步骤中使用此值。

Bash
PowerShell

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'

variables:
- name: variableGroupId

trigger: none

pool:
  vmImage: "windows-latest"

steps:
- pwsh: az devops configure --defaults organization='$(System.TeamFoundationCollectionUri)' project='$(System.TeamProject)' --use-git-aliases true
  displayName: 'Set default Azure DevOps organization and project'

- pwsh: 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'

- pwsh: az pipelines variable-group variable list --group-id '$(variableGroupId)'
  env:
    AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)
  displayName: 'List variables in Fabrikam-2023 variable group'

使用服务连接进行身份验证

使用服务连接时，服务连接在AzureCLI@2任务中为 Azure CLI 和 Azure DevOps CLI 命令提供所需的凭据，而无需在管道中手动管理凭据。

Note

使用服务连接进行身份验证 AzureCLI@2时，需要手动将服务主体添加到 Azure DevOps 组织。

此代码示例使用现有服务连接的名称定义一个新参数 serviceConnection。在AzureCLI@2任务中引用了该参数。任务列出所有项目（az devops project list）和池（az pipelines pool list）。

trigger:
  - main

parameters:
- name: serviceConnection
  displayName: Azure Service Connection Name
  type: string
  default: my-service-connection

steps:
  - task: AzureCLI@2
    condition: succeededOrFailed()
    displayName: 'Azure CLI -> DevOps CLI'
    inputs:
      azureSubscription: '${{ parameters.serviceConnection }}'
      scriptType: pscore
      scriptLocation: inlineScript
      inlineScript: |
        Write-Host "Using logged-in Azure CLI session..."
        Write-Host "$($PSStyle.Formatting.FormatAccent)az devops configure$($PSStyle.Reset)"
        az devops configure --defaults organization=$(System.CollectionUri) project=$(System.TeamProject)
        az devops configure -l

        Write-Host "`nUse Azure DevOps CLI (az devops) to list projects in the organization '$(System.CollectionUri)'..."
        Write-Host "$($PSStyle.Formatting.FormatAccent)az devops project list$($PSStyle.Reset)"
        az devops project list --query "value[].{Name:name, Id:id}" `
                               -o table

        Write-Host "`nUse Azure DevOps CLI (az pipelines) to list pools in the organization '$(System.CollectionUri)'..."
        Write-Host "$($PSStyle.Formatting.FormatAccent)az pipelines pool list$($PSStyle.Reset)"
        az pipelines pool list --query "[].{Id:id, Name:name}" `
                               -o table
      failOnStandardError: true

将 Azure DevOps CLI 调用的结果分配给变量

若要存储对管道变量的 Azure DevOps CLI 调用的结果，请使用task.setvariable脚本中“设置变量”中所述的语法。以下示例获取名为 kubernetes 的变量组的 ID，并在后续步骤中使用此值。

trigger:
  - main

variables:
- name: variableGroupId

parameters:
- name: serviceConnection
  displayName: Azure Service Connection Name
  type: string
  default: my-service-connection

steps:
  - task: AzureCLI@2
    condition: succeededOrFailed()
    displayName: 'Azure CLI -> DevOps CLI'
    inputs:
      azureSubscription: '${{ parameters.serviceConnection }}'
      scriptType: pscore
      scriptLocation: inlineScript
      inlineScript: |
        Write-Host "Using logged-in Azure CLI session..."
        Write-Host "$($PSStyle.Formatting.FormatAccent)az devops configure$($PSStyle.Reset)"
        az devops configure --defaults organization=$(System.CollectionUri) project=$(System.TeamProject)
        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@2
    condition: succeededOrFailed()
    displayName: 'Azure CLI -> DevOps CLI'
    inputs:
      azureSubscription: '${{ parameters.serviceConnection }}'
      scriptType: pscore
      scriptLocation: inlineScript
      inlineScript: |
        Write-Host "Using logged-in Azure CLI session..."
        az pipelines variable-group variable list --group-id '$(variableGroupId)'

有关使用变量（包括跨作业和阶段处理变量）的更多示例，请参阅 “定义变量”。有关上一示例中使用的查询语法示例，请参阅如何使用 JMESPath 查询查询 Azure CLI 命令输出。

反馈

此页面是否有帮助？

通过

Azure Pipeline YAML 中的 Azure DevOps CLI

通过 Azure DevOps 进行身份验证

使用 Windows 和 Linux 托管代理登录到 Azure DevOps CLI

使用 macOS 托管代理安装 Azure DevOps CLI 扩展

升级托管代理 Azure CLI 版本

有条件地安装 Azure DevOps CLI 扩展

使用自托管代理的 Azure DevOps CLI

手动安装 Azure CLI 和 Azure DevOps CLI 扩展

在管道中安装 Azure CLI 和 Azure DevOps CLI 扩展

将 Azure DevOps CLI 调用的结果分配给变量

使用服务连接进行身份验证

将 Azure DevOps CLI 调用的结果分配给变量

相关内容

反馈

其他资源