Skip to content

Commit

Permalink
Updating Azure DevOps CLI with new agents and authentication instruct…
Browse files Browse the repository at this point in the history 
…ions (#3739)

* Update Azure CLI samples

* Updating authentication for Azure DevOps CLI

* Added authenticate section

* Simpify macOS examples

* Simplified versioning and upgrading

* Tweak

* Fix link

* Intro tweak

* Update Windows-2022 image name

* Version information

* Added variable example

* Added related articles

* Tweak

* Add links and example step

* Fix link

* More links and simplification

* Apply pencil edit for blocking issue from PR review

Co-authored-by: Steve Danielson <[email protected]>
Co-authored-by: Courtney Wales <[email protected]>
  • Loading branch information
@steved0x @Court72
3 people authored Sep 22, 2021
1 parent 8a96c66 commit 5d25fc3
Showing 1 changed file with 76 additions and 56 deletions.
132 changes: 76 additions & 56 deletions docs/cli/azure-devops-cli-in-yaml.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,30 +9,43 @@ ms.manager: mijacobs
ms.author: kaelli
author: KathrynEE
monikerRange: '>= azure-devops-2020'
ms.date: 05/19/2021
ms.date: 09/22/2021
---

# Azure DevOps CLI in Azure Pipeline YAML

[!INCLUDE [temp](../includes/version-cloud-plus-2020.md)]

If you prefer to use YAML to provide your release pipeline configuration, you can use the following example to understand how YAML can be used to install Azure CLI, add the Azure DevOps extension, and run the build and PR list commands.
If you wish to use Azure DevOps CLI with a YAML pipeline, you can use the following example to understand how YAML can be used to install Azure CLI, add the Azure DevOps extension, and run Azure DevOps CLI commands.

> [!NOTE]
> The steps in this article show how to log in to Azure DevOps and run `az devops` commands using the Azure DevOps CLI extension. If you want to use Azure CLI to interact with Azure resources, use the [AzureCLI task](../pipelines/tasks/deploy/azure-cli.md).
> The steps in this article show how to authenticate with Azure DevOps and run `az devops` commands using the Azure DevOps CLI extension. If you want to use Azure CLI to interact with Azure resources, use the [AzureCLI task](../pipelines/tasks/deploy/azure-cli.md).
## Authenticate with Azure DevOps

Some Azure DevOps CLI commands that don't call into Azure DevOps, like `az devops configure` and `az devops -h`, do not require any authentication, but most commands interact with Azure DevOps and do require authentication. You can authenticate using the [System.AccessToken](../pipelines/build/variables.md#systemaccesstoken) security token used by the running pipeline, by assigning it to an environment variable named `AZURE_DEVOPS_EXT_PAT`, as shown in the following example.

```yml
- bash: |
az pipelines build list
displayName: 'Show build list'
env:
AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)
```
If you have multiple steps that require authentication, add the `AZURE_DEVOPS_EXT_PAT` environment variable to each step.

For more information on the scope of the security token used by the running pipeline, see [Access repositories, artifacts, and other resources](../pipelines/process/access-tokens.md).

For more information about authentication using a personal access token, see [Sign in with a personal access token (PAT)](log-in-via-pat.md).

## Azure DevOps CLI with Windows and Linux hosted agents

The Microsoft-hosted Windows and Linux agents are preconfigured with Azure CLI and the Azure DevOps CLI extension.

> [!IMPORTANT]
> Microsoft-hosted agents [typically deploy weekly updates](https://github.com/actions/virtual-environments#updates-to-virtual-environments) to the software on the virtual environments. For some tools, the latest version at the time of the deployment is used; for others, the tool is pinned to specific version(s).
>
> To check the included software and their versions for Microsoft-hosted agents, including the versions of Azure CLI and Azure DevOps CLI extension, follow the **Included Software** links in the [Software](../pipelines/agents/hosted.md#software) table.
The following example shows how to log in to Azure DevOps and run a few commands. This example uses the `ubuntu-latest` Microsoft-hosted agent image, but you can replace it with any of the other [Windows or Linux hosted images](../pipelines/agents/hosted.md#software).

This example logs into Azure DevOps CLI using the [System.AccessToken](../pipelines/build/variables.md#systemaccesstoken) security token used by the running pipeline.
This example authenticates with Azure DevOps CLI using the [System.AccessToken](../pipelines/build/variables.md#systemaccesstoken) security token used by the running pipeline.

```yml
trigger:
Expand All @@ -45,66 +58,36 @@ steps:
- bash: az --version
displayName: 'Show Azure CLI version'

- bash: echo ${AZURE_DEVOPS_CLI_PAT} | az devops login
env:
AZURE_DEVOPS_CLI_PAT: $(System.AccessToken)
displayName: 'Login Azure DevOps Extension'

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

```

If you are using a Windows agent, and want to replace [bash](../pipelines/tasks/utility/bash.md) with [script](../pipelines/yaml-schema.md#script), which uses bash for Linux and macOS and cmd.exe for Windows, use the following example to log in to Azure DevOps.

```yml
# %AZURE_DEVOPS_CLI_PAT% on Windows when using script
- script: echo %AZURE_DEVOPS_CLI_PAT% | az devops login
env:
AZURE_DEVOPS_CLI_PAT: $(System.AccessToken)
displayName: 'Login Azure DevOps Extension'
AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)

```

## Azure DevOps CLI with macOS hosted agents

The macOS Microsoft-hosted agents have Azure CLI installed but not the Azure DevOps CLI extension.
> [!IMPORTANT]
> Microsoft-hosted agents [typically deploy weekly updates](https://github.com/actions/virtual-environments#updates-to-virtual-environments) to the software on the virtual environments. For some tools, the latest version at the time of the deployment is used; for others, the tool is pinned to specific version(s).
>
> To check the included software and their versions for Microsoft-hosted agents, including the version of Azure CLI, follow the **Included Software** links in the [Software](../pipelines/agents/hosted.md#software) table.
* [macOS X Catalina 10.15](#macos-x-catalina-1015)
* [macOS X Catalina 10.14](#macos-x-catalina-1014)
### macOS X Catalina 10.15
The macOS X Catalina 10.15 hosted agent has Azure CLI 2.23.0 installed, but not the Azure DevOps CLI extension.
To install the Azure DevOps CLI extension, run the following command in your pipeline before calling `az devops login`.
The macOS Microsoft-hosted agents have Azure CLI installed but not the Azure DevOps CLI extension. To install the Azure DevOps CLI extension, run the following command in your pipeline before making any Azure DevOps CLI calls.

```yml
# Install Azure DevOps extension
- bash: az extension add -n azure-devops
displayName: 'Install Azure DevOps extension'
```
### macOS X Catalina 10.14
## Hosted agent Azure CLI version
The minimum Azure CLI version that supports the Azure DevOps CLI extension is [2.10.1](index.md), and the macOS X Catalina 10.14 hosted agent has Azure CLI 2.22.1 installed. To install the Azure DevOps CLI extension using that version of Azure CLI, run the following command in your pipeline before calling `az devops login`.
Microsoft-hosted agents [typically deploy weekly updates](https://github.com/actions/virtual-environments#updates-to-virtual-environments) to the software on the virtual environments. For some tools, the latest version at the time of the deployment is used; for others, the tool is pinned to specific version(s).
```yml
# Install Azure DevOps extension
- bash: az extension add -n azure-devops
displayName: 'Install Azure DevOps extension'
```
* To check the included software and their versions for Microsoft-hosted agents, including the installed version of Azure CLI and Azure DevOps CLI extension, follow the **Included Software** links in the [Software](../pipelines/agents/hosted.md#software) table.
* To check the current version for Azure CLI, see [How to install the Azure CLI](/cli/azure/install-azure-cli).
To upgrade the Azure CLI version to the latest version before installing the Azure DevOps CLI extension, run the following commands in your pipeline.
If a newer version of Azure CLI is released and the hosted images do not yet have the latest version, you can upgrade the Azure CLI version to the latest version by running the following commands in your pipeline.
```yml
# Specify python version
Expand All @@ -116,15 +99,9 @@ To upgrade the Azure CLI version to the latest version before installing the Azu
# Update to latest Azure CLI version
- bash: pip install --pre azure-cli --extra-index-url https://azurecliprod.blob.core.windows.net/edge
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
# ...
```
## Conditionally install the Azure DevOps CLI extension
If you have a pipeline that runs on several Microsoft-hosted VM images, some of which do not have the Azure DevOps CLI extension installed, you can perform that step conditionally, as shown in the following example.
Expand All @@ -133,7 +110,7 @@ If you have a pipeline that runs on several Microsoft-hosted VM images, some of
trigger:
- main

# Run on all Microsoft-hosted agent images
# Run on multiple Microsoft-hosted agent images
strategy:
matrix:
linux18:
Expand All @@ -142,8 +119,12 @@ strategy:
imageName: "ubuntu-20.04"
mac1015:
imageName: "macos-10.15"
macOS11:
imageName: "macos-11"
windows2019:
imageName: "windows-2019"
windows2022:
imageName: "windows-2022"
maxParallel: 3

pool:
Expand Down Expand Up @@ -175,7 +156,7 @@ steps:
## Azure DevOps CLI with self-hosted agents
If your self-hosted agent isn't preconfigured with the required software to use Azure DevOps CLI, or if you want to ensure you have the latest versions, you can install the required software using the following steps.
If your self-hosted agent isn't configured with the required software to use Azure DevOps CLI, or if you want to ensure you have the latest versions, you can install the required software using the following steps.
* [Manually install Azure CLI and Azure DevOps CLI extension](#manually-install-azure-cli-and-azure-devops-cli-extension)
* [Install Azure CLI and Azure DevOps CLI extension in your pipeline](#install-azure-cli-and-azure-devops-cli-extension-in-your-pipeline)
Expand Down Expand Up @@ -246,3 +227,42 @@ steps:
# Now you can make calls into Azure DevOps CLI
# ...
```

## Assign the results of an Azure DevOps CLI call to a variable

To store the results of an Azure DevOps CLI call to a pipeline variable, use the `task.setvariable` syntax described in [Set variables in scripts](../pipelines/process/variables.md#set-variables-in-scripts). The following example retrieves the ID of a variable group named **Fabrikam-2021** and then uses this value in a subsequent step.

```yml
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-2021 --query [].id -o tsv)"
env:
AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)
displayName: 'Get Fabrikam-2021 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-2021 variable group'
```

For more examples of working with variables, including working with variables across jobs and stages, see [Define variables](../pipelines/process/variables.md). For examples of the query syntax used in the previous example, see [How to query Azure CLI command output using a JMESPath query](/cli/azure/query-azure-cli).

## Related articles

* [System.AccessToken](../pipelines/build/variables.md#systemaccesstoken)
* [Access repositories, artifacts, and other resources](../pipelines/process/access-tokens.md)
* [Define variables](../pipelines/process/variables.md)
* [Azure DevOps CLI extension reference](/cli/azure/devops)
* [Azure DevOps CLI extension az pipelines reference](/cli/azure/pipelines)
* [How to query Azure CLI command output using a JMESPath query](/cli/azure/query-azure-cli)

0 comments on commit 5d25fc3

Please sign in to comment.