Azure Devops

Azure DevOps REST API Skill

Comprehensive guide for Azure DevOps REST API v7.2 operations including work items, pipelines, repositories, test plans, wikis, and search functionality.

Quick Reference

Authentication Methods

Personal Access Token (PAT)

# Base64 encode empty username with PAT
AUTH=$(echo -n ":${PAT}" | base64)
curl -H "Authorization: Basic ${AUTH}" https://dev.azure.com/{org}/_apis/projects

OAuth 2.0 Scopes

API Versioning

Format: {major}.{minor}[-{stage}[.{resource-version}]]

• Current: 7.2-preview.3
• Example: api-version=7.2-preview.3

---

1. Work Item Operations

Available MCP Tools

mcp__ado__wit_get_work_item          - Get single work item
mcp__ado__wit_get_work_items_batch_by_ids - Get multiple work items
mcp__ado__wit_my_work_items          - Get items assigned to me
mcp__ado__wit_create_work_item       - Create new work item
mcp__ado__wit_update_work_item       - Update work item fields
mcp__ado__wit_update_work_items_batch - Bulk update work items
mcp__ado__wit_add_work_item_comment  - Add comment to work item
mcp__ado__wit_list_work_item_comments - List work item comments
mcp__ado__wit_add_child_work_items   - Create child work items
mcp__ado__wit_work_items_link        - Link work items together
mcp__ado__wit_work_item_unlink       - Remove work item links
mcp__ado__wit_link_work_item_to_pull_request - Link to PR
mcp__ado__wit_add_artifact_link      - Add artifact links (branch, commit, build)
mcp__ado__wit_get_work_item_type     - Get work item type definition
mcp__ado__wit_list_backlogs          - List team backlogs
mcp__ado__wit_list_backlog_work_items - Get backlog items
mcp__ado__wit_get_work_items_for_iteration - Get sprint items
mcp__ado__wit_get_query              - Get saved query
mcp__ado__wit_get_query_results_by_id - Execute saved query

WIQL Query Syntax

Basic Structure

SELECT [Fields]
FROM workitems
WHERE [Conditions]
ORDER BY [Fields]
ASOF [DateTime]

Common Macros

Example Queries

-- Active tasks assigned to me
SELECT [System.Id], [System.Title], [System.State]
FROM workitems
WHERE [System.TeamProject] = @project
  AND [System.WorkItemType] = 'Task'
  AND [System.State] = 'Active'
  AND [System.AssignedTo] = @Me
ORDER BY [System.Priority] ASC

-- Bugs created in last 30 days
SELECT [System.Id], [System.Title], [System.CreatedDate]
FROM workitems
WHERE [System.TeamProject] = @project
  AND [System.WorkItemType] = 'Bug'
  AND [System.CreatedDate] >= @Today - 30

