azure-devops-skill

Name: azure-devops-skill
Author: julianobarbosa

github.com/julianobarbosa云与 DevOps1461 次安装2 天前更新

代码仓库

关于 azure-devops-skill

azure-devops-skill 是面向使用 Azure DevOps REST API v7.2 的开发者和团队的参考技能。它介绍工作项、管道、代码库、测试、Wiki 和搜索的 API 操作、认证、查询及 MCP 工具名称。

主要功能

01工作项查询与更新
02管道和构建操作
03代码库、分支与拉取请求流程
04测试计划与用例管理
05Wiki 和代码搜索操作
06认证与 API 指引

适用场景

01查找或更新分配的工作项
02触发管道并查看构建日志
03检查代码库、分支或拉取请求
04管理测试用例并搜索项目内容

MCP 相关

指南列出了工作项、管道、代码库、测试计划、Wiki 和搜索等 Azure DevOps MCP 工具名称，可作为调用这些工具的参考。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/julianobarbosa/claude-code-skills --skill azure-devops-skill

安装后在 Claude Code 中输入/azure-devops-skill确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/

git-repos-reference.md

pipelines-reference.md

test-plans-reference.md

wiki-search-reference.md

work-items-reference.md

scripts/

ado-cli.sh

pipelines.py

pull-requests.py

work-items.py

详细介绍

Azure DevOps REST API 技能

全面介绍 Azure DevOps REST API v7.2 的各项操作，包括工作项、流水线、仓库、测试计划、Wiki 和搜索功能。

快速参考

区域	基础 URL	MCP 工具前缀
核心	`dev.azure.com/{org}/_apis/`	`mcp__ado__core_*`
工作项	`dev.azure.com/{org}/{project}/_apis/wit/`	`mcp__ado__wit_*`
流水线	`dev.azure.com/{org}/{project}/_apis/pipelines/`	`mcp__ado__pipelines_*`
Git/仓库	`dev.azure.com/{org}/{project}/_apis/git/`	`mcp__ado__repo_*`
测试计划	`dev.azure.com/{org}/{project}/_apis/testplan/`	`mcp__ado__testplan_*`
Wiki	`dev.azure.com/{org}/{project}/_apis/wiki/`	`mcp__ado__wiki_*`
搜索	`almsearch.dev.azure.com/{org}/_apis/search/`	`mcp__ado__search_*`

身份验证方法

个人访问令牌（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 作用域

作用域	访问级别
`vso.work`	读取工作项
`vso.work_write`	创建/更新工作项
`vso.code`	读取源代码
`vso.code_write`	创建分支、PR
`vso.build_execute`	运行流水线
`vso.test`	读取测试计划
`vso.wiki`	读取 Wiki

API 版本控制

格式：{major}.{minor}[-{stage}[.{resource-version}]]

当前版本：7.2-preview.3
示例：api-version=7.2-preview.3

1. 工作项操作

可用的 MCP 工具

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 查询语法

基本结构

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

常用宏

宏	说明
`@Me`	当前用户
`@project`	当前项目
`@Today`	今天的日期
`@Today - N`	N 天前
`@CurrentIteration`	当前迭代
`@StartOfMonth`	月初

查询示例

-- 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 操作

[
  {"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}"
  }}
]

链接类型参考

类型	关系名称
父项	`System.LinkTypes.Hierarchy-Reverse`
子项	`System.LinkTypes.Hierarchy-Forward`
相关	`System.LinkTypes.Related`
前置项	`System.LinkTypes.Dependency-Reverse`
后续项	`System.LinkTypes.Dependency-Forward`

2. 流水线操作

可用的 MCP 工具

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

流水线触发示例

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

构建状态值

状态	说明
`none`	尚未开始
`inProgress`	正在运行
`completed`	已完成
`cancelling`	正在取消
`postponed`	已延迟
`notStarted`	已排队

构建结果值

结果	说明
`succeeded`	所有任务均已通过
`partiallySucceeded`	部分任务失败
`failed`	构建失败
`canceled`	用户已取消

3. 仓库操作

可用的 MCP 工具

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 状态值

状态	说明
`active`	等待审查
`abandoned`	已关闭，未合并
`completed`	已合并

合并策略

策略	说明
`noFastForward`	合并提交（默认）
`squash`	压缩提交
`rebase`	变基并快进
`rebaseMerge`	变基并创建合并提交

4. 测试计划操作

可用的 MCP 工具

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

测试用例步骤格式

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

测试套件类型

类型	说明
`staticTestSuite`	手动层级结构
`dynamicTestSuite`	基于查询
`requirementTestSuite`	与需求关联

测试结果值

