Contents

Developer resources
Azure DevOps CLI
Get started
How-to Guides
Sign in with a Personal Access Token
Output formats
Query
Auto detect configuration and git aliases
Configure policies
Run commands in a release pipeline
Run commands in a YAML build pipeline
Manage security permissions
Manage service connections
Troubleshooting
Troubleshooting common errors
Reference
Command reference
Security tokens
Azure DevOps REST APIs
Azure DevOps Demo Generator
Demo Generator
Get started
Build custom template
 Get started with Azure DevOps CLI
5/5/2020 • 2 minutes to read • Edit Online

Azure DevOps Ser vices

The Azure DevOps extension for Azure Command Line Interface (CLI) allows you to experience Azure DevOps
Services from the command line, bringing the capability to manage Azure DevOps right to your fingertips! This
allows you to work in a streamlined task/command oriented manner without having to worry about the GUI flows,
providing you a faster and flexible interaction canvas.

NOTE
The Azure DevOps Command Line Interface (CLI) is only available for Azure DevOps Services at this time.

To start using the Azure DevOps extension for Azure CLI, execute the following steps:
1. Install Azure CLI: Follow the instructions available here to set up Azure CLI in your environment. At a
minimum, your Azure CLI version must be 2.0.69. You can use az --version to validate.
2. Add the Azure DevOps extension:

az extension add --name azure-devops

You can use az extension list or az extension show --name azure-devops to confirm the installation.
3. Sign in: Run az login to sign in. Note that we support only interactive or log in using user name and
password with az login . We do not support use of service principals with az login . You would need to use
a PAT token in this case. For more information, see Log in via Azure DevOps Personal Access Token (PAT).
4. Configure defaults: Although you can provide the organization and project for each command, we
recommend you set these values as defaults in configuration for seamless commanding.

az devops configure --defaults organization=https://dev.azure.com/contoso project=ContosoWebApp

Command usage
Adding the Azure DevOps Extension adds devops , pipelines , artifacts , boards , and repos groups. For usage
and help content for any command, pass in the -h parameter, for example:
 $ az devops -h

Group
az devops : Manage Azure DevOps organization level operations.
Related Groups
az pipelines: Manage Azure Pipelines
az boards: Manage Azure Boards
az repos: Manage Azure Repos
az artifacts: Manage Azure Artifacts.

Subgroups:
admin : Manage administration operations.
extension : Manage extensions.
project : Manage team projects.
security : Manage security related operations.
service-endpoint : Manage service endpoints/service connections.
team : Manage teams.
user : Manage users.
wiki : Manage wikis.

Commands:
configure : Configure the Azure DevOps CLI or view your configuration.
feedback : Displays information on how to provide feedback to the Azure DevOps CLI team.
invoke : This command will invoke request for any DevOps area and resource. Please use
only json output as the response of this command is not fixed. Helpful docs -
https://docs.microsoft.com/rest/api/azure/devops/.
login : Set the credential (PAT) to use for a particular organization.
logout : Clear the credential for all or a particular organization.

Open items in browser

You can use --open switch to open any artifact in Azure DevOps portal in your default browser.
For example :

az pipelines build show --id 1 --open

This command will show the details of build with id 1 on the command-line and also open it in the default
browser.

Related articles
Log in via Azure DevOps Personal Access Token (PAT)
Output formats
Command Reference
Azure DevOps CLI Extension GitHub Repo
 Sign in with a Personal Access Token (PAT)
4/24/2020 • 2 minutes to read • Edit Online

Azure DevOps Ser vices

You can sign in using an Azure DevOps Personal Access Token. See the create personal access token guide to create
one.
You will be prompted to enter PAT after you run the az devops login command.

$az devops login --organization https://dev.azure.com/contoso

Token:

NOTE
If you have already signed in with az login interactively or using user name and password, then you don't have to provide
a token as az devops commands now support sign in through az login . However, service principal log in via az login
isn't supported, in which case a PAT token is required.

Once successfully signed in, this command would also set your default organization to Contoso, provided there is
no default organization configured.
To gain access in a non-interactive manner for automation scenarios, you can use environment variables or fetch a
PAT from a file.