-- Parent-child hierarchy
SELECT [Source].[System.Id], [Target].[System.Id]
FROM workitemLinks
WHERE [Source].[System.TeamProject] = @project
  AND [System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'
MODE (Recursive)

JSON Patch Operations

[
  {"op": "add", "path": "/fields/System.Title", "value": "New Title"},
  {"op": "replace", "path": "/fields/System.State", "value": "Active"},
  {"op": "add", "path": "/relations/-", "value": {
    "rel": "System.LinkTypes.Related",
    "url": "https://dev.azure.com/{org}/_apis/wit/workItems/{id}"
  }}
]

Link Types Reference

---

2. Pipeline Operations

Available MCP Tools

mcp__ado__pipelines_get_build_definitions - List pipeline definitions
mcp__ado__pipelines_get_build_definition_revisions - Get definition history
mcp__ado__pipelines_get_builds         - List builds
mcp__ado__pipelines_get_build_status   - Get build status
mcp__ado__pipelines_get_build_log      - Get build logs
mcp__ado__pipelines_get_build_log_by_id - Get specific log
mcp__ado__pipelines_get_build_changes  - Get commits in build
mcp__ado__pipelines_run_pipeline       - Trigger pipeline run
mcp__ado__pipelines_get_run            - Get pipeline run details
mcp__ado__pipelines_list_runs          - List pipeline runs
mcp__ado__pipelines_update_build_stage - Retry/cancel stage

Pipeline Trigger Example

{
  "resources": {
    "repositories": {
      "self": {"refName": "refs/heads/feature-branch"}
    }
  },
  "templateParameters": {
    "environment": "staging"
  },
  "variables": {
    "customVar": {"value": "custom-value", "isSecret": false}
  }
}

Build Status Values

Build Result Values

---

3. Repository Operations

Available MCP Tools

mcp__ado__repo_list_repos_by_project   - List repositories
mcp__ado__repo_get_repo_by_name_or_id  - Get repository details
mcp__ado__repo_list_branches_by_repo   - List branches
mcp__ado__repo_list_my_branches_by_repo - List my branches
mcp__ado__repo_get_branch_by_name      - Get branch details
mcp__ado__repo_create_branch           - Create new branch
mcp__ado__repo_search_commits          - Search commit history
mcp__ado__repo_list_pull_requests_by_repo_or_project - List PRs
mcp__ado__repo_get_pull_request_by_id  - Get PR details
mcp__ado__repo_create_pull_request     - Create PR
mcp__ado__repo_update_pull_request     - Update PR (autocomplete, status)
mcp__ado__repo_update_pull_request_reviewers - Add/remove reviewers
mcp__ado__repo_list_pull_request_threads - List PR comments
mcp__ado__repo_list_pull_request_thread_comments - Get thread comments
mcp__ado__repo_create_pull_request_thread - Create comment thread
mcp__ado__repo_reply_to_comment        - Reply to comment
mcp__ado__repo_resolve_comment         - Resolve thread
mcp__ado__repo_list_pull_requests_by_commits - Find PR by commit

PR Status Values

Merge Strategies

---

4. Test Plan Operations

Available MCP Tools

mcp__ado__testplan_list_test_plans     - List test plans
mcp__ado__testplan_create_test_plan    - Create test plan
mcp__ado__testplan_create_test_suite   - Create test suite
mcp__ado__testplan_list_test_cases     - List test cases in suite
mcp__ado__testplan_create_test_case    - Create test case
mcp__ado__testplan_update_test_case_steps - Update test steps
mcp__ado__testplan_add_test_cases_to_suite - Add cases to suite
mcp__ado__testplan_show_test_results_from_build_id - Get test results

Test Case Steps Format

1. Navigate to login page|Login page displayed
2. Enter username|Username field populated
3. Enter password|Password field populated
4. Click login button|User is logged in successfully

Test Suite Types

Test Outcome Values

---

5. Wiki Operations

Available MCP Tools

mcp__ado__wiki_list_wikis              - List wikis
mcp__ado__wiki_get_wiki                - Get wiki details
mcp__ado__wiki_list_pages              - List wiki pages
mcp__ado__wiki_get_page                - Get page metadata
mcp__ado__wiki_get_page_content        - Get page content
mcp__ado__wiki_create_or_update_page   - Create/update page

Wiki Types

Page Path Format

• Root: /
• Subpage: /Parent/Child
• Spaces: /My%20Page

---

6. Search Operations

Available MCP Tools

mcp__ado__search_code                  - Search source code
mcp__ado__search_workitem              - Search work items
mcp__ado__search_wiki                  - Search wiki pages

Code Search Filters

{
  "Project": ["project-name"],
  "Repository": ["repo-name"],
  "Path": ["/src"],
  "Branch": ["main"],
  "CodeElement": ["class", "def", "function"]
}

Work Item Search Filters

{
  "System.TeamProject": ["project-name"],
  "System.WorkItemType": ["Bug", "Task"],
  "System.State": ["Active", "New"],
  "System.AssignedTo": ["user@domain.com"]
}

---

7. Core Operations

Available MCP Tools

mcp__ado__core_list_projects           - List projects
mcp__ado__core_list_project_teams      - List teams
mcp__ado__core_get_identity_ids        - Get user identity
mcp__ado__work_list_team_iterations    - List iterations
mcp__ado__work_list_iterations         - List all iterations
mcp__ado__work_create_iterations       - Create iterations
mcp__ado__work_assign_iterations       - Assign to team
mcp__ado__work_get_team_capacity       - Get team capacity
mcp__ado__work_update_team_capacity    - Update capacity
mcp__ado__work_get_iteration_capacities - Get iteration capacity

---

8. Advanced Security Operations

Available MCP Tools

mcp__ado__advsec_get_alerts            - Get security alerts
mcp__ado__advsec_get_alert_details     - Get alert details

Alert Types

---

Rate Limiting

TSTU (Throughput Unit) Limits

• Anonymous: 200 TSTUs/minute
• Authenticated: 1200 TSTUs/minute

Response Headers

X-RateLimit-Resource: core
X-RateLimit-Delay: 500
X-RateLimit-Limit: 1200
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1609459200
Retry-After: 30

Handling Rate Limits

import time
import requests

def api_call_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 30))
            time.sleep(retry_after)
            continue
        return response
    raise Exception("Rate limit exceeded after retries")

---

Error Handling

HTTP Status Codes

Error Response Format

{
  "$id": "1",
  "innerException": null,
  "message": "Error description",
  "typeName": "Microsoft.VisualStudio.Services.WebApi.VssServiceException",
  "typeKey": "VssServiceException",
  "errorCode": 0
}

---

Common Field Reference

System Fields

Scheduling Fields

---

Multi-Repo Work Item Segregation

When a single Azure DevOps project contains multiple repositories, use Area Paths for primary segregation and hierarchical Iteration Paths for repo-scoped sprint/epic tracking.

Target Structure

Area Paths:                          Iteration Paths:
project\                             project\Iteration\
├── repo-a           (per-repo)      ├── Sprint 1        (shared across repos)
├── repo-b           (per-repo)      ├── Sprint 2        (shared across repos)
└── repo-c           (per-repo)      ├── repo-a\         (repo-scoped container)
                                     │   ├── epic-1-...  (auto-created by sync)
                                     │   └── epic-2-...
                                     └── repo-b\         (repo-scoped container)

Path Format Differences (Critical)

Azure DevOps uses two different path formats for iterations:

Setup Commands for a New Repo

# 1. Create area path (if not exists)
az boards area project create --name "<repo-name>" --path "\<project>"

# 2. Create iteration container
az boards iteration project create --name "<repo-name>" --path "\<project>\Iteration"

# 3. Configure BMAD sync (devops-sync-config.yaml)
# areaPath: "<project>\\<repo-name>"
# iterationRootPath: "<repo-name>"

Moving Iterations (No Native Move)

Azure DevOps CLI has no move command for iterations. To restructure: 1. Verify no work items assigned: az boards query --wiql "... WHERE [System.IterationPath] = '...'" 2. Delete: az boards iteration project delete --path "\project\Iteration\old-path" --yes 3. Recreate under new parent: az boards iteration project create --name "name" --path "\project\Iteration\new-parent" 4. Update state files with new iteration IDs

Common Error: TF401347

TF401347: The iteration path does not exist — caused by using the wrong path format. Check:

