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

| Area | Base URL | MCP Tool Prefix |
|------|----------|-----------------|
| Core | `dev.azure.com/{org}/_apis/` | `mcp__ado__core_*` |
| Work Items | `dev.azure.com/{org}/{project}/_apis/wit/` | `mcp__ado__wit_*` |
| Pipelines | `dev.azure.com/{org}/{project}/_apis/pipelines/` | `mcp__ado__pipelines_*` |
| Git/Repos | `dev.azure.com/{org}/{project}/_apis/git/` | `mcp__ado__repo_*` |
| Test Plans | `dev.azure.com/{org}/{project}/_apis/testplan/` | `mcp__ado__testplan_*` |
| Wiki | `dev.azure.com/{org}/{project}/_apis/wiki/` | `mcp__ado__wiki_*` |
| Search | `almsearch.dev.azure.com/{org}/_apis/search/` | `mcp__ado__search_*` |

## Authentication Methods

### Personal Access Token (PAT)

```bash
# 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

| Scope | Access Level |
|-------|--------------|
| `vso.work` | Read work items |
| `vso.work_write` | Create/update work items |
| `vso.code` | Read source code |
| `vso.code_write` | Create branches, PRs |
| `vso.build_execute` | Run pipelines |
| `vso.test` | Read test plans |
| `vso.wiki` | Read wikis |

## 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

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

#### Common Macros

| Macro | Description |
|-------|-------------|
| `@Me` | Current user |
| `@project` | Current project |
| `@Today` | Today's date |
| `@Today - N` | N days ago |
| `@CurrentIteration` | Current sprint |
| `@StartOfMonth` | First of month |

#### Example Queries

```sql
-- 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

```json
[
  {"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

| Type | Rel Name |
|------|----------|
| Parent | `System.LinkTypes.Hierarchy-Reverse` |
| Child | `System.LinkTypes.Hierarchy-Forward` |
| Related | `System.LinkTypes.Related` |
| Predecessor | `System.LinkTypes.Dependency-Reverse` |
| Successor | `System.LinkTypes.Dependency-Forward` |

---

## 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

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

### Build Status Values

| Status | Description |
|--------|-------------|
| `none` | Not started |
| `inProgress` | Running |
| `completed` | Finished |
| `cancelling` | Being cancelled |
| `postponed` | Delayed |
| `notStarted` | Queued |

### Build Result Values

| Result | Description |
|--------|-------------|
| `succeeded` | All tasks passed |
| `partiallySucceeded` | Some tasks failed |
| `failed` | Build failed |
| `canceled` | User cancelled |

---

## 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

| Status | Description |
|--------|-------------|
| `active` | Open for review |
| `abandoned` | Closed without merge |
| `completed` | Merged |

### Merge Strategies

| Strategy | Description |
|----------|-------------|
| `noFastForward` | Merge commit (default) |
| `squash` | Squash commits |
| `rebase` | Rebase and fast-forward |
| `rebaseMerge` | Rebase with merge commit |

---

## 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

| Type | Description |
|------|-------------|
| `staticTestSuite` | Manual hierarchy |
| `dynamicTestSuite` | Query-based |
| `requirementTestSuite` | Linked to requirement |

### Test Outcome Values

| Outcome | Description |
|---------|-------------|
| `Passed` | Test passed |
| `Failed` | Test failed |
| `Blocked` | Cannot execute |
| `NotExecuted` | Not run |
| `Inconclusive` | No clear result |

---

## 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

| Type | Description |
|------|-------------|
| `projectWiki` | Project-scoped wiki |
| `codeWiki` | Git-backed wiki |

### 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

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

### Work Item Search Filters

```json
{
  "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

| Type | Description |
|------|-------------|
| `Dependency` | Vulnerable dependencies |
| `Secret` | Exposed secrets |
| `Code` | Code vulnerabilities |

---

## 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

```python
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

| Code | Meaning |
|------|---------|
| 200 | Success |
| 201 | Created |
| 204 | No Content (DELETE) |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 409 | Conflict (version) |
| 429 | Rate Limited |
| 500 | Server Error |

### Error Response Format

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

---

## Common Field Reference

### System Fields

| Field | Reference Name |
|-------|----------------|
| ID | `System.Id` |
| Title | `System.Title` |
| State | `System.State` |
| Assigned To | `System.AssignedTo` |
| Area Path | `System.AreaPath` |
| Iteration Path | `System.IterationPath` |
| Work Item Type | `System.WorkItemType` |
| Created Date | `System.CreatedDate` |
| Changed Date | `System.ChangedDate` |
| Tags | `System.Tags` |
| Description | `System.Description` |

### Scheduling Fields

| Field | Reference Name |
|-------|----------------|
| Story Points | `Microsoft.VSTS.Scheduling.Effort` |
| Remaining Work | `Microsoft.VSTS.Scheduling.RemainingWork` |
| Original Estimate | `Microsoft.VSTS.Scheduling.OriginalEstimate` |
| Completed Work | `Microsoft.VSTS.Scheduling.CompletedWork` |

---

## 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:

| Operation | Format | Example |
|-----------|--------|---------|
| `az boards iteration project create --path` | `\Project\Iteration\Parent` (literal "Iteration" segment required) | `\devops-team\Iteration\azure-quota-automation` |
| `az boards work-item update --iteration` | `Project\Parent\Child` (no "Iteration" segment, no leading `\`) | `devops-team\azure-quota-automation\epic-1-slug` |

### Setup Commands for a New Repo

```bash
# 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](https://learn.microsoft.com/en-us/rest/api/azure/devops/?view=azure-devops-rest-7.2)
- [WIQL Syntax Reference](https://learn.microsoft.com/en-us/azure/devops/boards/queries/wiql-syntax)
- [Authentication Guide](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/authentication-guidance)
- [Rate Limits](https://learn.microsoft.com/en-us/azure/devops/integrate/concepts/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.