Use environment variables

There are cases where persisting a personal access token on the machine is not feasible or secure. In these cases,
you can get a token from an environment variable.
To use a personal access token, set the AZURE_DEVOPS_EXT_PAT environment variable at the process level:
Windows
macOS and Linux

# set environment variable for current process

$env:AZURE_DEVOPS_EXT_PAT = 'xxxxxxxxxx'

Replace xxxxxxxxxx with your PAT.

Now run any command without having to sign in explicitly. Each command will try to use the PAT in the
environment variable for authentication.

Fetch PAT from a file

cat my_pat_token.txt | az devops login --organization https://dev.azure.com/contoso/
 Auto detect configuration and git aliases
2/26/2020 • 2 minutes to read • Edit Online

Azure DevOps Ser vices

The Azure DevOps CLI has been optimized to allow developers to use Azure Repos and work well with their git
workflows.

Auto detect configuration

The Azure DevOps Extension evaluates if your current working directory is an Azure Repos git repository to auto
detect configuration setting - organization, project, and repository. Auto detection is controlled by the --detect
flag, which is true by default.
With this capability, you can run az repos pr list in your local git checkout to view all PRs in the repository.

Git alias
You can also configure the Azure DevOps Extension to add git aliases for common git-based Azure Repos
commands like creating or adding reviewers to pull requests. Run the following command to enable git aliases.

az devops configure --use-git-aliases true

All az repos commands will now be aliased to git repo and all az repos pr commands to git pr .
For example, a pull request can now be created using the following command:

git pr create --target-branch {branch\_name}

Parameter hierarchy
There are three main ways by which parameters can be provided to a command. They have been listed in order of
priority:
1. Command parameters
For example: az repos list --organization https://dev.azure.com/contoso --project webApplication
2. Auto detection from git context if --detect is true . Detect is true by default.
3. Default configuration For example:
az devops configure --defaults organization=https://dev.azure.com/contoso project=webApplication

Say a customer runs the following commands

~/$ az devops configure --defaults organization=https://dev.azure.com/contoso project=webApp

~/$ az repos list --organization=https://dev.azure.com/contosoTest --project=testApplication

The organization and project parameter provided via command will be used since command parameters take top
priority.
Let's have a look at another example. Say a user has pre-configured the default organization to contoso and
project to webApp . However, the user is working out of a local checkout of a git repo, which is in the contosoTest
organization and testApplication project. Further, --detect is true by default.

~/contosoTest/portal$ az devops configure --defaults organization=https://dev.azure.com/contoso project=webApp

~/contosoTest/portal$ az repos list

In this case, contosoTest and testApplication will be auto detected as the target organization and project from git
context and will override the defaults that have been set.
 Configure policies
2/26/2020 • 2 minutes to read • Edit Online

Azure DevOps Ser vices

You can easily configure branch policies for your repository using the various policy commands. However, the
policy commands accept a single scope, i.e., single combination of repository, branch and match type. If you want to
apply the same policy across various scopes, you can do that using a policy configuration file.
Say you want to create a manual queue build policy across all branch folders that start with "release" and also on
the master branch. To achieve this, execute the following steps:

Create a policy configuration file

Create a policy configuration file for build policy, including the multiple application scopes.

{
"isBlocking": true,
"isDeleted": false,
"isEnabled": true,
"revision": 1,
"settings": {
"buildDefinitionId": 22,
"displayName": "Manual Queue Policy",
"manualQueueOnly": true,
"queueOnSourceUpdateOnly": false,
"scope": [
{
"matchKind": "Prefix",
"refName": "refs/heads/release",
"repositoryId": "e646f204-53c9-4153-9ab9-fd41a11e3564"
},
{
"matchKind": "Exact",
"refName": "refs/heads/master",
"repositoryId": "e646f204-53c9-4153-9ab9-fd41a11e1234"
}
],
"validDuration": 0
},
"type": {
"displayName": "Build",
"id": "0609b952-1397-4640-95ec-e00a01b2f659"
}
}

To learn more about the structure for various policy types, refer to Policy create.