• --iteration on work items uses Project\Parent\Child (no "Iteration" segment)
• --path on iteration create uses \Project\Iteration\Parent (with "Iteration" segment)

---

Best Practices

1. Use Batch Operations

• Use mcp__ado__wit_get_work_items_batch_by_ids instead of multiple single calls
• Max 200 items per batch request

2. Minimize Field Selection

• Only request fields you need: fields=System.Id,System.Title,System.State
• Reduces response size and API load

3. Handle Pagination

• Use $top and $skip for large result sets
• Follow continuation tokens when provided

4. Version Control

• Use test operation in JSON Patch for optimistic concurrency
• Always check rev field before updates

5. Error Recovery

• Implement exponential backoff for rate limits
• Log correlation IDs from response headers

---

References

• Azure DevOps REST API v7.2
• WIQL Syntax Reference
• Authentication Guide
• Rate Limits

---

Gotchas

• REST API rate limits are per-org per-PAT — concurrent batch jobs share the budget. HTTP 429 returns retry-after but most clients ignore it.
• WIQL `[System.AssignedTo]` returns identity ref objects, not names — equality comparison needs EVER operator or a UPN-shaped string match.
• Work-item rev-based optimistic concurrency: concurrent updates with stale rev fail silently (the update is dropped, not errored).
• Pipeline YAML stage-less mode: a YAML with only jobs: runs as one implicit stage, but APIs filtering by stage name return empty.
• PAT scopes are union, not intersection — a "Read & Write" scope on Code doesn't grant Build access; missing scopes get 401 with vague "TF400813" error.
• Date macros (`@Today`, `@StartOfWeek`) work in some queries and not others — saved query in UI may not match WIQL via API.

Git Repositories API Reference

Comprehensive reference for Azure DevOps Git REST API operations.

Table of Contents

• Repository Concepts
• Pull Request Operations
• Branch Policies
• Git Refs and Commits
• Code Review

---

Repository Concepts

Repository Properties

Ref Format

refs/heads/main          # Branch
refs/heads/feature/test  # Feature branch
refs/tags/v1.0.0         # Tag
refs/pull/123/merge      # PR merge ref

---

Pull Request Operations

PR Status Values

Merge Strategies

PR Vote Values

PR Completion Options

{
  "autoCompleteSetBy": {
    "id": "user-guid"
  },
  "completionOptions": {
    "deleteSourceBranch": true,
    "mergeCommitMessage": "Merged PR #123: Feature description",
    "mergeStrategy": "squash",
    "bypassPolicy": false,
    "bypassReason": "",
    "transitionWorkItems": true,
    "squashMerge": true
  }
}

---

Branch Policies

Policy Types

Policy Configuration Example

{
  "isEnabled": true,
  "isBlocking": true,
  "type": {
    "id": "fa4e907d-c16b-4a4c-9dfa-4916e5d171ab"
  },
  "settings": {
    "minimumApproverCount": 2,
    "creatorVoteCounts": false,
    "allowDownvotes": false,
    "resetOnSourcePush": true,
    "scope": [
      {
        "refName": "refs/heads/main",
        "matchKind": "exact",
        "repositoryId": "repo-guid"
      }
    ]
  }
}

---

Git Refs and Commits

Ref Update Operation

Commit Properties

Change Types

---

Code Review

Thread Status

Comment Types

Thread Context

{
  "filePath": "/src/main.cs",
  "rightFileStart": {
    "line": 10,
    "offset": 1
  },
  "rightFileEnd": {
    "line": 15,
    "offset": 50
  },
  "leftFileStart": null,
  "leftFileEnd": null
}

---

MCP Tool Usage Examples

List Repositories

# Using mcp__ado__repo_list_repos_by_project
params = {
    "project": "MyProject",
    "repoNameFilter": "api",  # Optional filter
    "top": 100
}

Get Repository

# Using mcp__ado__repo_get_repo_by_name_or_id
params = {
    "project": "MyProject",
    "repositoryNameOrId": "my-repo"
}

Create Branch

# Using mcp__ado__repo_create_branch
params = {
    "repositoryId": "repo-guid",
    "branchName": "feature/new-feature",
    "sourceBranchName": "main"
}

List Branches

# Using mcp__ado__repo_list_branches_by_repo
params = {
    "repositoryId": "repo-guid",
    "filterContains": "feature",
    "top": 50
}

Search Commits

# Using mcp__ado__repo_search_commits
params = {
    "project": "MyProject",
    "repository": "my-repo",
    "searchText": "fix bug",
    "author": "developer@company.com",
    "fromDate": "2024-01-01T00:00:00Z",
    "toDate": "2024-12-31T23:59:59Z",
    "includeWorkItems": True,
    "top": 20
}

Create Pull Request

# Using mcp__ado__repo_create_pull_request
params = {
    "repositoryId": "repo-guid",
    "sourceRefName": "refs/heads/feature/new-feature",
    "targetRefName": "refs/heads/main",
    "title": "Add new feature",
    "description": "## Summary\nThis PR adds...\n\n## Testing\n- [ ] Unit tests\n- [ ] Integration tests",
    "isDraft": False,
    "workItems": "12345 12346"  # Space-separated IDs
}

Update Pull Request

# Using mcp__ado__repo_update_pull_request
params = {
    "repositoryId": "repo-guid",
    "pullRequestId": 123,
    "title": "Updated title",
    "description": "Updated description",
    "autoComplete": True,
    "mergeStrategy": "Squash",
    "deleteSourceBranch": True,
    "transitionWorkItems": True
}

Add/Remove Reviewers