结果	说明
`Passed`	测试通过
`Failed`	测试失败
`Blocked`	无法执行
`NotExecuted`	未运行
`Inconclusive`	无明确结果

5. Wiki 操作

可用的 MCP 工具

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 类型

类型	说明
`projectWiki`	项目范围的 Wiki
`codeWiki`	由 Git 提供支持的 Wiki

页面路径格式

根目录：/
子页面：/Parent/Child
空格：/My%20Page

6. 搜索操作

可用的 MCP 工具

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

代码搜索筛选条件

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

工作项搜索筛选条件

{
  "System.TeamProject": ["project-name"],
  "System.WorkItemType": ["Bug", "Task"],
  "System.State": ["Active", "New"],
  "System.AssignedTo": ["[email protected]"]
}

7. 核心操作

可用的 MCP 工具

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. 高级安全操作

可用的 MCP 工具

mcp__ado__advsec_get_alerts            - Get security alerts
mcp__ado__advsec_get_alert_details     - Get alert details

警报类型

类型	说明
`Dependency`	易受攻击的依赖项
`Secret`	暴露的机密信息
`Code`	代码漏洞

速率限制

TSTU（吞吐量单位）限制

匿名：每分钟 200 TSTU
已认证：每分钟 1200 TSTU

响应标头

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

处理速率限制

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")

错误处理

HTTP 状态码

代码	含义
200	成功
201	已创建
204	无内容（DELETE）
400	错误请求
401	未授权
403	禁止访问
404	未找到
409	冲突（版本）
429	请求过多
500	服务器错误

错误响应格式

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

常用字段参考

系统字段

字段	引用名称
ID	`System.Id`
标题	`System.Title`
状态	`System.State`
分配给	`System.AssignedTo`
区域路径	`System.AreaPath`
迭代路径	`System.IterationPath`
工作项类型	`System.WorkItemType`
创建日期	`System.CreatedDate`
更改日期	`System.ChangedDate`
标签	`System.Tags`
描述	`System.Description`

排期字段

字段	引用名称
故事点数	`Microsoft.VSTS.Scheduling.Effort`
剩余工作量	`Microsoft.VSTS.Scheduling.RemainingWork`
原始估算	`Microsoft.VSTS.Scheduling.OriginalEstimate`
已完成工作量	`Microsoft.VSTS.Scheduling.CompletedWork`

多仓库工作项隔离

当一个 Azure DevOps 项目包含多个仓库时，使用 区域路径 进行主要隔离，并使用分层迭代路径跟踪特定仓库的冲刺/史诗。

目标结构

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)

路径格式差异（重要）

Azure DevOps 对迭代使用两种不同的路径格式：

操作	格式	示例
`az boards iteration project create --path`	`\Project\Iteration\Parent`（必须包含字面量 "Iteration" 段）	`\devops-team\Iteration\azure-quota-automation`
`az boards work-item update --iteration`	`Project\Parent\Child`（不含 "Iteration" 段，也没有前导 `\`）	`devops-team\azure-quota-automation\epic-1-slug`

新仓库的设置命令

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

移动迭代（不支持原生移动）

Azure DevOps CLI 没有用于移动迭代的 move 命令。要重新组织结构：

确认没有分配工作项：az boards query --wiql "... WHERE [System.IterationPath] = '...'"
删除：az boards iteration project delete --path "\project\Iteration\old-path" --yes
在新父级下重新创建：az boards iteration project create --name "name" --path "\project\Iteration\new-parent"
使用新的迭代 ID 更新状态文件

常见错误：TF401347

TF401347: The iteration path does not exist — 由路径格式错误导致。请检查：

工作项上的 --iteration 使用 Project\Parent\Child（不含 "Iteration" 段）
创建迭代时的 --path 使用 \Project\Iteration\Parent（包含 "Iteration" 段）

最佳实践

1. 使用批量操作

使用 mcp__ado__wit_get_work_items_batch_by_ids，而不是多次单项调用
每个批量请求最多包含 200 个项目

2. 尽量减少字段选择

仅请求所需字段：fields=System.Id,System.Title,System.State
减少响应大小和 API 负载

3. 处理分页

对较大的结果集使用 $top 和 $skip
如果提供了延续令牌，请遵循它们

4. 版本控制

在 JSON Patch 中使用 test 操作实现乐观并发控制
更新前始终检查 rev 字段

5. 错误恢复

针对速率限制实现指数退避
记录响应标头中的关联 ID

参考资料

支持 Markdown

登录后评论

基本信息

作者: julianobarbosa
仓库: julianobarbosa/claude-code-skills
分类: 云与 DevOps
安装次数: 61
GitHub Stars: 14

报告问题