Save the file and run the create policy command

az repos policy create C:\policyConfiguration.txt

Note that the path is provided using '\' backslash.

 Azure DevOps CLI in a release pipeline
2/26/2020 • 2 minutes to read • Edit Online

Azure DevOps Ser vices

To use the Azure DevOps CLI in a hosted agent using a Release Pipeline, execute the following steps:
1. Create a release pipeline.

2. Choose Empty job .

3. Choose Stage 1 to configure the stage.

4. Choose the Tasks page, and configure the job to use Hosted Mac OS in Agent Pools.

5. Choose the plus icon to add another task and configure it as a PowerShell task. Enter Power into the
search box to filter the list.
6. Add the script, either via file or inline. For the example, the script has been included inline.

For reference, here is the inline script:

$extensions = az extension list -o json | ConvertFrom-Json

$devopsFound = $False
foreach($extension in $extensions)
{
if($extension.name -eq 'azure-devops'){
$devopsFound = $True
}
}

if ($devopsFound -eq $False){

az extension add -n azure-devops
}
 Azure DevOps CLI in Azure Pipeline YAML
3/26/2020 • 2 minutes to read • Edit Online

Azure DevOps Ser vices

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 and add the Azure DevOps extension.
In the example, you will learn how to add the Azure DevOps extension to Azure CLI and run the build and PR list
commands on Linux, macOS and Windows hosted agents.

Create the azure-pipelines-steps.yml file

Include the content below.
For macOS: azure -pipelines-steps-mac.yml

steps:
- script: az extension add -n azure-devops
displayName: 'Install Azure DevOps Extension'

- script: echo ${AZURE_DEVOPS_CLI_PAT} | az devops login

env:
AZURE_DEVOPS_CLI_PAT: $(System.AccessToken)
displayName: 'Login Azure DevOps Extension'

- script: az devops configure --defaults organization=$(System.TeamFoundationCollectionUri)

project=$(System.TeamProject) --use-git-aliases true
displayName: 'Set default Azure DevOps organization and project'

- script: |
az pipelines build list
git pr list
displayName: 'Show build list and PRs'

For Linux: azure -pipelines-steps-linux.yml

 steps:
# Updating the python version available on the linux agent
- task: UsePythonVersion@0
inputs:
versionSpec: '3.x'
architecture: 'x64'

# Updating pip to latest

- script: python -m pip install --upgrade pip
displayName: 'Upgrade pip'

# Updating to latest Azure CLI version.

- script: pip install --pre azure-cli --extra-index-url https://azurecliprod.blob.core.windows.net/edge
displayName: 'upgrade azure cli'

- script: az --version
displayName: 'Show Azure CLI version'

- script: az extension add -n azure-devops

displayName: 'Install Azure DevOps Extension'

- script: echo ${AZURE_DEVOPS_CLI_PAT} | az devops login

env:
AZURE_DEVOPS_CLI_PAT: $(System.AccessToken)
displayName: 'Login Azure DevOps Extension'

- script: az devops configure --defaults organization=https://georgeverghese.visualstudio.com project="Movie

Search Web App" --use-git-aliases true
displayName: 'Set default Azure DevOps organization and project'

- script: |
az pipelines build list
git pr list
displayName: 'Show build list and PRs'

For Windows: azure-pipelines-steps-win.yml

 steps:
# Updating the python version available on the linux agent
- task: UsePythonVersion@0
inputs:
versionSpec: '3.x'
architecture: 'x64'

# Updating pip to latest which is required by the Azure DevOps extension

- script: python -m pip install --upgrade pip
displayName: 'Upgrade pip'

# Upgrading Azure CLI from 2.0.46 to latest; min version required for Azure DevOps is 2.0.49
- script: pip install --pre azure-cli --extra-index-url https://azurecliprod.blob.core.windows.net/edge
displayName: 'upgrade azure cli'

- script: az --version
displayName: 'Show Azure CLI version'

- script: az extension add -n azure-devops

displayName: 'Install Azure DevOps Extension'

- script: echo $(System.AccessToken) | az devops login