# Using mcp__ado__repo_update_pull_request_reviewers
params = {
    "repositoryId": "repo-guid",
    "pullRequestId": 123,
    "reviewerIds": ["user-guid-1", "user-guid-2"],
    "action": "add"  # or "remove"
}

List PR Threads

# Using mcp__ado__repo_list_pull_request_threads
params = {
    "repositoryId": "repo-guid",
    "pullRequestId": 123,
    "top": 100
}

Create Comment Thread

# Using mcp__ado__repo_create_pull_request_thread
params = {
    "repositoryId": "repo-guid",
    "pullRequestId": 123,
    "content": "Please review this logic",
    "filePath": "/src/main.cs",
    "rightFileStartLine": 10,
    "rightFileEndLine": 15,
    "status": "Active"
}

Reply to Comment

# Using mcp__ado__repo_reply_to_comment
params = {
    "repositoryId": "repo-guid",
    "pullRequestId": 123,
    "threadId": 456,
    "content": "Good catch, I'll fix this."
}

Resolve Thread

# Using mcp__ado__repo_resolve_comment
params = {
    "repositoryId": "repo-guid",
    "pullRequestId": 123,
    "threadId": 456
}

Find PRs by Commit

# Using mcp__ado__repo_list_pull_requests_by_commits
params = {
    "project": "MyProject",
    "repository": "my-repo",
    "commits": ["abc123def456", "789ghi012jkl"],
    "queryType": "LastMergeCommit"
}

---

Git URL Patterns

Clone URLs

# HTTPS
https://dev.azure.com/{org}/{project}/_git/{repo}

# SSH
git@ssh.dev.azure.com:v3/{org}/{project}/{repo}

# With PAT
https://{pat}@dev.azure.com/{org}/{project}/_git/{repo}

Web URLs

# Repository home
https://dev.azure.com/{org}/{project}/_git/{repo}

# Specific branch
https://dev.azure.com/{org}/{project}/_git/{repo}?version=GB{branch}

# Specific file
https://dev.azure.com/{org}/{project}/_git/{repo}?path=/path/to/file&version=GB{branch}

# Commit
https://dev.azure.com/{org}/{project}/_git/{repo}/commit/{commitId}

# Pull request
https://dev.azure.com/{org}/{project}/_git/{repo}/pullrequest/{prId}

# Compare
https://dev.azure.com/{org}/{project}/_git/{repo}/branchCompare?baseVersion=GB{base}&targetVersion=GB{target}

Pipelines and Build API Reference

Comprehensive reference for Azure DevOps Pipelines REST API operations.

Table of Contents

• Pipeline Concepts
• Build Status and Results
• YAML Pipeline Reference
• Pipeline Variables
• Triggers and Resources

---

Pipeline Concepts

Pipeline Types

Pipeline Hierarchy

Pipeline Definition
    └── Stages
        └── Jobs
            └── Steps (Tasks/Scripts)

Run vs Build

• Pipeline Run: Modern YAML pipeline execution (Pipelines API)
• Build: Classic build or YAML execution (Build API)

---

Build Status and Results

Build Status Values

Build Result Values

Build Reason Values

---

YAML Pipeline Reference

Basic Structure

# azure-pipelines.yml
trigger:
  branches:
    include:
      - main
      - release/*
    exclude:
      - feature/experimental/*
  paths:
    include:
      - src/*
    exclude:
      - docs/*

pr:
  branches:
    include:
      - main
  autoCancel: true

pool:
  vmImage: 'ubuntu-latest'

variables:
  - name: buildConfiguration
    value: 'Release'
  - group: 'production-secrets'

stages:
  - stage: Build
    displayName: 'Build Stage'
    jobs:
      - job: BuildJob
        displayName: 'Build Application'
        steps:
          - task: DotNetCoreCLI@2
            displayName: 'Build'
            inputs:
              command: 'build'
              projects: '**/*.csproj'

Stage Template

stages:
  - stage: stageName
    displayName: 'Stage Display Name'
    dependsOn: [previousStage]
    condition: succeeded()
    variables:
      stageVar: 'value'
    jobs:
      - job: jobName
        # Job definition

Job Template

jobs:
  - job: JobName
    displayName: 'Job Display Name'
    pool:
      vmImage: 'ubuntu-latest'
    timeoutInMinutes: 60
    cancelTimeoutInMinutes: 5
    dependsOn: [PreviousJob]
    condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
    continueOnError: false
    strategy:
      matrix:
        linux:
          imageName: 'ubuntu-latest'
        windows:
          imageName: 'windows-latest'
      maxParallel: 2
    steps:
      - script: echo Hello

Deployment Job

jobs:
  - deployment: DeploymentName
    displayName: 'Deploy to Production'
    environment: 'production'
    strategy:
      runOnce:
        deploy:
          steps:
            - download: current
              artifact: drop
            - script: ./deploy.sh

---

Pipeline Variables

Predefined Variables

Variable Syntax

# Macro syntax (compile-time)
variables:
  myVar: 'value'
steps:
  - script: echo $(myVar)

# Template expression (compile-time)
steps:
  - script: echo ${{ variables.myVar }}

# Runtime expression
steps:
  - script: echo $[variables.myVar]

# Environment variable (Bash)
steps:
  - script: echo $MYVAR
    env:
      MYVAR: $(myVar)

# PowerShell
steps:
  - powershell: Write-Host $env:MYVAR
    env:
      MYVAR: $(myVar)

Variable Groups

variables:
  - group: 'my-variable-group'
  - name: localVar
    value: 'local value'

Secret Variables

variables:
  - name: mySecret
    value: $(secretFromLibrary)  # From variable group

