Azure Pipeline の YAML で Azure DevOps の CLI を使用する

Azure DevOps サービス

Note

この機能は、今週と次の週にロールアウトされます。 Azure DevOps Services プロジェクトにこの機能がまだ表示されない場合は、数日後にもう一度確認してください。

Azure DevOps CLI を使用すると、コマンド ラインからAzure DevOpsリソースを管理できます。 AzureCLI@3 タスクを使用して YAML パイプラインで CLI コマンドを実行し、CI/CD ワークフローの一部として一般的な DevOps タスクを自動化します。 Microsoftホスト型Windowsおよび Linux エージェントには、Azure CLIと Azure DevOps CLI 拡張機能が既に含まれています。

認証には、ワークロード ID フェデレーションによってサポートされるAzure DevOpsサービス接続Microsoft Entra使用します。 資格情報の管理が不要になるため、この方法をお勧めします。 個人用アクセス トークン (PAT) は、サービス接続が使用できない場合にのみ使用します。

Azure DevOpsで認証する

az devops configure や az devops --help など、一部のAzure DevOps CLI コマンドでは、認証は必要ありません。 Azure DevOpsに接続しません。 ほとんどのコマンドはAzure DevOpsと対話し、認証が必要です。

次の例に示すように、実行中のパイプラインで使用される System.AccessToken セキュリティ トークンを使用して、 AZURE_DEVOPS_EXT_PATという名前の環境変数に割り当てることで認証できます。

System.AccessTokenを使用するには、PAT が必要です。 より安全な代替手段として、サービス接続を使用します。 セットアップ ガイダンスについては、「 サービス接続の管理」を参照してください。

- bash: |
    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 環境変数を追加します。

実行中のパイプラインで使用されるセキュリティ トークンのスコープの詳細については、「 Access リポジトリ、成果物、およびその他のリソースを参照してください。

個人用アクセス トークン (PAT) を使用した認証の詳細については、「個人用アクセス トークン を使用したサインイン」を参照してください。

Windows および Linux でホストされているエージェントを使用して Azure DevOps CLI にサインインする

MicrosoftでホストされるWindowsおよび Linux エージェントは、Azure CLIと Azure DevOps CLI 拡張機能で事前構成されています。

次の例は、Azure DevOpsにサインインし、いくつかのコマンドを実行する方法を示しています。 この例では、ubuntu-latest Microsoft ホストされるエージェント イメージを使用します。 他の Windows または Linux でホストされているイメージに置き換えることができます。

この例では、Azure DevOps CLI を使用して認証します。 実行中のパイプラインで使用される System.AccessToken セキュリティ トークンを使用します。

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)

Azure DevOps CLI 拡張機能を macOS ホスト エージェントでインストールする

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ホストされるエージェント仮想環境のソフトウェアに毎週更新プログラムを定期的に展開します。 一部のツールでは、デプロイ時の最新バージョンが使用されます。 その他の場合、ツールは特定のバージョンにピン留めされます。

  • インストールされているバージョンの Azure CLI および Azure DevOps CLI 拡張機能を含む、Microsoftホストされるエージェントの含まれるソフトウェアとそのバージョンを確認するには、Software 表の Included Software リンクに従います。
  • Azure CLIの現在のバージョンを確認するには、「Azure CLIを参照してください。

パイプラインで次のコマンドを実行して、ホストされているイメージのAzure CLIをアップグレードできます。

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

Azure DevOps CLI 拡張機能を条件付きでインストールする

パイプラインが複数のMicrosoftホストされた仮想マシン イメージで実行されている場合、その一部に Azure DevOps CLI 拡張機能がインストールされていない場合は、条件付きでインストールできます。

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をセルフホステッドエージェントで使用する

次の方法を使用して、セルフホステッド エージェントに Azure DevOps CLI をインストールまたはアップグレードできます。

Azure CLIを手動でインストールし、Azure DevOps CLI 拡張機能をインストールする

エージェントの仮想マシン イメージをプロビジョニングするときに、セルフホステッド エージェントに Azure CLI および Azure DevOps CLI 拡張機能をインストールする方が、パイプラインを実行するたびにインストールするよりも高速です。

セルフホステッド エージェント イメージにAzure CLIをインストールするには、 Azure CLI。 Windows、Linux、およびmacOSに関する個別の手順があります。

Azure CLIをインストールしたら、Azure DevOps CLI 拡張機能をインストールします。

パイプラインに CLI 拡張機能Azure CLIとAzure DevOpsをインストールする

パイプラインを使用してセルフホステッド エージェントで Azure CLI および Azure DevOps CLI 拡張機能を構成する次の例には、次の前提条件があります。

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

DevOps 拡張機能Azure CLIインストールします。

  • Azure CLIバージョン 2.10.1 以降がインストールされています。
  • エージェントとパスに bash のバージョンがインストールされています。 bash タスクを使用するには、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
# ...

次の例では、Azure CLIをインストールし、その後に 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
- 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
# ...

Azure DevOps CLI 呼び出しの結果を変数に割り当てる

Azure DevOps CLI 呼び出しの結果をパイプライン変数に格納するには、task.setvariableで説明されている構文を使用します。 次の例では、 Fabrikam-2023 という名前の変数グループの ID を取得し、後続の手順でこの値を使用します。

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'

サービス接続で認証する

サービス接続を使用すると、サービス接続は、パイプラインでの手動資格情報管理を必要とせずに、AzureCLI@3 タスクの Azure CLI コマンドと Azure DevOps CLI コマンドに必要な資格情報を提供します。

Note

AzureCLI@3 での認証にサービス接続を使用する場合は、Azure DevOps組織にサービス プリンシパルを手動で追加する必要があります。

PAT なしのガイダンスとサービス接続のベスト プラクティスについては、「 サービス接続の管理」を参照してください。

このコード サンプルでは、既存のサービス接続の名前を使用して、 serviceConnection新しいパラメーターを定義します。 このパラメーターは、 AzureCLI@3 タスクで参照されます。 このスクリプトでは、シークレットのない接続を使用して REST エンドポイントを呼び出し、プロジェクトとプールを一覧表示します。

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

Azure DevOps CLI 呼び出しの結果を変数に割り当てる

Azure DevOps CLI 呼び出しの結果をパイプライン変数に格納するには、task.setvariableで説明されている構文を使用します。 次の例では、 kubernetes という名前の変数グループの ID を取得し、後続の手順でこの値を使用します。

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

ジョブやステージ間での変数の操作など、変数を操作する例については、「変数の定義を参照してください。 前の例で使用したクエリ構文の例については、「JMESPath クエリを使用してコマンド出力Azure CLIクエリを実行する方法を参照してください。

関連コンテンツ

  • Last updated on