env:
AZURE_DEVOPS_CLI_PAT: $(System.AccessToken)
displayName: 'Login Azure DevOps Extension'

- script: az devops configure --defaults organization=https://georgeverghese.visualstudio.com project="Movie

Search Web App" --use-git-aliases true
displayName: 'Set default Azure DevOps organization and project'

- script: |
az pipelines build list
git pr list
displayName: 'Show build list and PRs'

Create the azure-pipelines.yml

Include the content below.

jobs:
# Running Azure DevOps extension commands on a hosted Mac agent
- job:
displayName: 'macOS'
pool:
vmImage: 'macOS-latest'
steps:
- template: azure-pipelines-steps-mac.yml

# Running Azure DevOps extension commands on a hosted Linux agent

- job:
displayName: 'Linux'
pool:
vmImage: 'ubuntu-16.04'
steps:
- template: azure-pipelines-steps-linux.yml

# Running Azure DevOps extension commands on a hosted Windows agent

- job:
displayName: 'Windows'
pool:
vmImage: 'vs2017-win2016'
steps:
- template: azure-pipelines-steps-win.yml
 Manage security permissions
2/26/2020 • 2 minutes to read • Edit Online

Azure DevOps Ser vices

Security permissions for a User or Security group can be managed by running following group of commands:
az devops security permission -h

For more information on concepts related to Security permissions, kindly refer REST API documentation

Find a namespace
Typically, each family of resources (work items, Git repositories, etc.) is secured using a different namespace. Each
security namespace contains zero or more access control lists. Each access control list contains a token, an inherit
flag and a set of zero or more access control entries. Each access control entry contains an identity descriptor, an
allowed permissions bitmask and an denied permissions bitmask.
List all namespaces
To list all available namespace in an organization, run following command.
az devops security permission namespace list

Get namespace details

To get the details of a namespace, and check what are the permission types secured with that namespace, use show
command. az devops security permission namespace show --namespace-id <NAMESPACE_ID>

Understand security tokens

Tokens are arbitrary strings representing resources in Azure DevOps. Token format differs per resource type,
however hierarchy and separator characters are common between all tokens.
List tokens for a namespace
Once you have figured the required namespace, you can list all the tokens available in namespace for a specific
user or security group.
az devops security permission list --namespace-id <NAMESPACE_ID> --subject <USER_ID/GROUP_DESCRIPTOR>

You can also use token parameter in above command if you know the token already and want to list only root
and/or child tokens of a resource. This way you will be able to filter results when some namespace has long list of
ACLs for given user/group.
az devops security permission list --namespace-id <NAMESPACE_ID> --subject <USER_ID/GROUP_DESCRIPTOR> --token
<SECURITY_TOKEN> --recurse

To get the required token for different namespaces, refer Security tokens for Permissions management
For given token, and group/user, if you need to list permissions or resolve the allow/deny bits to its corresponding
permission types,use following command.
az devops security permission show --namespace-id <NAMESPACE_ID> --subject <USER_ID/GROUP_DESCRIPTOR> --token
<SECURITY_TOKEN>

Change permissions
Here, permissions could be a single permission type or combination of multiple permission types. You will get the
permission details available for any namespace with az devops security permission namespace show --id command.
You will have to pass this permission bits while assigning allow/deny permissions and removing permissions.
Assign permissions
az devops security permission update --namespace-id <NAMESPACE_ID> --subject <USER_ID/GROUP_DESCRIPTOR> --token
<SECURITY_TOKEN> --allow-bit 4 --deny-bit 1

Here, --allow-bit/--deny-bit could be a single permission bit or addition of multiple permission bits.
Reset permissions
az devops security permission reset --namespace-id <NAMESPACE_ID> --subject <USER_ID/GROUP_DESCRIPTOR> --token
<SECURITY_TOKEN> --permission-bit 5

Here, --permission-bit could be a single permission bit or addition of multiple permission bits.
Reset all permissions
You can clear all explicit permissions for given token , given user or group with following command.
az devops security permission reset-all --namespace-id <NAMESPACE_ID> --subject <USER_ID/GROUP_DESCRIPTOR> --
token <SECURITY_TOKEN>
 Azure DevOps CLI Service Endpoint