steps:
  - script: |
      echo "Using secret (masked in logs)"
      curl -H "Authorization: Bearer $(mySecret)" https://api.example.com
    env:
      MY_SECRET: $(mySecret)

---

Triggers and Resources

CI Triggers

# Branch triggers
trigger:
  batch: true  # Batch changes
  branches:
    include:
      - main
      - release/*
    exclude:
      - feature/experimental/*
  paths:
    include:
      - src/*
    exclude:
      - '**/*.md'
  tags:
    include:
      - v*
    exclude:
      - v0.*

# Disable CI trigger
trigger: none

PR Triggers

pr:
  autoCancel: true
  drafts: false
  branches:
    include:
      - main
      - release/*
  paths:
    include:
      - src/*
    exclude:
      - docs/*

Scheduled Triggers

schedules:
  - cron: '0 0 * * *'  # Daily at midnight UTC
    displayName: 'Daily Build'
    branches:
      include:
        - main
    always: false  # Only if changes
  - cron: '0 12 * * 0'  # Weekly Sunday noon
    displayName: 'Weekly Build'
    branches:
      include:
        - main
    always: true  # Always run

Pipeline Resources

resources:
  repositories:
    - repository: templates
      type: git
      name: ProjectName/TemplateRepo
      ref: refs/heads/main
    - repository: external
      type: github
      name: org/repo
      endpoint: 'GitHub Connection'

  pipelines:
    - pipeline: upstream
      source: 'Upstream-Pipeline'
      trigger:
        branches:
          include:
            - main

  containers:
    - container: build-container
      image: mcr.microsoft.com/dotnet/sdk:6.0
      options: --privileged

  packages:
    - package: myPackage
      type: npm
      connection: 'npm-connection'
      name: '@scope/package'
      version: 1.0.0

---

MCP Tool Usage Examples

List Build Definitions

# Using mcp__ado__pipelines_get_build_definitions
params = {
    "project": "MyProject",
    "includeLatestBuilds": True,
    "queryOrder": "LastModifiedDescending",
    "top": 50
}

Get Builds

# Using mcp__ado__pipelines_get_builds
params = {
    "project": "MyProject",
    "definitions": [123, 456],  # Definition IDs
    "statusFilter": 2,  # Completed
    "resultFilter": 8,  # Failed
    "queryOrder": "FinishTimeDescending",
    "top": 20
}

Run Pipeline

# Using mcp__ado__pipelines_run_pipeline
params = {
    "project": "MyProject",
    "pipelineId": 123,
    "resources": {
        "repositories": {
            "self": {
                "refName": "refs/heads/feature-branch"
            }
        }
    },
    "templateParameters": {
        "environment": "staging",
        "runTests": "true"
    },
    "variables": {
        "customVar": {
            "value": "custom-value",
            "isSecret": False
        }
    },
    "stagesToSkip": ["Deploy-Production"]
}

Get Build Logs

# Using mcp__ado__pipelines_get_build_log
params = {
    "project": "MyProject",
    "buildId": 12345
}

# Get specific log
# Using mcp__ado__pipelines_get_build_log_by_id
params = {
    "project": "MyProject",
    "buildId": 12345,
    "logId": 5,
    "startLine": 100,
    "endLine": 200
}

Retry Failed Stage

# Using mcp__ado__pipelines_update_build_stage
params = {
    "project": "MyProject",
    "buildId": 12345,
    "stageName": "Deploy",
    "status": "Retry",
    "forceRetryAllJobs": True
}

Get Pipeline Run

# Using mcp__ado__pipelines_get_run
params = {
    "project": "MyProject",
    "pipelineId": 123,
    "runId": 456
}

---

Common Pipeline Tasks

Checkout

steps:
  - checkout: self
    clean: true
    fetchDepth: 0
    lfs: true
    submodules: recursive
    persistCredentials: true

Download Artifacts

steps:
  - download: current
    artifact: 'drop'
    patterns: '**/*.dll'

  - task: DownloadPipelineArtifact@2
    inputs:
      buildType: 'specific'
      project: 'ProjectGuid'
      definition: '123'
      buildVersionToDownload: 'latest'
      artifactName: 'drop'
      targetPath: '$(Pipeline.Workspace)/artifacts'

Publish Artifacts

steps:
  - task: PublishPipelineArtifact@1
    inputs:
      targetPath: '$(Build.ArtifactStagingDirectory)'
      artifact: 'drop'
      publishLocation: 'pipeline'

Cache

steps:
  - task: Cache@2
    inputs:
      key: 'npm | "$(Agent.OS)" | package-lock.json'
      restoreKeys: |
        npm | "$(Agent.OS)"
      path: $(npm_config_cache)
    displayName: 'Cache npm packages'

Test Plans API Reference

Comprehensive reference for Azure DevOps Test Plans REST API operations.

Table of Contents

• Test Plan Hierarchy
• Test Case Management
• Test Runs and Results
• Test Configurations
• Test Points

---

Test Plan Hierarchy

Structure

Test Plan
    └── Test Suite (Root)
        ├── Test Suite (Static)
        │   └── Test Cases
        ├── Test Suite (Requirements-based)
        │   └── Test Cases (auto-linked)
        └── Test Suite (Query-based)
            └── Test Cases (dynamic)

Test Suite Types

Test Plan States

---

Test Case Management

Test Case Fields

Test Steps Format

1. Step action|Expected result
2. Another step|Another expected result
3. Validate data|Data is correct

Test Steps XML Structure

