Azure PowerShell DevOps Reference

Introduction

The Azure DevOps PowerShell module (Az.DevOps) provides cmdlets for managing your Azure DevOps resources programmatically. This module allows you to automate tasks related to pipelines, repositories, work items, test plans, and more.

Use these cmdlets to integrate Azure DevOps into your existing automation workflows, build custom dashboards, and manage your projects efficiently.

Installation

To install the Az.DevOps module, open a PowerShell session and run the following command:

Install-Module -Name Az.DevOps -Scope CurrentUser -Repository PSGallery -Force

You may be prompted to install additional dependencies or trusted repositories. It is recommended to approve these actions to ensure proper functionality.

Getting Started

After installation, you need to connect to your Azure DevOps organization. Use the Connect-AzDevOpsOrganization cmdlet:

Connect-AzDevOpsOrganization -Project -OrganizationUrl

Replace <YourProjectName> with your Azure DevOps project name and <YourOrganizationUrl> with the URL of your Azure DevOps organization (e.g., https://dev.azure.com/yourcompany).

You will be prompted to authenticate. You can use your Azure Active Directory credentials or a Personal Access Token (PAT).

Az.DevOps Module Overview

The Az.DevOps module is organized into several functional areas, each corresponding to a part of Azure DevOps:

Pipelines

Manage build and release pipelines, definitions, runs, and agents.

Get-AzDevOpsPipeline
New-AzDevOpsPipeline
Update-AzDevOpsPipeline
Get-AzDevOpsPipelineRun
Invoke-AzDevOpsPipeline

Boards

Interact with work items, queries, and iterations.

Get-AzDevOpsWorkItem
New-AzDevOpsWorkItem
Update-AzDevOpsWorkItem
Get-AzDevOpsQuery

Repositories

Manage Git repositories, branches, and commits.

Get-AzDevOpsRepository
New-AzDevOpsRepository
Get-AzDevOpsBranch
Update-AzDevOpsBranch

Test Plans

Manage test plans, suites, and test cases.

Get-AzDevOpsTestPlan
New-AzDevOpsTestPlan
Get-AzDevOpsTestSuite

Artifacts

Manage package feeds and versions.

Get-AzDevOpsFeed
Get-AzDevOpsPackage

Common Tasks

Here are some common scenarios you can accomplish with the Az.DevOps module:

Listing all pipelines: Get-AzDevOpsPipeline -All
Triggering a specific pipeline: Invoke-AzDevOpsPipeline -DefinitionId -BranchName main
Creating a new work item: New-AzDevOpsWorkItem -Title "Fix Bug XYZ" -WorkItemType Bug -Description "Investigate and resolve the bug."
Getting the latest build: Get-AzDevOpsPipelineRun -DefinitionId -Top 1 -Statuss Completed
Listing repositories: Get-AzDevOpsRepository

Examples

Example 1: Get all work items of type 'Bug' in a project

To retrieve all work items classified as 'Bug' within your connected Azure DevOps project, use:


Get-AzDevOpsOrganization -Project "MyAwesomeProject" | Get-AzDevOpsWorkItem -Query "SELECT [System.Id], [System.Title], [System.State] FROM workitems WHERE [System.WorkItemType] = 'Bug'"

Example 2: Trigger a release pipeline and wait for completion

This example demonstrates how to trigger a release pipeline and poll for its status until it completes.


$pipelineName = "MyReleasePipeline"
$pipeline = Get-AzDevOpsPipeline -Name $pipelineName
$release = Invoke-AzDevOpsPipeline -DefinitionId $pipeline.Id
Write-Host "Triggered Release ID: $($release.Id)"

# Wait for completion (with a timeout)
$timeout = New-TimeSpan -Minutes 30
$startTime = Get-Date
while ((Get-Date) -lt ($startTime + $timeout)) {
    $release = Get-AzDevOpsRelease -Id $release.Id
    if ($release.Status -eq "Succeeded" -or $release.Status -eq "Failed") {
        Write-Host "Release $($release.Id) finished with status: $($release.Status)"
        break
    }
    Write-Host "Waiting for release $($release.Id) to complete. Current status: $($release.Status)"
    Start-Sleep -Seconds 30
}
if ((Get-Date) -ge ($startTime + $timeout)) {
    Write-Host "Timeout waiting for release $($release.Id) to complete."
}

Troubleshooting

If you encounter issues:

Ensure the Az.DevOps module is up-to-date: Update-Module -Name Az.DevOps
Verify your organization URL and project name are correct.
Check the permissions of your Personal Access Token (PAT) if you are using one.
Use the -Verbose or -Debug flags with cmdlets for more detailed output.
Consult the official Azure DevOps REST API documentation for underlying operations.

Microsoft Docs

Azure DevOps PowerShell Reference