2/26/2020 • 2 minutes to read • Edit Online

Azure DevOps Ser vices

Creating GitHub Service Endpoint

Use command:

az devops service-endpoint github create

In interactive mode this command will ask for GitHub PAT token using a prompt message, for automation purpose
set the GitHub PAT token in AZURE_DEVOPS_EXT_GITHUB_PAT environment variable.

Creating Azure RM Service Endpoint

Use command:

az devops service-endpoint azurerm create

Using client secret/password

In interactive mode this command will ask for service principal password/secret using a prompt message, for
automation purpose set service principal password/secret in AZURE_DEVOPS_EXT_AZURE_RM_SERVICE_PRINCIPAL_KEY
environment variable.

export AZURE_DEVOPS_EXT_AZURE_RM_SERVICE_PRINCIPAL_KEY=<your_secret_here>

Using client certificate

If AAD application uses certificate for authentification then create .pem for the certificate and pass path to .pem file
in --azure-rm-service-principal-certificate-path argument.
.pem file can be created using openssl

openssl pkcs12 -in file.pfx -out file.pem -nodes -password pass:<password_here>

Create service endpoint using configuration file

DevOps CLI extension supports creation of any type of service endpoint using

az devops service-endpoint create

Prerequisite for using this command is that user should be aware of the request format for creating that particular
kind of service endpoint.
It can be achived using the following steps: Create endpoint of same type from UI and capture its network trace
(using tool of your preference like Fiddler, Chrome Developer tool)
Captured request will be a POST call to uri ending apis/serviceendpoint/endpoints

and body will look like

{
"id": "980cf1c0-ba7c-4731-bd7f-1df785b89ab3",
"description": "",
"administratorsGroup": null,
"authorization": {
"parameters": {
"username": "Docker_ID_Sample",
"password": "Docker_ID_Sample",
"email": "Docker_ID_Email",
"registry": "https://index.docker.io/v1/"
},
"scheme": "UsernamePassword"
},
"createdBy": null,
"data": {
"registrytype": "Others"
},
"name": "Docker_Registry_Sample",
"type": "dockerregistry",
"url": "https://index.docker.io/v1/",
"readersGroup": null,
"groupScopeId": null,
"serviceEndpointProjectReferences": null,
"operationStatus": null
}

This request body should be saved in a file and that file can act as a template for creation of service endpoints of
type "Docker Registry Service Connection"
Path to this file (after updating appropriate values like Name, ID or password) can be passed to
--service-endpoint-configuration parameter. Note that the path is provided using '\' backslash.
 Troubleshoot common errors in Azure DevOps CLI
2/26/2020 • 2 minutes to read • Edit Online

Azure DevOps Ser vices

Boards - Iterations and Area commands

C O M M A N D GRO UP ERRO R SC EN A RIO F IX/ W O RK A RO UN D

Team level iterations
VS1530019: Cannot find Cannot find iteration: When You can only add child
iteration with id you try to add a backlog iterations of backlog iteration
'b1e33737-e943-xxxx-xxxx-
e3f1cbaxxxx'. The iteration to a team. to your team. Create child
iteration might have been iterations of your backlog
deleted, or it might not iteration using command
be selected for your
team. az boards iteration
project create --name
"child_iteration_name" --
path
<BacklogIterationPath>
. Get the identifier of this
iteration and add it to your
team using
az boards iteration team
add -h
command.

Team level Areas
DefaultValue If you are trying to add your
first area to a team without
passing the flag --set-as-
default.
Pass --set-as-default when
adding an area to a team or
use
az boards area team update
command to change the
default area for the team. Refer
help for
az boards area team add -h

Team level Areas
TF400499: You have not Adding/removing/updating Be cautious while working with
set your team field. area to team team areas, --path parameter
for team area must be
\ProjectName\RootAreaName\ChildArea1
and not
\ProjectName\Area\RootAreaName\ChildArea1
. Team area commands don't
expect 'Area' keyword to be
passed in the --path parameter.
 Security tokens for permissions management
2/26/2020 • 2 minutes to read • Edit Online