<steps id="0" last="3">
  <step id="1" type="ActionStep">
    <parameterizedString isFormatted="true">
      &lt;P&gt;Navigate to login page&lt;/P&gt;
    </parameterizedString>
    <parameterizedString isFormatted="true">
      &lt;P&gt;Login page is displayed&lt;/P&gt;
    </parameterizedString>
  </step>
  <step id="2" type="ActionStep">
    <parameterizedString isFormatted="true">
      &lt;P&gt;Enter username @username&lt;/P&gt;
    </parameterizedString>
    <parameterizedString isFormatted="true">
      &lt;P&gt;Username field populated&lt;/P&gt;
    </parameterizedString>
  </step>
</steps>

Test Case States

Automation Status

---

Test Runs and Results

Test Run States

Test Run Types

Test Outcome Values

Test Result Fields

---

Test Configurations

Configuration Properties

Configuration Variables

{
  "name": "Windows 11 Chrome",
  "description": "Test on Windows 11 with Chrome browser",
  "values": [
    {"name": "Operating System", "value": "Windows 11"},
    {"name": "Browser", "value": "Chrome"},
    {"name": "Browser Version", "value": "Latest"}
  ]
}

---

Test Points

Test Point Concept

A Test Point is the combination of:

• Test Case
• Test Configuration
• Test Suite

Test Point Properties

Test Point Assignment

{
  "id": 123,
  "testCase": {"id": 456},
  "configuration": {"id": 1},
  "assignedTo": {
    "displayName": "Test User",
    "uniqueName": "user@domain.com"
  }
}

---

MCP Tool Usage Examples

List Test Plans

# Using mcp__ado__testplan_list_test_plans
params = {
    "project": "MyProject",
    "filterActivePlans": True,
    "includePlanDetails": True
}

Create Test Plan

# Using mcp__ado__testplan_create_test_plan
params = {
    "project": "MyProject",
    "name": "Q1 2024 Release Testing",
    "iteration": "MyProject\\Release 1.0",
    "areaPath": "MyProject\\Team A",
    "description": "Test plan for Q1 2024 release",
    "startDate": "2024-01-01",
    "endDate": "2024-03-31"
}

Create Test Suite

# Using mcp__ado__testplan_create_test_suite
params = {
    "project": "MyProject",
    "planId": 123,
    "parentSuiteId": 456,  # Root suite ID if top-level
    "name": "Login Feature Tests"
}

Create Test Case

# Using mcp__ado__testplan_create_test_case
params = {
    "project": "MyProject",
    "title": "Verify successful login with valid credentials",
    "priority": 1,
    "areaPath": "MyProject\\Team A",
    "iterationPath": "MyProject\\Sprint 1",
    "steps": """1. Navigate to login page|Login page is displayed
2. Enter valid username in the username field|Username is entered
3. Enter valid password in the password field|Password is masked and entered
4. Click the Login button|User is redirected to dashboard
5. Verify user name is displayed|User's name appears in header""",
    "testsWorkItemId": 789  # Optional: link to user story/requirement
}

Update Test Case Steps

# Using mcp__ado__testplan_update_test_case_steps
params = {
    "id": 12345,
    "steps": """1. Navigate to login page|Login page is displayed
2. Enter valid username|Username field populated
3. Enter valid password|Password field shows masked characters
4. Click Login button|System processes credentials
5. Verify dashboard loads|Dashboard is displayed with user info"""
}

Add Test Cases to Suite

# Using mcp__ado__testplan_add_test_cases_to_suite
params = {
    "project": "MyProject",
    "planId": 123,
    "suiteId": 456,
    "testCaseIds": ["12345", "12346", "12347"]
}

List Test Cases in Suite

# Using mcp__ado__testplan_list_test_cases
params = {
    "project": "MyProject",
    "planid": 123,
    "suiteid": 456
}

Get Test Results from Build

# Using mcp__ado__testplan_show_test_results_from_build_id
params = {
    "project": "MyProject",
    "buildid": 78901
}

---

Test Plan Best Practices

1. Structure Test Plans by Release/Sprint

Release 2.0 Test Plan
├── Sprint 1 Tests
│   ├── Feature A Tests
│   └── Feature B Tests
├── Sprint 2 Tests
│   └── Feature C Tests
├── Regression Tests
└── Performance Tests

2. Use Requirements-Based Suites

Link test suites to user stories for traceability:

User Story: As a user, I want to login...
└── Requirements Suite
    ├── TC: Valid login
    ├── TC: Invalid password
    ├── TC: Account locked
    └── TC: Forgot password

3. Parameterize Test Cases

Use shared parameters for data-driven testing:

@username = testuser1, testuser2, admin
@password = valid123, Valid456, Admin789

4. Configure Multiple Configurations

Test across environments:

5. Link to Automation

{
  "automationStatus": "Automated",
  "automatedTestName": "MyTests.LoginTests.ValidLoginTest",
  "automatedTestStorage": "MyTests.dll",
  "automatedTestType": "Unit Test"
}

Wiki and Search API Reference

Comprehensive reference for Azure DevOps Wiki and Search REST API operations.

Table of Contents

• Wiki Operations
• Code Search
• Work Item Search
• Wiki Search
• Search Filters

---

Wiki Operations

Wiki Types

Wiki Properties

Page Path Format

Page Properties

Wiki Markdown Extensions

# Standard Markdown
**bold** *italic* `code`

# Azure DevOps Extensions
[[_TOC_]]                    # Table of contents
[[/Page/Path]]               # Wiki page link
[[/Page/Path|Display Text]]  # Named wiki link

# Work Item Links
#1234                        # Work item link
AB#1234                      # Cross-project work item

# Mentions
@<user-guid>                 # User mention
@<group-name>                # Group mention

