Azure DevOps CLI
This Skill helps manage Azure DevOps resources using the Azure CLI with Azure DevOps extension.
CLI Version: 2.81.0 (current as of 2025)
Prerequisites
Install Azure CLI and Azure DevOps extension:
# Install Azure CLI brew install azure-cli # macOS curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash # Linux pip install azure-cli # via pip # Verify installation az --version # Install Azure DevOps extension az extension add --name azure-devops az extension show --name azure-devops
CLI Structure
az devops # Main DevOps commands
βββ admin # Administration (banner)
βββ extension # Extension management
βββ project # Team projects
βββ security # Security operations
β βββ group # Security groups
β βββ permission # Security permissions
βββ service-endpoint # Service connections
βββ team # Teams
βββ user # Users
βββ wiki # Wikis
βββ configure # Set defaults
βββ invoke # Invoke REST API
βββ login # Authenticate
βββ logout # Clear credentials
az pipelines # Azure Pipelines
βββ agent # Agents
βββ build # Builds
βββ folder # Pipeline folders
βββ pool # Agent pools
βββ queue # Agent queues
βββ release # Releases
βββ runs # Pipeline runs
βββ variable # Pipeline variables
βββ variable-group # Variable groups
az boards # Azure Boards
βββ area # Area paths
βββ iteration # Iterations
βββ work-item # Work items
az repos # Azure Repos
βββ import # Git imports
βββ policy # Branch policies
βββ pr # Pull requests
βββ ref # Git references
az artifacts # Azure Artifacts
βββ universal # Universal Packages
βββ download # Download packages
βββ publish # Publish packages
Authentication
Login to Azure DevOps
# Interactive login (prompts for PAT) az devops login --organization https://dev.azure.com/{org} # Login with PAT token az devops login --organization https://dev.azure.com/{org} --token YOUR_PAT_TOKEN # Logout az devops logout --organization https://dev.azure.com/{org}
Configure Defaults
# Set default organization and project az devops configure --defaults organization=https://dev.azure.com/{org} project={project} # List current configuration az devops configure --list # Enable Git aliases az devops configure --use-git-aliases true
Extension Management
List Extensions
# List available extensions az extension list-available --output table # List installed extensions az extension list --output table
Manage Azure DevOps Extension
# Install Azure DevOps extension az extension add --name azure-devops # Update Azure DevOps extension az extension update --name azure-devops # Remove extension az extension remove --name azure-devops # Install from local path az extension add --source ~/extensions/azure-devops.whl
Projects
List Projects
az devops project list --organization https://dev.azure.com/{org} az devops project list --top 10 --output table
Create Project
az devops project create \ --name myNewProject \ --organization https://dev.azure.com/{org} \ --description "My new DevOps project" \ --source-control git \ --visibility private
Show Project Details
az devops project show --project {project-name} --org https://dev.azure.com/{org}
Delete Project
az devops project delete --id {project-id} --org https://dev.azure.com/{org} --yes
Repositories
List Repositories
az repos list --org https://dev.azure.com/{org} --project {project} az repos list --output table
Show Repository Details
az repos show --repository {repo-name} --project {project}
Create Repository
az repos create --name {repo-name} --project {project}
Delete Repository
az repos delete --id {repo-id} --project {project} --yes
Update Repository
az repos update --id {repo-id} --name {new-name} --project {project}
Repository Import
Import Git Repository
# Import from public Git repository az repos import create \ --git-source-url https://github.com/user/repo \ --repository {repo-name} # Import with authentication az repos import create \ --git-source-url https://github.com/user/private-repo \ --repository {repo-name} \ --user {username} \ --password {password-or-pat}
Pull Requests
Create Pull Request
# Basic PR creation az repos pr create \ --repository {repo} \ --source-branch {source-branch} \ --target-branch {target-branch} \ --title "PR Title" \ --description "PR description" \ --open # PR with work items az repos pr create \ --repository {repo} \ --source-branch {source-branch} \ --work-items 63 64 # Draft PR with reviewers az repos pr create \ --repository {repo} \ --source-branch feature/new-feature \ --target-branch main \ --title "Feature: New functionality" \ --draft true \ --reviewers [email protected] [email protected] \ --required-reviewers [email protected] \ --labels "enhancement" "backlog"
List Pull Requests
# All PRs az repos pr list --repository {repo} # Filter by status az repos pr list --repository {repo} --status active # Filter by creator az repos pr list --repository {repo} --creator {email} # Output as table az repos pr list --repository {repo} --output table
Show PR Details
az repos pr show --id {pr-id} az repos pr show --id {pr-id} --open # Open in browser
Update PR (Complete/Abandon/Draft)
# Complete PR az repos pr update --id {pr-id} --status completed # Abandon PR az repos pr update --id {pr-id} --status abandoned # Set to draft az repos pr update --id {pr-id} --draft true # Publish draft PR az repos pr update --id {pr-id} --draft false # Auto-complete when policies pass az repos pr update --id {pr-id} --auto-complete true # Set title and description az repos pr update --id {pr-id} --title "New title" --description "New description"
Checkout PR Locally
# Checkout PR branch az repos pr checkout --id {pr-id} # Checkout with specific remote az repos pr checkout --id {pr-id} --remote-name upstream
Vote on PR
az repos pr set-vote --id {pr-id} --vote approve az repos pr set-vote --id {pr-id} --vote approve-with-suggestions az repos pr set-vote --id {pr-id} --vote reject az repos pr set-vote --id {pr-id} --vote wait-for-author az repos pr set-vote --id {pr-id} --vote reset
PR Reviewers
# Add reviewers az repos pr reviewer add --id {pr-id} --reviewers [email protected] [email protected] # List reviewers az repos pr reviewer list --id {pr-id} # Remove reviewers az repos pr reviewer remove --id {pr-id} --reviewers [email protected]
PR Work Items
# Add work items to PR az repos pr work-item add --id {pr-id} --work-items {id1} {id2} # List PR work items az repos pr work-item list --id {pr-id} # Remove work items from PR az repos pr work-item remove --id {pr-id} --work-items {id1}
PR Policies
# List policies for a PR az repos pr policy list --id {pr-id} # Queue policy evaluation for a PR az repos pr policy queue --id {pr-id} --evaluation-id {evaluation-id}
Pipelines
List Pipelines
az pipelines list --output table az pipelines list --query "[?name=='myPipeline']" az pipelines list --folder-path 'folder/subfolder'
Create Pipeline
# From local repository context (auto-detects settings) az pipelines create --name 'ContosoBuild' --description 'Pipeline for contoso project' # With specific branch and YAML path az pipelines create \ --name {pipeline-name} \ --repository {repo} \ --branch main \ --yaml-path azure-pipelines.yml \ --description "My CI/CD pipeline" # For GitHub repository az pipelines create \ --name 'GitHubPipeline' \ --repository https://github.com/Org/Repo \ --branch main \ --repository-type github # Skip first run az pipelines create --name 'MyPipeline' --skip-run true
Show Pipeline
az pipelines show --id {pipeline-id} az pipelines show --name {pipeline-name}
Update Pipeline
az pipelines update --id {pipeline-id} --name "New name" --description "Updated description"
Delete Pipeline
az pipelines delete --id {pipeline-id} --yes
Run Pipeline
# Run by name az pipelines run --name {pipeline-name} --branch main # Run by ID az pipelines run --id {pipeline-id} --branch refs/heads/main # With parameters az pipelines run --name {pipeline-name} --parameters version=1.0.0 environment=prod # With variables az pipelines run --name {pipeline-name} --variables buildId=123 configuration=release # Open results in browser az pipelines run --name {pipeline-name} --open
Pipeline Runs
List Runs
az pipelines runs list --pipeline {pipeline-id} az pipelines runs list --name {pipeline-name} --top 10 az pipelines runs list --branch main --status completed
Show Run Details
az pipelines runs show --run-id {run-id} az pipelines runs show --run-id {run-id} --open
Pipeline Artifacts
# List artifacts for a run az pipelines runs artifact list --run-id {run-id} # Download artifact az pipelines runs artifact download \ --artifact-name '{artifact-name}' \ --path {local-path} \ --run-id {run-id} # Upload artifact az pipelines runs artifact upload \ --artifact-name '{artifact-name}' \ --path {local-path} \ --run-id {run-id}
Pipeline Run Tags
# Add tag to run az pipelines runs tag add --run-id {run-id} --tags production v1.0 # List run tags az pipelines runs tag list --run-id {run-id} --output table
Builds
List Builds
az pipelines build list az pipelines build list --definition {build-definition-id} az pipelines build list --status completed --result succeeded
Queue Build
az pipelines build queue --definition {build-definition-id} --branch main az pipelines build queue --definition {build-definition-id} --parameters version=1.0.0
Show Build Details
az pipelines build show --id {build-id}
Cancel Build
az pipelines build cancel --id {build-id}
Build Tags
# Add tag to build az pipelines build tag add --build-id {build-id} --tags prod release # Delete tag from build az pipelines build tag delete --build-id {build-id} --tag prod
Build Definitions
List Build Definitions
az pipelines build definition list az pipelines build definition list --name {definition-name}
Show Build Definition
az pipelines build definition show --id {definition-id}
Releases
List Releases
az pipelines release list az pipelines release list --definition {release-definition-id}
Create Release
az pipelines release create --definition {release-definition-id} az pipelines release create --definition {release-definition-id} --description "Release v1.0"
Show Release
az pipelines release show --id {release-id}
Release Definitions
List Release Definitions
az pipelines release definition list
Show Release Definition
az pipelines release definition show --id {definition-id}
Pipeline Variables
List Variables
az pipelines variable list --pipeline-id {pipeline-id}
Create Variable
# Non-secret variable az pipelines variable create \ --name {var-name} \ --value {var-value} \ --pipeline-id {pipeline-id} # Secret variable az pipelines variable create \ --name {var-name} \ --secret true \ --pipeline-id {pipeline-id} # Secret with prompt az pipelines variable create \ --name {var-name} \ --secret true \ --prompt true \ --pipeline-id {pipeline-id}
Update Variable
az pipelines variable update \ --name {var-name} \ --value {new-value} \ --pipeline-id {pipeline-id} # Update secret variable az pipelines variable update \ --name {var-name} \ --secret true \ --value "{new-secret-value}" \ --pipeline-id {pipeline-id}
Delete Variable
az pipelines variable delete --name {var-name} --pipeline-id {pipeline-id} --yes
Variable Groups
List Variable Groups
az pipelines variable-group list az pipelines variable-group list --output table
Show Variable Group
az pipelines variable-group show --id {group-id}
Create Variable Group
az pipelines variable-group create \ --name {group-name} \ --variables key1=value1 key2=value2 \ --authorize true
Update Variable Group
az pipelines variable-group update \ --id {group-id} \ --name {new-name} \ --description "Updated description"
Delete Variable Group
az pipelines variable-group delete --id {group-id} --yes
Variable Group Variables
List Variables
az pipelines variable-group variable list --group-id {group-id}
Create Variable
# Non-secret variable az pipelines variable-group variable create \ --group-id {group-id} \ --name {var-name} \ --value {var-value} # Secret variable (will prompt for value if not provided) az pipelines variable-group variable create \ --group-id {group-id} \ --name {var-name} \ --secret true # Secret with environment variable export AZURE_DEVOPS_EXT_PIPELINE_VAR_MySecret=secretvalue az pipelines variable-group variable create \ --group-id {group-id} \ --name MySecret \ --secret true
Update Variable
az pipelines variable-group variable update \ --group-id {group-id} \ --name {var-name} \ --value {new-value} \ --secret false
Delete Variable
az pipelines variable-group variable delete \ --group-id {group-id} \ --name {var-name}
Pipeline Folders
List Folders
az pipelines folder list
Create Folder
az pipelines folder create --path 'folder/subfolder' --description "My folder"
Delete Folder
az pipelines folder delete --path 'folder/subfolder'
Update Folder
az pipelines folder update --path 'old-folder' --new-path 'new-folder'
Agent Pools
List Agent Pools
az pipelines pool list az pipelines pool list --pool-type automation az pipelines pool list --pool-type deployment
Show Agent Pool
az pipelines pool show --pool-id {pool-id}
Agent Queues
List Agent Queues
az pipelines queue list az pipelines queue list --pool-name {pool-name}
Show Agent Queue
az pipelines queue show --id {queue-id}
Work Items (Boards)
Query Work Items
# WIQL query az boards query \ --wiql "SELECT [System.Id], [System.Title], [System.State] FROM WorkItems WHERE [System.AssignedTo] = @Me AND [System.State] = 'Active'" # Query with output format az boards query --wiql "SELECT * FROM WorkItems" --output table
Show Work Item
az boards work-item show --id {work-item-id} az boards work-item show --id {work-item-id} --open
Create Work Item
# Basic work item az boards work-item create \ --title "Fix login bug" \ --type Bug \ --assigned-to [email protected] \ --description "Users cannot login with SSO" # With area and iteration az boards work-item create \ --title "New feature" \ --type "User Story" \ --area "Project\\Area1" \ --iteration "Project\\Sprint 1" # With custom fields az boards work-item create \ --title "Task" \ --type Task \ --fields "Priority=1" "Severity=2" # With discussion comment az boards work-item create \ --title "Issue" \ --type Bug \ --discussion "Initial investigation completed" # Open in browser after creation az boards work-item create --title "Bug" --type Bug --open
Update Work Item
# Update state, title, and assignee az boards work-item update \ --id {work-item-id} \ --state "Active" \ --title "Updated title" \ --assigned-to [email protected] # Move to different area az boards work-item update \ --id {work-item-id} \ --area "{ProjectName}\\{Team}\\{Area}" # Change iteration az boards work-item update \ --id {work-item-id} \ --iteration "{ProjectName}\\Sprint 5" # Add comment/discussion az boards work-item update \ --id {work-item-id} \ --discussion "Work in progress" # Update with custom fields az boards work-item update \ --id {work-item-id} \ --fields "Priority=1" "StoryPoints=5"
Delete Work Item
# Soft delete (can be restored) az boards work-item delete --id {work-item-id} --yes # Permanent delete az boards work-item delete --id {work-item-id} --destroy --yes
Work Item Relations
# List relations az boards work-item relation list --id {work-item-id} # List supported relation types az boards work-item relation list-type # Add relation az boards work-item relation add --id {work-item-id} --relation-type parent --target-id {parent-id} # Remove relation az boards work-item relation remove --id {work-item-id} --relation-id {relation-id}
Area Paths
List Areas for Project
az boards area project list --project {project} az boards area project show --path "Project\\Area1" --project {project}
Create Area
az boards area project create --path "Project\\NewArea" --project {project}
Update Area
az boards area project update \ --path "Project\\OldArea" \ --new-path "Project\\UpdatedArea" \ --project {project}
Delete Area
az boards area project delete --path "Project\\AreaToDelete" --project {project} --yes
Area Team Management
# List areas for team az boards area team list --team {team-name} --project {project} # Add area to team az boards area team add \ --team {team-name} \ --path "Project\\NewArea" \ --project {project} # Remove area from team az boards area team remove \ --team {team-name} \ --path "Project\\AreaToRemove" \ --project {project} # Update team area az boards area team update \ --team {team-name} \ --path "Project\\Area" \ --project {project} \ --include-sub-areas true
Iterations
List Iterations for Project
az boards iteration project list --project {project} az boards iteration project show --path "Project\\Sprint 1" --project {project}
Create Iteration
az boards iteration project create --path "Project\\Sprint 1" --project {project}
Update Iteration
az boards iteration project update \ --path "Project\\OldSprint" \ --new-path "Project\\NewSprint" \ --project {project}
Delete Iteration
az boards iteration project delete --path "Project\\OldSprint" --project {project} --yes
List Iterations for Team
az boards iteration team list --team {team-name} --project {project}
Add Iteration to Team
az boards iteration team add \ --team {team-name} \ --path "Project\\Sprint 1" \ --project {project}
Remove Iteration from Team
az boards iteration team remove \ --team {team-name} \ --path "Project\\Sprint 1" \ --project {project}
List Work Items in Iteration
az boards iteration team list-work-items \ --team {team-name} \ --path "Project\\Sprint 1" \ --project {project}
Set Default Iteration for Team
az boards iteration team set-default-iteration \ --team {team-name} \ --path "Project\\Sprint 1" \ --project {project}
Show Default Iteration
az boards iteration team show-default-iteration \ --team {team-name} \ --project {project}
Set Backlog Iteration for Team
az boards iteration team set-backlog-iteration \ --team {team-name} \ --path "Project\\Sprint 1" \ --project {project}
Show Backlog Iteration
az boards iteration team show-backlog-iteration \ --team {team-name} \ --project {project}
Show Current Iteration
az boards iteration team show --team {team-name} --project {project} --timeframe current
Git References
List References (Branches)
az repos ref list --repository {repo} az repos ref list --repository {repo} --query "[?name=='refs/heads/main']"
Create Reference (Branch)
az repos ref create --name refs/heads/new-branch --object-type commit --object {commit-sha}
Delete Reference (Branch)
az repos ref delete --name refs/heads/old-branch --repository {repo} --project {project}
Lock Branch
az repos ref lock --name refs/heads/main --repository {repo} --project {project}
Unlock Branch
az repos ref unlock --name refs/heads/main --repository {repo} --project {project}
Repository Policies
List All Policies
az repos policy list --repository {repo-id} --branch main
Create Policy Using Configuration File
az repos policy create --config policy.json
Update/Delete Policy
# Update az repos policy update --id {policy-id} --config updated-policy.json # Delete az repos policy delete --id {policy-id} --yes
Policy Types
Approver Count Policy
az repos policy approver-count create \ --blocking true \ --enabled true \ --branch main \ --repository-id {repo-id} \ --minimum-approver-count 2 \ --creator-vote-counts true
Build Policy
az repos policy build create \ --blocking true \ --enabled true \ --branch main \ --repository-id {repo-id} \ --build-definition-id {definition-id} \ --queue-on-source-update-only true \ --valid-duration 720
Work Item Linking Policy
az repos policy work-item-linking create \ --blocking true \ --branch main \ --enabled true \ --repository-id {repo-id}
Required Reviewer Policy
az repos policy required-reviewer create \ --blocking true \ --enabled true \ --branch main \ --repository-id {repo-id} \ --required-reviewers [email protected]
Merge Strategy Policy
az repos policy merge-strategy create \ --blocking true \ --enabled true \ --branch main \ --repository-id {repo-id} \ --allow-squash true \ --allow-rebase true \ --allow-no-fast-forward true
Case Enforcement Policy
az repos policy case-enforcement create \ --blocking true \ --enabled true \ --branch main \ --repository-id {repo-id}
Comment Required Policy
az repos policy comment-required create \ --blocking true \ --enabled true \ --branch main \ --repository-id {repo-id}
File Size Policy
az repos policy file-size create \ --blocking true \ --enabled true \ --branch main \ --repository-id {repo-id} \ --maximum-file-size 10485760 # 10MB in bytes
Service Endpoints
List Service Endpoints
az devops service-endpoint list --project {project} az devops service-endpoint list --project {project} --output table
Show Service Endpoint
az devops service-endpoint show --id {endpoint-id} --project {project}
Create Service Endpoint
# Using configuration file az devops service-endpoint create --service-endpoint-configuration endpoint.json --project {project}
Delete Service Endpoint
az devops service-endpoint delete --id {endpoint-id} --project {project} --yes
Teams
List Teams
az devops team list --project {project}
Show Team
az devops team show --team {team-name} --project {project}
Create Team
az devops team create \ --name {team-name} \ --description "Team description" \ --project {project}
Update Team
az devops team update \ --team {team-name} \ --project {project} \ --name "{new-team-name}" \ --description "Updated description"
Delete Team
az devops team delete --team {team-name} --project {project} --yes
Show Team Members
az devops team list-member --team {team-name} --project {project}
Users
List Users
az devops user list --org https://dev.azure.com/{org} az devops user list --top 10 --output table
Show User
az devops user show --user {user-id-or-email} --org https://dev.azure.com/{org}
Add User
az devops user add \ --email [email protected] \ --license-type express \ --org https://dev.azure.com/{org}
Update User
az devops user update \ --user {user-id-or-email} \ --license-type advanced \ --org https://dev.azure.com/{org}
Remove User
az devops user remove --user {user-id-or-email} --org https://dev.azure.com/{org} --yes
Security Groups
List Groups
# List all groups in project az devops security group list --project {project} # List all groups in organization az devops security group list --scope organization # List with filtering az devops security group list --project {project} --subject-types vstsgroup
Show Group Details
az devops security group show --group-id {group-id}
Create Group
az devops security group create \ --name {group-name} \ --description "Group description" \ --project {project}
Update Group
az devops security group update \ --group-id {group-id} \ --name "{new-group-name}" \ --description "Updated description"
Delete Group
az devops security group delete --group-id {group-id} --yes
Group Memberships
# List memberships az devops security group membership list --id {group-id} # Add member az devops security group membership add \ --group-id {group-id} \ --member-id {member-id} # Remove member az devops security group membership remove \ --group-id {group-id} \ --member-id {member-id} --yes
Security Permissions
List Namespaces
az devops security permission namespace list
Show Namespace Details
# Show permissions available in a namespace az devops security permission namespace show --namespace "GitRepositories"
List Permissions
# List permissions for user/group and namespace az devops security permission list \ --id {user-or-group-id} \ --namespace "GitRepositories" \ --project {project} # List for specific token (repository) az devops security permission list \ --id {user-or-group-id} \ --namespace "GitRepositories" \ --project {project} \ --token "repoV2/{project}/{repository-id}"
Show Permissions
az devops security permission show \ --id {user-or-group-id} \ --namespace "GitRepositories" \ --project {project} \ --token "repoV2/{project}/{repository-id}"
Update Permissions
# Grant permission az devops security permission update \ --id {user-or-group-id} \ --namespace "GitRepositories" \ --project {project} \ --token "repoV2/{project}/{repository-id}" \ --permission-mask "Pull,Contribute" # Deny permission az devops security permission update \ --id {user-or-group-id} \ --namespace "GitRepositories" \ --project {project} \ --token "repoV2/{project}/{repository-id}" \ --permission-mask 0
Reset Permissions
# Reset specific permission bits az devops security permission reset \ --id {user-or-group-id} \ --namespace "GitRepositories" \ --project {project} \ --token "repoV2/{project}/{repository-id}" \ --permission-mask "Pull,Contribute" # Reset all permissions az devops security permission reset-all \ --id {user-or-group-id} \ --namespace "GitRepositories" \ --project {project} \ --token "repoV2/{project}/{repository-id}" --yes
Wikis
List Wikis
# List all wikis in project az devops wiki list --project {project} # List all wikis in organization az devops wiki list
Show Wiki
az devops wiki show --wiki {wiki-name} --project {project} az devops wiki show --wiki {wiki-name} --project {project} --open
Create Wiki
# Create project wiki az devops wiki create \ --name {wiki-name} \ --project {project} \ --type projectWiki # Create code wiki from repository az devops wiki create \ --name {wiki-name} \ --project {project} \ --type codeWiki \ --repository {repo-name} \ --mapped-path /wiki
Delete Wiki
az devops wiki delete --wiki {wiki-id} --project {project} --yes
Wiki Pages
# List pages az devops wiki page list --wiki {wiki-name} --project {project} # Show page az devops wiki page show \ --wiki {wiki-name} \ --path "/page-name" \ --project {project} # Create page az devops wiki page create \ --wiki {wiki-name} \ --path "/new-page" \ --content "# New Page\n\nPage content here..." \ --project {project} # Update page az devops wiki page update \ --wiki {wiki-name} \ --path "/existing-page" \ --content "# Updated Page\n\nNew content..." \ --project {project} # Delete page az devops wiki page delete \ --wiki {wiki-name} \ --path "/old-page" \ --project {project} --yes
Administration
Banner Management
# List banners az devops admin banner list # Show banner details az devops admin banner show --id {banner-id} # Add new banner az devops admin banner add \ --message "System maintenance scheduled" \ --level info # info, warning, error # Update banner az devops admin banner update \ --id {banner-id} \ --message "Updated message" \ --level warning \ --expiration-date "2025-12-31T23:59:59Z" # Remove banner az devops admin banner remove --id {banner-id}
DevOps Extensions
Manage extensions installed in an Azure DevOps organization (different from CLI extensions).
# List installed extensions az devops extension list --org https://dev.azure.com/{org} # Search marketplace extensions az devops extension search --search-query "docker" # Show extension details az devops extension show --ext-id {extension-id} --org https://dev.azure.com/{org} # Install extension az devops extension install \ --ext-id {extension-id} \ --org https://dev.azure.com/{org} \ --publisher {publisher-id} # Enable extension az devops extension enable \ --ext-id {extension-id} \ --org https://dev.azure.com/{org} # Disable extension az devops extension disable \ --ext-id {extension-id} \ --org https://dev.azure.com/{org} # Uninstall extension az devops extension uninstall \ --ext-id {extension-id} \ --org https://dev.azure.com/{org} --yes
Universal Packages
Publish Package
az artifacts universal publish \ --feed {feed-name} \ --name {package-name} \ --version {version} \ --path {package-path} \ --project {project}
Download Package
az artifacts universal download \ --feed {feed-name} \ --name {package-name} \ --version {version} \ --path {download-path} \ --project {project}
Agents
List Agents in Pool
az pipelines agent list --pool-id {pool-id}
Show Agent Details
az pipelines agent show --agent-id {agent-id} --pool-id {pool-id}
Git Aliases
After enabling git aliases:
# Enable Git aliases az devops configure --use-git-aliases true # Use Git commands for DevOps operations git pr create --target-branch main git pr list git pr checkout 123
Output Formats
All commands support multiple output formats:
# Table format (human-readable) az pipelines list --output table # JSON format (default, machine-readable) az pipelines list --output json # JSONC (colored JSON) az pipelines list --output jsonc # YAML format az pipelines list --output yaml # YAMLC (colored YAML) az pipelines list --output yamlc # TSV format (tab-separated values) az pipelines list --output tsv # None (no output) az pipelines list --output none
JMESPath Queries
Filter and transform output:
# Filter by name az pipelines list --query "[?name=='myPipeline']" # Get specific fields az pipelines list --query "[].{Name:name, ID:id}" # Chain queries az pipelines list --query "[?name.contains('CI')].{Name:name, ID:id}" --output table # Get first result az pipelines list --query "[0]" # Get top N az pipelines list --query "[0:5]"
Global Arguments
Available on all commands:
--help/-h: Show help--output/-o: Output format (json, jsonc, none, table, tsv, yaml, yamlc)--query: JMESPath query string--verbose: Increase logging verbosity--debug: Show all debug logs--only-show-errors: Only show errors, suppress warnings--subscription: Name or ID of subscription
Common Parameters
| Parameter | Description |
|---|---|
--org / --organization | Azure DevOps organization URL (e.g., https://dev.azure.com/{org}) |
--project / -p | Project name or ID |
--detect | Auto-detect organization from git config |
--yes / -y | Skip confirmation prompts |
--open | Open in web browser |
Common Workflows
Create PR from current branch
CURRENT_BRANCH=$(git branch --show-current) az repos pr create \ --source-branch $CURRENT_BRANCH \ --target-branch main \ --title "Feature: $(git log -1 --pretty=%B)" \ --open
Create work item on pipeline failure
az boards work-item create \ --title "Build $BUILD_BUILDNUMBER failed" \ --type bug \ --org $SYSTEM_TEAMFOUNDATIONCOLLECTIONURI \ --project $SYSTEM_TEAMPROJECT
Download latest pipeline artifact
RUN_ID=$(az pipelines runs list --pipeline {pipeline-id} --top 1 --query "[0].id" -o tsv) az pipelines runs artifact download \ --artifact-name 'webapp' \ --path ./output \ --run-id $RUN_ID
Approve and complete PR
# Vote approve az repos pr set-vote --id {pr-id} --vote approve # Complete PR az repos pr update --id {pr-id} --status completed
Create pipeline from local repo
# From local git repository (auto-detects repo, branch, etc.) az pipelines create --name 'CI-Pipeline' --description 'Continuous Integration'
Bulk update work items
# Query items and update in loop for id in $(az boards query --wiql "SELECT ID FROM WorkItems WHERE State='New'" -o tsv); do az boards work-item update --id $id --state "Active" done
Best Practices
Authentication and Security
# Use PAT from environment variable (most secure) export AZURE_DEVOPS_EXT_PAT=$MY_PAT az devops login --organization $ORG_URL # Pipe PAT securely (avoids shell history) echo $MY_PAT | az devops login --organization $ORG_URL # Set defaults to avoid repetition az devops configure --defaults organization=$ORG_URL project=$PROJECT # Clear credentials after use az devops logout --organization $ORG_URL
Idempotent Operations
# Always use --detect for auto-detection az devops configure --defaults organization=$ORG_URL project=$PROJECT # Check existence before creation if ! az pipelines show --id $PIPELINE_ID 2>/dev/null; then az pipelines create --name "$PIPELINE_NAME" --yaml-path azure-pipelines.yml fi # Use --output tsv for shell parsing PIPELINE_ID=$(az pipelines list --query "[?name=='MyPipeline'].id" --output tsv) # Use --output json for programmatic access BUILD_STATUS=$(az pipelines build show --id $BUILD_ID --query "status" --output json)
Script-Safe Output
# Suppress warnings and errors az pipelines list --only-show-errors # No output (useful for commands that only need to execute) az pipelines run --name "$PIPELINE_NAME" --output none # TSV format for shell scripts (clean, no formatting) az repos pr list --output tsv --query "[].{ID:pullRequestId,Title:title}" # JSON with specific fields az pipelines list --output json --query "[].{Name:name, ID:id, URL:url}"
Pipeline Orchestration
# Run pipeline and wait for completion RUN_ID=$(az pipelines run --name "$PIPELINE_NAME" --query "id" -o tsv) while true; do STATUS=$(az pipelines runs show --run-id $RUN_ID --query "status" -o tsv) if [[ "$STATUS" != "inProgress" && "$STATUS" != "notStarted" ]]; then break fi sleep 10 done # Check result RESULT=$(az pipelines runs show --run-id $RUN_ID --query "result" -o tsv) if [[ "$RESULT" == "succeeded" ]]; then echo "Pipeline succeeded" else echo "Pipeline failed with result: $RESULT" exit 1 fi
Variable Group Management
# Create variable group idempotently VG_NAME="production-variables" VG_ID=$(az pipelines variable-group list --query "[?name=='$VG_NAME'].id" -o tsv) if [[ -z "$VG_ID" ]]; then VG_ID=$(az pipelines variable-group create \ --name "$VG_NAME" \ --variables API_URL=$API_URL API_KEY=$API_KEY \ --authorize true \ --query "id" -o tsv) echo "Created variable group with ID: $VG_ID" else echo "Variable group already exists with ID: $VG_ID" fi
Service Connection Automation
# Create service connection using configuration file cat > service-connection.json <<'EOF' { "data": { "subscriptionId": "$SUBSCRIPTION_ID", "subscriptionName": "My Subscription", "creationMode": "Manual", "serviceEndpointId": "$SERVICE_ENDPOINT_ID" }, "url": "https://management.azure.com/", "authorization": { "parameters": { "tenantid": "$TENANT_ID", "serviceprincipalid": "$SP_ID", "authenticationType": "spnKey", "serviceprincipalkey": "$SP_KEY" }, "scheme": "ServicePrincipal" }, "type": "azurerm", "isShared": false, "isReady": true } EOF az devops service-endpoint create \ --service-endpoint-configuration service-connection.json \ --project "$PROJECT"
Pull Request Automation
# Create PR with work items and reviewers PR_ID=$(az repos pr create \ --repository "$REPO_NAME" \ --source-branch "$FEATURE_BRANCH" \ --target-branch main \ --title "Feature: $(git log -1 --pretty=%B)" \ --description "$(git log -1 --pretty=%B)" \ --work-items $WORK_ITEM_1 $WORK_ITEM_2 \ --reviewers "$REVIEWER_1" "$REVIEWER_2" \ --required-reviewers "$LEAD_EMAIL" \ --labels "enhancement" "backlog" \ --open \ --query "pullRequestId" -o tsv) # Set auto-complete when policies pass az repos pr update --id $PR_ID --auto-complete true
Error Handling and Retry Patterns
Retry Logic for Transient Failures
# Retry function for network operations retry_command() { local max_attempts=3 local attempt=1 local delay=5 while [[ $attempt -le $max_attempts ]]; do if "$@"; then return 0 fi echo "Attempt $attempt failed. Retrying in ${delay}s..." sleep $delay ((attempt++)) delay=$((delay * 2)) done echo "All $max_attempts attempts failed" return 1 } # Usage retry_command az pipelines run --name "$PIPELINE_NAME"
Check and Handle Errors
# Check if pipeline exists before operations PIPELINE_ID=$(az pipelines list --query "[?name=='$PIPELINE_NAME'].id" -o tsv) if [[ -z "$PIPELINE_ID" ]]; then echo "Pipeline not found. Creating..." az pipelines create --name "$PIPELINE_NAME" --yaml-path azure-pipelines.yml else echo "Pipeline exists with ID: $PIPELINE_ID" fi
Validate Inputs
# Validate required parameters if [[ -z "$PROJECT" || -z "$REPO" ]]; then echo "Error: PROJECT and REPO must be set" exit 1 fi # Check if branch exists if ! az repos ref list --repository "$REPO" --query "[?name=='refs/heads/$BRANCH']" -o tsv | grep -q .; then echo "Error: Branch $BRANCH does not exist" exit 1 fi
Handle Permission Errors
# Try operation, handle permission errors if az devops security permission update \ --id "$USER_ID" \ --namespace "GitRepositories" \ --project "$PROJECT" \ --token "repoV2/$PROJECT/$REPO_ID" \ --allow-bit 2 \ --deny-bit 0 2>&1 | grep -q "unauthorized"; then echo "Error: Insufficient permissions to update repository permissions" exit 1 fi
Pipeline Failure Notification
# Run pipeline and check result RUN_ID=$(az pipelines run --name "$PIPELINE_NAME" --query "id" -o tsv) # Wait for completion while true; do STATUS=$(az pipelines runs show --run-id $RUN_ID --query "status" -o tsv) if [[ "$STATUS" != "inProgress" && "$STATUS" != "notStarted" ]]; then break fi sleep 10 done # Check result and create work item on failure RESULT=$(az pipelines runs show --run-id $RUN_ID --query "result" -o tsv) if [[ "$RESULT" != "succeeded" ]]; then BUILD_NUMBER=$(az pipelines runs show --run-id $RUN_ID --query "buildNumber" -o tsv) az boards work-item create \ --title "Build $BUILD_NUMBER failed" \ --type Bug \ --description "Pipeline run $RUN_ID failed with result: $RESULT\n\nURL: $ORG_URL/$PROJECT/_build/results?buildId=$RUN_ID" fi
Graceful Degradation
# Try to download artifact, fallback to alternative source if ! az pipelines runs artifact download \ --artifact-name 'webapp' \ --path ./output \ --run-id $RUN_ID 2>/dev/null; then echo "Warning: Failed to download from pipeline run. Falling back to backup source..." # Alternative download method curl -L "$BACKUP_URL" -o ./output/backup.zip fi
Advanced JMESPath Queries
Filtering and Sorting
# Filter by multiple conditions az pipelines list --query "[?name.contains('CI') && enabled==true]" # Filter by status and result az pipelines runs list --query "[?status=='completed' && result=='succeeded']" # Sort by date (descending) az pipelines runs list --query "sort_by([?status=='completed'], &finishTime | reverse(@))" # Get top N items after filtering az pipelines runs list --query "[?result=='succeeded'] | [0:5]"
Nested Queries
# Extract nested properties az pipelines show --id $PIPELINE_ID --query "{Name:name, Repo:repository.{Name:name, Type:type}, Folder:folder}" # Query build details az pipelines build show --id $BUILD_ID --query "{ID:id, Number:buildNumber, Status:status, Result:result, Requested:requestedFor.displayName}"
Complex Filtering
# Find pipelines with specific YAML path az pipelines list --query "[?process.type.name=='yaml' && process.yamlFilename=='azure-pipelines.yml']" # Find PRs from specific reviewer az repos pr list --query "[?contains(reviewers[?displayName=='John Doe'].displayName, 'John Doe')]" # Find work items with specific iteration and state az boards work-item show --id $WI_ID --query "{Title:fields['System.Title'], State:fields['System.State'], Iteration:fields['System.IterationPath']}"
Aggregation
# Count items by status az pipelines runs list --query "groupBy([?status=='completed'], &[result]) | {Succeeded: [?key=='succeeded'][0].count, Failed: [?key=='failed'][0].count}" # Get unique reviewers az repos pr list --query "unique_by(reviewers[], &displayName)" # Sum values az pipelines runs list --query "[?result=='succeeded'] | [].{Duration:duration} | [0].Duration"
Conditional Transformation
# Format dates az pipelines runs list --query "[].{ID:id, Date:createdDate, Formatted:createdDate | format_datetime(@, 'yyyy-MM-dd HH:mm')}" # Conditional output az pipelines list --query "[].{Name:name, Status:(enabled ? 'Enabled' : 'Disabled')}" # Extract with defaults az pipelines show --id $PIPELINE_ID --query "{Name:name, Folder:folder || 'Root', Description:description || 'No description'}"
Complex Workflows
# Find longest running builds az pipelines build list --query "sort_by([?result=='succeeded'], &queueTime) | reverse(@) | [0:3].{ID:id, Number:buildNumber, Duration:duration}" # Get PR statistics per reviewer az repos pr list --query "groupBy([], &reviewers[].displayName) | [].{Reviewer:@.key, Count:length(@)}" # Find work items with multiple child items az boards work-item relation list --id $PARENT_ID --query "[?rel=='System.LinkTypes.Hierarchy-Forward'] | [].{ChildID:url | split('/', @) | [-1]}"
Scripting Patterns for Idempotent Operations
Create or Update Pattern
# Ensure pipeline exists, update if different ensure_pipeline() { local name=$1 local yaml_path=$2 PIPELINE=$(az pipelines list --query "[?name=='$name']" -o json) if [[ -z "$PIPELINE" ]]; then echo "Creating pipeline: $name" az pipelines create --name "$name" --yaml-path "$yaml_path" else echo "Pipeline exists: $name" fi }
Ensure Variable Group
# Create variable group with idempotent updates ensure_variable_group() { local vg_name=$1 shift local variables=("$@") VG_ID=$(az pipelines variable-group list --query "[?name=='$vg_name'].id" -o tsv) if [[ -z "$VG_ID" ]]; then echo "Creating variable group: $vg_name" VG_ID=$(az pipelines variable-group create \ --name "$vg_name" \ --variables "${variables[@]}" \ --authorize true \ --query "id" -o tsv) else echo "Variable group exists: $vg_name (ID: $VG_ID)" fi echo "$VG_ID" }
Ensure Service Connection
# Check if service connection exists, create if not ensure_service_connection() { local name=$1 local project=$2 SC_ID=$(az devops service-endpoint list \ --project "$project" \ --query "[?name=='$name'].id" \ -o tsv) if [[ -z "$SC_ID" ]]; then echo "Service connection not found. Creating..." # Create logic here else echo "Service connection exists: $name" echo "$SC_ID" fi }
Idempotent Work Item Creation
# Create work item only if doesn't exist with same title create_work_item_if_new() { local title=$1 local type=$2 WI_ID=$(az boards query \ --wiql "SELECT ID FROM WorkItems WHERE [System.WorkItemType]='$type' AND [System.Title]='$title'" \ --query "[0].id" -o tsv) if [[ -z "$WI_ID" ]]; then echo "Creating work item: $title" WI_ID=$(az boards work-item create --title "$title" --type "$type" --query "id" -o tsv) else echo "Work item exists: $title (ID: $WI_ID)" fi echo "$WI_ID" }
Bulk Idempotent Operations
# Ensure multiple pipelines exist declare -a PIPELINES=( "ci-pipeline:azure-pipelines.yml" "deploy-pipeline:deploy.yml" "test-pipeline:test.yml" ) for pipeline in "${PIPELINES[@]}"; do IFS=':' read -r name yaml <<< "$pipeline" ensure_pipeline "$name" "$yaml" done
Configuration Synchronization
# Sync variable groups from config file sync_variable_groups() { local config_file=$1 while IFS=',' read -r vg_name variables; do ensure_variable_group "$vg_name" "$variables" done < "$config_file" } # config.csv format: # prod-vars,API_URL=prod.com,API_KEY=secret123 # dev-vars,API_URL=dev.com,API_KEY=secret456
Real-World Workflows
CI/CD Pipeline Setup
# Setup complete CI/CD pipeline setup_cicd_pipeline() { local project=$1 local repo=$2 local branch=$3 # Create variable groups VG_DEV=$(ensure_variable_group "dev-vars" "ENV=dev API_URL=api-dev.com") VG_PROD=$(ensure_variable_group "prod-vars" "ENV=prod API_URL=api-prod.com") # Create CI pipeline az pipelines create \ --name "$repo-CI" \ --repository "$repo" \ --branch "$branch" \ --yaml-path .azure/pipelines/ci.yml \ --skip-run true # Create CD pipeline az pipelines create \ --name "$repo-CD" \ --repository "$repo" \ --branch "$branch" \ --yaml-path .azure/pipelines/cd.yml \ --skip-run true echo "CI/CD pipeline setup complete" }
Automated PR Creation
# Create PR from feature branch with automation create_automated_pr() { local branch=$1 local title=$2 # Get branch info LAST_COMMIT=$(git log -1 --pretty=%B "$branch") COMMIT_SHA=$(git rev-parse "$branch") # Find related work items WORK_ITEMS=$(az boards query \ --wiql "SELECT ID FROM WorkItems WHERE [System.ChangedBy] = @Me AND [System.State] = 'Active'" \ --query "[].id" -o tsv) # Create PR PR_ID=$(az repos pr create \ --source-branch "$branch" \ --target-branch main \ --title "$title" \ --description "$LAST_COMMIT" \ --work-items $WORK_ITEMS \ --auto-complete true \ --query "pullRequestId" -o tsv) # Set required reviewers az repos pr reviewer add \ --id $PR_ID \ --reviewers $(git log -1 --pretty=format:'%ae' "$branch") \ --required true echo "Created PR #$PR_ID" }
Pipeline Monitoring and Alerting
# Monitor pipeline and alert on failure monitor_pipeline() { local pipeline_name=$1 local slack_webhook=$2 while true; do # Get latest run RUN_ID=$(az pipelines list --query "[?name=='$pipeline_name'] | [0].id" -o tsv) RUNS=$(az pipelines runs list --pipeline $RUN_ID --top 1) LATEST_RUN_ID=$(echo "$RUNS" | jq -r '.[0].id') RESULT=$(echo "$RUNS" | jq -r '.[0].result') # Check if failed and not already processed if [[ "$RESULT" == "failed" ]]; then # Send Slack alert curl -X POST "$slack_webhook" \ -H 'Content-Type: application/json' \ -d "{\"text\": \"Pipeline $pipeline_name failed! Run ID: $LATEST_RUN_ID\"}" fi sleep 300 # Check every 5 minutes done }
Bulk Work Item Management
# Bulk update work items based on query bulk_update_work_items() { local wiql=$1 local updates=("$@") # Query work items WI_IDS=$(az boards query --wiql "$wiql" --query "[].id" -o tsv) # Update each work item for wi_id in $WI_IDS; do az boards work-item update --id $wi_id "${updates[@]}" echo "Updated work item: $wi_id" done } # Usage: bulk_update_work_items "SELECT ID FROM WorkItems WHERE State='New'" --state "Active" --assigned-to "[email protected]"
Branch Policy Automation
# Apply branch policies to all repositories apply_branch_policies() { local branch=$1 local project=$2 # Get all repositories REPOS=$(az repos list --project "$project" --query "[].id" -o tsv) for repo_id in $REPOS; do echo "Applying policies to repo: $repo_id" # Require minimum approvers az repos policy approver-count create \ --blocking true \ --enabled true \ --branch "$branch" \ --repository-id "$repo_id" \ --minimum-approver-count 2 \ --creator-vote-counts true # Require work item linking az repos policy work-item-linking create \ --blocking true \ --branch "$branch" \ --enabled true \ --repository-id "$repo_id" # Require build validation BUILD_ID=$(az pipelines list --query "[?name=='CI'].id" -o tsv | head -1) az repos policy build create \ --blocking true \ --enabled true \ --branch "$branch" \ --repository-id "$repo_id" \ --build-definition-id "$BUILD_ID" \ --queue-on-source-update-only true done }
Multi-Environment Deployment
# Deploy across multiple environments deploy_to_environments() { local run_id=$1 shift local environments=("$@") # Download artifacts ARTIFACT_NAME=$(az pipelines runs artifact list --run-id $run_id --query "[0].name" -o tsv) az pipelines runs artifact download \ --artifact-name "$ARTIFACT_NAME" \ --path ./artifacts \ --run-id $run_id # Deploy to each environment for env in "${environments[@]}"; do echo "Deploying to: $env" # Get environment-specific variables VG_ID=$(az pipelines variable-group list --query "[?name=='$env-vars'].id" -o tsv) # Run deployment pipeline DEPLOY_RUN_ID=$(az pipelines run \ --name "Deploy-$env" \ --variables ARTIFACT_PATH=./artifacts ENV="$env" \ --query "id" -o tsv) # Wait for deployment while true; do STATUS=$(az pipelines runs show --run-id $DEPLOY_RUN_ID --query "status" -o tsv) if [[ "$STATUS" != "inProgress" ]]; then break fi sleep 10 done done }
Enhanced Global Arguments
| Parameter | Description |
|---|---|
--help / -h | Show command help |
--output / -o | Output format (json, jsonc, none, table, tsv, yaml, yamlc) |
--query | JMESPath query string for filtering output |
--verbose | Increase logging verbosity |
--debug | Show all debug logs |
--only-show-errors | Only show errors, suppress warnings |
--subscription | Name or ID of subscription |
--yes / -y | Skip confirmation prompts |
Enhanced Common Parameters
| Parameter | Description |
|---|---|
--org / --organization | Azure DevOps organization URL (e.g., https://dev.azure.com/{org}) |
--project / -p | Project name or ID |
--detect | Auto-detect organization from git config |
--yes / -y | Skip confirmation prompts |
--open | Open resource in web browser |
--subscription | Azure subscription (for Azure resources) |
Getting Help
# General help az devops --help # Help for specific command group az pipelines --help az repos pr --help # Help for specific command az repos pr create --help # Search for examples az find "az repos pr create"