Azure DevOps Ser vices

Tokens are arbitrary strings representing resources in Azure DevOps. Token format differs per resource type,
however hierarchy and separator characters are common between all tokens.

Hierarchy
A security namespace can be either hierarchical or flat. Tokens in a hierarchical namespace exist in a hierarchy with
effective permissions being inherited from parent tokens to child tokens. Tokens in a flat namespace have no
concept of a parent-child relationship between any two tokens.

Separator character
Tokens in a hierarchical namespace either have a fixed length for each path part, or variable length. If the tokens
have variable-length path parts, then a separator character is used to distinguish where one path part ends and
another begins.

Token examples for different namespaces

Namespace name: Project
Namespace ID:52d39943-cb85-4d7f-8fa8-c6baac873819
Basically tokens in this namespace are of the following format. Root token : '$PROJECT'
Token to secure permissions for each project in your organization
'$PROJECT:vstfs:///Classification/TeamProject/PROJECT_ID'
So, let's assume you have a project named 'Test Project 1'. You can get the project ID for this project by referring
project show command az devops project show --project "Test Project 1"
Above command would return a project-id (say xxxxxxxx-a1de-4bc8-b751-188eea17c3ba)
Thus, the token to secure project related permissions for 'Test Project 1' would be
'$PROJECT:vstfs:///Classification/TeamProject/xxxxxxxx-a1de-4bc8-b751-188eea17c3ba'
Namespace name : Tagging
Namespace ID : bb50f182-8e5e-40b8-bc21-e8752a1e7ae2
Token format for project level permissions : '/PROJECT_ID'
Example : '/xxxxxxxx-a1de-4bc8-b751-188eea17c3ba'
Namespace name : AnalyticsViews
Namespace ID : d34d3680-dfe5-4cc6-a949-7d9c68f73cba
Token format for project level permissions : '$/Shared/PROJECT_ID'
Example : '$/Shared/xxxxxxxx-a1de-4bc8-b751-188eea17c3ba'
Namespace name : Analytics
Namespace ID : 58450c49-b02d-465a-ab12-59ae512d6531
Token format for project level permissions : '$/PROJECT_ID'
Example : '$/xxxxxxxx-a1de-4bc8-b751-188eea17c3ba'
Namespace name: Iteration
Namespace ID : bf7bfa03-b2b7-47db-8113-fa2e002cc5b1
Token format: 'vstfs:///Classification/Node/Iteration_Identifier/'
Suppose, you have following iterations configured for your team.
ProjectIteration1
1. TeamIteration1
TeamIteration1ChildIteration1
TeamIteration1ChildIteration2
TeamIteration1ChildIteration3
2. TeamIteration2
TeamIteration2ChildIteration1
TeamIteration2ChildIteration2
If you need to update permissions for ProjectIteration1\TeamIteration1\TeamIteration1ChildIteration1, security
token would look like this:
'vstfs:///Classification/Node/ProjectIteration1_Identifier:vstfs:///Classification/Node/TeamIteration1_Identifier:vstfs:
///Classification/Node/TeamIteration1ChildIteration1_Identifier'
Namespace name : BuildAdministration
Namespace ID : 302acaca-b667-436d-a946-87133492041c
Token format: 'BuildPrivileges'
Namespace name : Build
Namespace ID : 33344d9c-fc72-4d6f-aba5-fa317101a7e9
Token format for project level build permissions : 'PROJECT_ID'
If you need to update permissions for a particular build definition ID [Let's say 12], security token for that build
definition would look like this
Token format for project level build permissions : 'PROJECT_ID/12'
Example : 'xxxxxxxx-a1de-4bc8-b751-188eea17c3ba/12'
Namespace name : Identity
Namespace ID : 5a27515b-ccd7-42c9-84f1-54c998f03866
Token format for project level permissions : 'PROJECT_ID'
Example : 'xxxxxxxx-a1de-4bc8-b751-188eea17c3ba'
To modify group level permissions for Group Origin ID [2b087996-2e64-4cc1-a1dc-1ccd5e7eb95b]
Token : 'xxxxxxxx-a1de-4bc8-b751-188eea17c3ba\2b087996-2e64-4cc1-a1dc-1ccd5e7eb95b'
Namespace name : ReleaseManagement
Namespace ID : c788c23e-1b46-4162-8f5e-d7585343b5de
Token format for project level permissions : 'PROJECT_ID'
Example : 'xxxxxxxx-a1de-4bc8-b751-188eea17c3ba'
If you need to update permissions for a particular release definition ID [Let's say 12], security token for that release
definition would look like this
Token format for project level build permissions : 'PROJECT_ID/12'
Example : 'xxxxxxxx-a1de-4bc8-b751-188eea17c3ba/12'
Namespace name : Git Repositories
Namespace ID : 2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87
Token format for project level permissions : 'repoV2/PROJECT_ID'
You need to append RepositoryID to update repo level permissions
Token format for repository level permissions : 'repoV2/PROJECT_ID/REPO_ID'
For more information on this namespace and its tokens refer this blog
 About the Azure DevOps Services Demo Generator
2/26/2020 • 2 minutes to read • Edit Online

The Azure DevOps Services Demo Generator is a service which helps you provision projects in your organization
with pre-populated sample content that includes source code, work items, iterations, service connections, and build
and release pipelines based on a template you choose.

The purpose of this system is to simplify working with the hands-on-labs, demos and other education material
provided by the Microsoft Visual Studio Marketing team. You can use it to experiment with different services and
options in a personal, pre-configured sandbox, or to simply develop comfort with UI and workflows without
impacting a production environment.
Get started using the Demo Generator V2 now, or follow the simple walkthrough.
 Get started creating and populating demo Azure
DevOps Services projects
2/26/2020 • 4 minutes to read • Edit Online

1. Browse to the Azure DevOps Demo Generator site by selecting the link, or copy
https://azuredevopsdemogenerator.azurewebsites.net/ into your browser's URL field.

2. Click Sign In and provide the Microsoft or Azure AD account credentials associated with an organization in
Azure DevOps Services. If you don't have an organization, click on Get Star ted for Free to create one and
then log in with your credentials.

NOTE
If you are a member of multiple tenants and the desired tenant isn't the selected one, close your browser windows
and then open a new browser and navigate to https://aka.ms/vssignout . Close this browser, open a new browser
and navigate to https://aex.dev.azure.com/me , and sign-in using the desired tenant.

3. After you sign in, select Accept to grant the Demo Generator permissions to access your Azure DevOps
organization.
4. Select the organization you will use to host the project created by the Azure DevOps Demo Generator. (You
may have multiple accounts of which you are a member, and which are associated with your login, so
choose carefully.) Provide a name for your project (such as "MyProjectDemo" ) that you and other
contributors can use to identify it as a demo project. Lastly, select the demo project template you want to
provision by clicking ... (Browse) button.
 The default template is Smar tHotel360 , which contains complete ASP.NET 2 web mobile and desktop
business apps for a hotel, and can be deployed using Docker containers.
There are several other templates available, including MyHealthClinic , which defines a team project for an
ASP.NET Core app that deploys to Azure App Service; Par tsUnlimited , which defines an ASP.NET app with
customized CI/CD pipelines; and MyShuttle , which defines a Java app and Azure App service deployment. If
you are following a lab from Azure DevOps Labs, select the DevOps Labs tab to choose the template

NOTE
All templates provide fictional Azure DevOps users and pre-populated Agile planning and tracking work items and
data, along with source code in an Azure Repos Git repo, as well as access to Azure Pipelines.

5. Some templates may require additional extensions to be installed to your organization. The demo
generation process checks to see if these extensions are already installed. If the extension is already
installed, a green check will be displayed in front of the extension name. If the extension is not installed,
select the empty check boxes to install the extension(s) to your account. When ready, click on Create
Project button.

NOTE
If you want to manually install the extensions, click on the provided link for a specific extension, which takes you to
the extension's page on Azure DevOps Marketplace. From there, you can install the extension.

6. Your project may take a couple of minutes for the Demo Generator to provision. When it completes, you will
be provided with a link to the demo project.
7. Select the link to go to the new demo Azure DevOps Services project and confirm it was successfully
provisioned.

NOTE
You must provide your own information such as URLs, logins, password, and others for the configuration of demo endpoints
that use Azure resources.

Next: Learn how you can build your own template

Common Issues and workarounds:

Issue: Error while creating release definition:
Tasks with versions ARM Outputs:4.* are not valid for deploy job Agent job in stage Stage 1
Cause: This is usually caused by one of the third-party extensions not enabled or installed in your Azure DevOps
org. Usually installation of extensions are quick but sometimes, it can take a few minutes (or even hours!) for an
extension to be available to use, after it is installed in the marketplace.
Workaround: You can try waiting for a few minutes and confirm whether the extension is available to use, and
then run the generator again.

Issue: Error while creating query: TF401256: You do not have Write permissions for query Shared Queries:
Cause: In Azure DevOps, users have different access levels - Basic, Stakeholder and Visual Studio Subscriber.
Access levels determine what features are available to users. In order to provision projects using the demo
generator, you need at least a Basic access level. This error indicates the user has a stakeholder license which does
not grant permissions to writing shared queries
Fix: You should change the access level, from basic to stakeholder. Please refer to this article on docs: Add users to
your organization or project for more information on how to add users to your organization, and specify the level
of features they can use

Issue: TF50309: The following account does not have sufficient permissions to complete the operation:
The following permissions are needed to perform this operation: Create new projects
Cause: You do not have permissions to create new projects in the Azure DevOps organization you have selected.
You will need to be a part of the Project Administrators group or have explicit permissions to create new projects
Fix: Please make sure you have the required permissions or try selecting a different Azure DevOps org where you
project creation permission.
 Building your own template
2/26/2020 • 2 minutes to read • Edit Online

Azure DevOps Generator provides a number of templates, out of the box, that supports a wide variety of scenarios,
from different project types to different programming languages, deployment platforms, etc., In addition to this, the
generator also allows users to make their own templates. Users can convert their existing projects into templates
and then provision new projects using that template. The ability to have custom templates can be useful in many
scenarios, such as building custom training materials, provision only certain artifacts, etc.,
This document walks you through the steps on how you can use the extractor.

Before you start

Setup an Azure DevOps project and make sure it is ready to be extracted. The extractor will capture the contents of
the project and save them as JSON files which will be archived into a zip file.

Building a new custom template

1. Access the generator with the query parameter "enableextractor=true" added to the URL:
https://azuredevopsdemogenerator.azurewebsites.net/?enableextractor=true

2. After you sign in, on the main page, you will see a new link labeled "Build your template"

3. Selecting that will open the extractor main page in a new tab.
4. Select the organization and then the project that you want to turn into a template.
5. Click Analyze . This will validate if the project is one of the supported types (only Agile, Scrum and Basic
process based projects are supported for the time being) and that all of the contents can be read. At the end
of the analysis, you will see the artifacts and count of items for you to confirm if the extractor has read all
items correctly.

6. If it is correct and you wish to proceed, select the Generate Ar tifacts button. This will again read all the
items from the project but this time, the contents will be saved as JSON data. After all the items have been
extracted, the folder will be archived into a zip file.
7. Select the link to download the zip file. Note that the zip file is not stored on the server side - so, make sure
you download the file. It will not be available after you close the page.
Note: The Extractor supports only limited artifacts and work item types and so it should not be considered as a
migration tool for moving projects from one server to another. For what's supported and what's not supported, see
the limitations section

Provisioning your project from your custom template

1. Return back to the generator page or re-open it again if you have already closed it. You should use the
enableextractor=true query parameter in the URL.
2. Select Choose Template
3. You will see a new tab labeled Private . Select the tab.

4. Under the private tab, you have the option to import template from your local drive, GitHub or any https
URL.
 If the URL needs authentication, please provide Access Token or Username & Password

5. Clicking Submit will validate your template and credentials.

6. If the validation is effective, it will accept your template. In the Selected Template field, your template
name will be presented.
Now you are ready to create project using your own template

Previous: Using the Generator