# Pull Request Links
!123                         # PR link

# Code Snippets
:::code language="csharp" source="path/to/file.cs" range="1-10":::

# Mermaid Diagrams
:::mermaid
graph TD
    A --> B
:::

# Math (LaTeX)
$$E = mc^2$$
$inline math$

---

Code Search

Search Syntax

Code Search Filters

Code Element Filters

Example Code Searches

# Find class definitions
class:UserService

# Find methods with specific name
method:ValidateCredentials

# Find in specific repo and path
repo:Backend path:src/api login

# Find specific file type
ext:cs "async Task" repo:MyRepo

# Complex query
repo:Backend path:src NOT path:test method:Login

---

Work Item Search

Work Item Search Filters

Date Filters

Date Syntax

created:>=2024-01-01
changeddate:<=2024-06-30
created:2024-01-01..2024-03-31
created:@Today-30

Example Work Item Searches

# Active bugs assigned to me
t:Bug s:Active a:@Me

# High priority items
t:Task priority:<=2 s:Active

# Recently created in current sprint
created:@Today-7 iteration:@CurrentIteration

# Specific area path
area:"MyProject\Backend Team" t:User Story

# With specific tag
tags:security t:Bug s:Active

# Created by specific user
c:"john.doe@company.com" created:>=2024-01-01

---

Wiki Search

Wiki Search Filters

Example Wiki Searches

# Search in specific wiki
wiki:"Developer Wiki" API

# Search specific path
path:/Architecture microservices

# Multiple terms
"getting started" installation project:MyProject

---

Search Filters

Filter Structure (API)

{
  "searchText": "search query",
  "filters": {
    "Project": ["Project1", "Project2"],
    "Repository": ["Repo1"],
    "Path": ["/src"],
    "Branch": ["main", "develop"],
    "CodeElement": ["class", "method"]
  },
  "$skip": 0,
  "$top": 25,
  "$orderBy": [
    {
      "field": "filename",
      "sortOrder": "ASC"
    }
  ]
}

Facets Response

{
  "facets": {
    "Project": [
      {"name": "MyProject", "count": 150},
      {"name": "AnotherProject", "count": 45}
    ],
    "Repository": [
      {"name": "Backend", "count": 100},
      {"name": "Frontend", "count": 50}
    ],
    "CodeElement": [
      {"name": "class", "count": 30},
      {"name": "method", "count": 120}
    ]
  }
}

---

MCP Tool Usage Examples

List Wikis

# Using mcp__ado__wiki_list_wikis
params = {
    "project": "MyProject"
}

Get Wiki

# Using mcp__ado__wiki_get_wiki
params = {
    "wikiIdentifier": "MyProject.wiki",
    "project": "MyProject"
}

List Wiki Pages

# Using mcp__ado__wiki_list_pages
params = {
    "wikiIdentifier": "MyProject.wiki",
    "project": "MyProject",
    "pageViewsForDays": 7,  # Include view stats
    "top": 50
}

Get Wiki Page Content

# Using mcp__ado__wiki_get_page_content
params = {
    "wikiIdentifier": "MyProject.wiki",
    "project": "MyProject",
    "path": "/Getting-Started/Setup"
}

# Or by URL
params = {
    "url": "https://dev.azure.com/org/project/_wiki/wikis/wiki-name?pagePath=/My%20Page"
}

Create/Update Wiki Page

# Using mcp__ado__wiki_create_or_update_page
params = {
    "wikiIdentifier": "MyProject.wiki",
    "project": "MyProject",
    "path": "/Guides/New-Feature",
    "content": """# New Feature Guide

## Overview
This guide covers the new feature implementation.

## Steps
1. Step one
2. Step two

## Related
- [[/API/Reference]]
- #12345
"""
}

Search Code

# Using mcp__ado__search_code
params = {
    "searchText": "async Task<User> GetUserById",
    "project": ["MyProject"],
    "repository": ["Backend"],
    "path": ["/src"],
    "branch": ["main"],
    "top": 25,
    "includeFacets": True
}

Search Work Items

# Using mcp__ado__search_workitem
params = {
    "searchText": "login authentication",
    "project": ["MyProject"],
    "workItemType": ["Bug", "User Story"],
    "state": ["Active", "New"],
    "assignedTo": ["@Me"],
    "top": 50,
    "includeFacets": True
}

Search Wiki

# Using mcp__ado__search_wiki
params = {
    "searchText": "deployment guide kubernetes",
    "project": ["MyProject"],
    "wiki": ["Team Wiki"],
    "top": 20,
    "includeFacets": True
}

---

Search Response Structure

Code Search Result

{
  "count": 150,
  "results": [
    {
      "fileName": "UserService.cs",
      "path": "/src/Services/UserService.cs",
      "repository": {
        "name": "Backend",
        "id": "repo-guid"
      },
      "project": {
        "name": "MyProject"
      },
      "versions": [
        {
          "branchName": "main",
          "changeId": "commit-sha"
        }
      ],
      "matches": {
        "content": [
          {
            "charOffset": 100,
            "length": 15
          }
        ]
      },
      "contentId": "blob-sha"
    }
  ],
  "facets": {
    "Project": [...],
    "Repository": [...],
    "CodeElement": [...]
  }
}

Work Item Search Result

{
  "count": 45,
  "results": [
    {
      "project": {
        "name": "MyProject"
      },
      "fields": {
        "system.id": "12345",
        "system.workitemtype": "Bug",
        "system.title": "Login fails with SSO",
        "system.state": "Active",
        "system.assignedto": "user@company.com"
      },
      "hits": [
        {
          "fieldReferenceName": "system.title",
          "highlights": ["Login fails with <highlighttext>SSO</highlighttext>"]
        }
      ],
      "url": "https://dev.azure.com/org/project/_workitems/edit/12345"
    }
  ],
  "facets": {
    "System.WorkItemType": [...],
    "System.State": [...],
    "System.AssignedTo": [...]
  }
}

