Getting Started with Azure DevOps CLI

Getting started with Azure DevOps CLI. If you work with Azure DevOps then you should check out the Azure DevOps CLI, if you haven’t already. Working with the CLI will save you time because it lets you work in a streamlined task/command orientated manner. In other words, we are talking fast and flexible interaction. Unlike the GUI flow.

In this article, we will cover everything that you need to get up and running with the Azure DevOps CLI.

It’s an extension of the Azure CLI that allows you to manage your Azure DevOps Services from the command line.

The Azure DevOps Command Line Interface (CLI) is available for Azure DevOps Server 2020 and Azure DevOps Services.

Before can we jump into it we’ll need to make sure that we’ve got Azure CLI version 2.10.1 installed (minimum version required), run az –version to confirm. Follow the steps in this link if you need to install or upgrade Azure CLI – install

1 – Add the Azure DevOps Extension

az extension –name azure devops

2 – Confirm the Azure DevOps Extension is installed

az extension list or az extension show –name azure-devops

If you need help figuring out which commands and args you need then -h or –help is your friend. For any command just add the -h or –help switch to show args needed. For example, if you want to find out more about the az pipelines commands just type az pipelines -h.

It’s also not a bad way to find out about new commands.

You can sign in using the Azure CLI az login command or an Azure DevOps Personal Access Token (PAT) by running the az devops login –organization http://dev.azure.com/{organization} and entering the PAT when prompted. Refer to the create personal access token guide for creating a PAT – pat.

For non-interactive / automation scenarios you can use environment variables or retrieve a PAT from a file see the following link for more detail – automation.

You will need to specify the organization and more often than not the project that you want to run the az devops commands i.e. az pipelines build list –organization https://dev.azure.com/{organization name}-project {project name}. Rather than specifying these details on every command you can, you can set a default organization and project using the az devops configure –defaults project={project name} organization={organization name}.

Azure DevOps CLI uses JSON as its default output but you can use the -o or –output parameter to format the output to jsonc, yaml, table and tsv e.g. –output table.

The other thing you’ll want to know is the JMESPath query language. Azure CLI uses the –query argument to execute a JMESPath query on the result of the commands so you can extract only the information that you’re looking for. Check the following link for more information about the JMESPath query language here – https://jmespath.org/.

Combining the –query and –output arguments allows us to get plain text results that we can assign to variables that we can use in our scripts.

For example, the az devops project list command returns an array of objects so if we only want to see if a project already exists then we can add –query value[].[name] -o tsv.

Now we’ve got some of the basics out of the way, we can get cracking with the examples!

Note – These examples assume that you’ve already got the Az DevOps extension installed and have configured a default project and organization.

Example 1 – Create a new project

There’s not a lot to this one the only argument that’s required is –name, all of the other arguments i.e. -p or –process (organization default), -s or –source-control (git) and –visibility (private) will use default values if not specified.

For this example we want our project to use the basic process template, git for source control and be private.

az devops project create –name Example1 –description “Az Devops CLI Example1” –process basic

Example 2 – Add users to your project

Let’s assume that the member that we want to add already exists within the Organization and the Project Group that we’ll be adding them to is Example1 Team.

To add users to we’ll be using the az devops security group command but first, we’ll need to grab the descriptor (id) of the Project Group and Member that we want to add.

$groupDescriptor = az devops security group list –query “graphGroups[?contains(principalName,’Example1 Team’)].[descriptor]” -o tsv

$memberDescriptor = az devops user show –user someone@test.com –query user.descriptor -o tsv

Now we’ve got these descriptors we can add the member to the group.

az devops security group membership add –group-id $groupDescriptor –member-id $memberDescriptor

Example 3 – Check that our Git Repo exists

This is pretty straightforward.

az repos list –query “[].name” -o tsv

Example 4 – Import an external Git Repo

In this example, we’ll be creating a new git repo in our project and then importing an external git repo from GitHub into it.

az repos create –name {Repo Name}

az repos import create –git-url {GitHub WebUrl} –repository {Repo Name} –requires-authorization

Example 5 – Create an Azure Resource Manager Service Connection

Next, let’s create an Azure Resource Manager Service Connection to our Azure Subscription so that we have somewhere to deploy our code.

For this example, we’ll assume that we will be using an existing Service Principal (SP) with certificate-based authentication and that the SP has all require role assignments in Azure. See the following link for more information about Service Connections – service connections.

az devops service-endpoint azurerm create –name {Service Connection Name} –azure-rm-tenant-id {Azure Tenant Id} –azure-rm-subscription-id {Azure Subscription Id} –azure-rm-subscription-name {Azure Subscription Name} –azure-rm-service-principal-id {SP Id} –azure-rm-service-principal-certificate

Example 6 – Create Variable Groups

Time to create a variable group to support deployments to multiple environments. For this example, we’ll be using the az pipelines variable-group with the create and list subcommands.

az pipelines variable-group create –name {Variable Group Name} –authorize –variables {Variable 1 Name}=”{Variable 1 Value}” {Variable 2 Name}=”{Variable 2 Value}”

To display a list of the Variable Groups within the project we can run;

az pipelines variable-group list –query “[].name” -o tsv

Example 7 – Create a new YAML Pipeline

Note – you must have a file association for .yml to be able to edit the yaml file.

In this example, we’re going to create a starter YAML Pipeline using the interactive mode of the Azure DevOps CLI by running the az pipelines create command.

az pipelines create –name {Pipeline Name} –description {“Description for pipeline”} –repository {Repository Name} –branch {Branch Name} –repository-type {Repository Type}

• If –repository-type is omitted it will be auto-detected from the remote URL of the local repository. Azure DevOps repo = ‘tfsgit’, GitHub repo = ‘github’.

Hit enter when prompted to select the default template ([1] Starter Pipeline).

At this point you can choose to either 1) Continue with creating the pipeline; or 2) View or edit the yaml, we’re going to go with option 2. Now the Azure DevOps CLI will try and open the default application associated with .yml files, in my case, it’s VS Code.

With our editor open, we can modify our pipeline to our heart’s content and when finished simply save the file and close the editor.

Next, we get prompted for the location to commit our azure-pipelines.yml file. Go ahead and select the Default choice(1): Commit directly to the master branch.

The build will automatically be triggered once it’s been committed and there you have it an executed pipeline of your very own courtesy of the Azure DevOps CLI.

The Azure DevOps CLI doesn’t cover all areas and resources ‘natively’ but luckily it does provide a ‘catch-all’ command called invoke that you can use to easily call the Azure DevOps Rest API.

Let’s take a look at how to use the invoke command to get a list of releases for a project via the Azure DevOps Services REST API. See the following link for information about the API call – release API

GET https://vsrm.dev.azure.com/{organization}/{project}/_apis/release/releases?api-version=6.0

To call a REST API with the invoke command we’ll need the following details;

• area – release
• resource – releases
• route – {organization} / {project}
• api version – ?api-version=6.0

Breaking down the release API above we get;

https://vsrm.dev.azure/route/route/_apis/area/resource/api version

Armed with this information we can now build our invoke command.

az devops invoke –area release –resource releases –route –api-version “6.0-preview” -o json

To conclude

In this article Getting Started with Azure DevOps CLI we covered all of the basics to help you get started. If you work with Azure DevOps it’s worth taking the time to start working with the Azure DevOps CLI, to script and automate your tasks.

While not all of the APIs are wrapped yet Azure DevOps CLI makes it easy to interact with the Azure DevOps REST API, besides which the Azure DevOps CLI seems to be under constant development so it’s only a matter of time before everything’s covered.

Thank you for reading.