---

Best Practices

1. Use Specific Filters

# Bad: Too broad
login

# Good: Specific
repo:Backend path:src/auth class:LoginService method:Validate

2. Leverage Facets

Use facets to narrow results progressively.

3. Quote Exact Phrases

"public async Task" vs public async Task

4. Use Code Element Filters for Code

# Find all implementations of interface
class:IUserRepository NOT interface:IUserRepository

5. Combine Filters

t:Bug s:Active a:@Me created:@Today-7 priority:<=2

Work Item Tracking API Reference

Comprehensive reference for Azure DevOps Work Item Tracking REST API operations.

Table of Contents

• Work Item Fields
• Work Item Types
• WIQL Reference
• Link Types
• State Transitions

---

Work Item Fields

System Fields

Scheduling Fields

Bug-Specific Fields

Custom Field Pattern

Custom fields follow the pattern: Custom.{FieldName}

---

Work Item Types

Agile Process Template

Scrum Process Template

CMMI Process Template

---

WIQL Reference

Query Syntax

SELECT [Field1], [Field2], ...
FROM workitems | workitemLinks
WHERE [Conditions]
ORDER BY [Field] [ASC|DESC]
ASOF [DateTime]
MODE [Options]

Operators

Macros

Link Query Modes

Example Queries

-- Active bugs assigned to me, high priority
SELECT [System.Id], [System.Title], [System.State], [Microsoft.VSTS.Common.Severity]
FROM workitems
WHERE [System.TeamProject] = @Project
  AND [System.WorkItemType] = 'Bug'
  AND [System.State] = 'Active'
  AND [System.AssignedTo] = @Me
  AND [Microsoft.VSTS.Common.Priority] <= 2
ORDER BY [Microsoft.VSTS.Common.Priority] ASC, [System.CreatedDate] DESC

-- Items changed in last week
SELECT [System.Id], [System.Title], [System.ChangedDate], [System.ChangedBy]
FROM workitems
WHERE [System.TeamProject] = @Project
  AND [System.ChangedDate] >= @Today - 7
ORDER BY [System.ChangedDate] DESC

-- Current sprint work items
SELECT [System.Id], [System.Title], [System.State], [System.AssignedTo]
FROM workitems
WHERE [System.TeamProject] = @Project
  AND [System.IterationPath] = @CurrentIteration
  AND [System.WorkItemType] IN ('User Story', 'Task', 'Bug')
ORDER BY [System.State], [System.AssignedTo]

-- Parent-child hierarchy
SELECT [Source].[System.Id], [Source].[System.Title],
       [Target].[System.Id], [Target].[System.Title]
FROM workitemLinks
WHERE [Source].[System.TeamProject] = @Project
  AND [Source].[System.WorkItemType] = 'User Story'
  AND [System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'
  AND [Target].[System.WorkItemType] = 'Task'
MODE (MustContain)

---

Link Types

Standard Link Types

External Link Types

VSTFS Link URIs

# Branch
vstfs:///Git/Ref/{projectId}/{repositoryId}/GB{branchName}

# Commit
vstfs:///Git/Commit/{projectId}/{repositoryId}/{commitId}

# Pull Request
vstfs:///Git/PullRequestId/{projectId}/{pullRequestId}

# Build
vstfs:///Build/Build/{projectId}/{buildId}

# Release
vstfs:///ReleaseManagement/ReleaseEnvironment/{projectId}/{releaseId}:{environmentId}

---

State Transitions

Agile Bug States

New → Active → Resolved → Closed
         ↓         ↓
      Removed   Removed

Agile User Story States

New → Active → Resolved → Closed
         ↓
      Removed

Agile Task States

New → Active → Closed
         ↓
      Removed

State Reasons

---

MCP Tool Usage Examples

Get Work Item

# Using mcp__ado__wit_get_work_item
params = {
    "project": "MyProject",
    "id": 12345,
    "expand": "relations",  # Include links
    "fields": ["System.Id", "System.Title", "System.State"]
}

Create Work Item

# Using mcp__ado__wit_create_work_item
params = {
    "project": "MyProject",
    "workItemType": "Bug",
    "fields": [
        {"name": "System.Title", "value": "Login button not working"},
        {"name": "System.Description", "value": "Users cannot click the login button"},
        {"name": "Microsoft.VSTS.Common.Severity", "value": "2 - High"},
        {"name": "System.AssignedTo", "value": "user@company.com"}
    ]
}

Update Work Item

# Using mcp__ado__wit_update_work_item
params = {
    "id": 12345,
    "updates": [
        {"op": "add", "path": "/fields/System.State", "value": "Active"},
        {"op": "add", "path": "/fields/System.AssignedTo", "value": "dev@company.com"}
    ]
}

Link Work Items

# Using mcp__ado__wit_work_items_link
params = {
    "project": "MyProject",
    "updates": [
        {"id": 12345, "linkToId": 12346, "type": "child"},
        {"id": 12345, "linkToId": 12347, "type": "related"}
    ]
}

Add Artifact Link

# Using mcp__ado__wit_add_artifact_link
params = {
    "workItemId": 12345,
    "project": "MyProject",
    "linkType": "Branch",
    "projectId": "project-guid",
    "repositoryId": "repo-guid",
    "branchName": "feature/new-feature"
}