azure-devops

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Azure DevOps with orbit CLI

Manage Azure DevOps (VSTS) projects, work items, and saved queries from the command line. Supports both modern (

dev.azure.com

) and legacy (

*.visualstudio.com

) instances using PAT-based basic auth.

从命令行管理Azure DevOps（VSTS）项目、工作项和已保存查询。支持使用基于PAT的基本认证连接现代（

dev.azure.com

）和旧版（

*.visualstudio.com

）实例。

Prerequisites

前提条件

orbit

CLI installed — if

which orbit

fails, install with:

macOS/Linux (Homebrew):
```
brew install jorgemuza/tap/orbit
```

macOS/Linux (script):

curl -sSfL https://raw.githubusercontent.com/jorgemuza/orbit/main/install.sh | sh

A profile with an
```
azure-devops
```
service configured in
```
~/.config/orbit/config.yaml
```
A Personal Access Token (PAT) with appropriate scopes (Work Items Read/Write, Project Read)
Auth method:
```
basic
```
with your email as username and the PAT as password

已安装

orbit

CLI —— 若执行

which orbit

无结果，可通过以下方式安装：

macOS/Linux（Homebrew）：
```
brew install jorgemuza/tap/orbit
```

macOS/Linux（脚本）：

curl -sSfL https://raw.githubusercontent.com/jorgemuza/orbit/main/install.sh | sh

在
```
~/.config/orbit/config.yaml
```
中配置包含
```
azure-devops
```
服务的配置文件
具备适当权限范围的个人访问令牌（PAT）（工作项读写、项目读取）
认证方式：
```
basic
```
，用户名填写邮箱，密码填写PAT

Configuration

配置示例

yaml

profiles:
  myprofile:
    services:
      - name: azure-devops
        type: azure-devops
        base_url: https://myorg.visualstudio.com   # or https://dev.azure.com/myorg
        proxy: none                                 # bypass profile-level proxy if needed
        auth:
          method: basic
          username: me@company.com
          password: "MY_PAT_HERE"                   # supports op:// references
        options:
          default_project: MyProject                # optional — avoids --project on every call

yaml

profiles:
  myprofile:
    services:
      - name: azure-devops
        type: azure-devops
        base_url: https://myorg.visualstudio.com   # 或 https://dev.azure.com/myorg
        proxy: none                                 # 如有需要，绕过配置文件级代理
        auth:
          method: basic
          username: me@company.com
          password: "MY_PAT_HERE"                   # 支持op://引用
        options:
          default_project: MyProject                # 可选 —— 避免每次调用都添加--project参数

Quick Reference

快速参考

All commands follow the pattern:

orbit -p <profile> ado <command> [flags]

All commands support

-o json

and

-o yaml

for structured output.

所有命令遵循以下格式：

orbit -p <profile> ado <command> [flags]

所有命令均支持

-o json

和

-o yaml

参数以输出结构化数据。

Command Groups

命令组

Group	Alias	Description
`project`		List projects in the organization
`work-item`	`wi`	View, list, create, update work items
`query`		Run and list saved queries
`version`		Verify connectivity and show authenticated user

命令组	别名	描述
`project`		列出组织内的项目
`work-item`	`wi`	查看、列出、创建、更新工作项
`query`		运行和列出已保存的查询
`version`		验证连接状态并显示已认证用户

Core Workflows

核心工作流

Verifying Connection

验证连接

bash

orbit -p myprofile ado version

bash

orbit -p myprofile ado version

Listing Projects

列出项目

bash

orbit -p myprofile ado project list
orbit -p myprofile ado project list -o json

bash

orbit -p myprofile ado project list
orbit -p myprofile ado project list -o json

Work Items

工作项操作

bash

undefined

bash

undefined

View a single work item

查看单个工作项

orbit -p myprofile ado wi view 12345 orbit -p myprofile ado wi view 12345 -o json

List work items with filters (builds WIQL automatically)

带筛选条件列出工作项（自动生成WIQL）

orbit -p myprofile ado wi list --project Fusion --type Bug --state New orbit -p myprofile ado wi list --project Fusion --type "User Story" --state Active orbit -p myprofile ado wi list --project Fusion --assigned-to "me@company.com" orbit -p myprofile ado wi list --project Fusion --max-results 100

Raw WIQL query

原生WIQL查询

orbit -p myprofile ado wi list --project Fusion --wiql "SELECT [System.Id], [System.Title] FROM WorkItems WHERE [System.State] = 'Active' ORDER BY [System.CreatedDate] DESC"

Create a work item

创建工作项

orbit -p myprofile ado wi create --project Fusion --type Bug
--field "System.Title=Login page broken"
--field "System.Description=Steps to reproduce..."

Update a work item (any field)

更新工作项（支持任意字段）

orbit -p myprofile ado wi update 12345 --field "System.State=Active" orbit -p myprofile ado wi update 12345 --field "System.AssignedTo=someone@company.com" orbit -p myprofile ado wi update 12345
--field "System.State=Resolved"
--field "Microsoft.VSTS.Common.ResolvedReason=Fixed"

undefined

undefined

Saved Queries

已保存查询操作

bash

undefined

bash

undefined

Run a saved query by its UUID

通过UUID运行已保存的查询

orbit -p myprofile ado query run a670954b-e739-47ca-a09a-acc10f623123 --project Fusion

List saved queries and folders

列出已保存的查询和文件夹

orbit -p myprofile ado query list --project Fusion orbit -p myprofile ado query list --project Fusion --depth 3

undefined

orbit -p myprofile ado query list --project Fusion orbit -p myprofile ado query list --project Fusion --depth 3

undefined

Common Field Names

常用字段名称

Azure DevOps uses fully-qualified field names. The most common:

Field	Description
`System.Title`	Work item title
`System.State`	State (New, Active, Resolved, Closed)
`System.WorkItemType`	Type (Bug, Task, User Story, Epic, Feature)
`System.AssignedTo`	Assigned user (email or display name)
`System.Description`	HTML description
`System.AreaPath`	Area path (e.g. `Fusion\Backend` )
`System.IterationPath`	Iteration/sprint path
`System.Tags`	Semicolon-separated tags
`Microsoft.VSTS.Common.Priority`	Priority (1-4)
`Microsoft.VSTS.Common.Severity`	Severity (1-4)
`Microsoft.VSTS.Common.ResolvedReason`	Why it was resolved

Azure DevOps使用全限定字段名称，最常用的字段如下：

字段	描述
`System.Title`	工作项标题
`System.State`	状态（新建、活跃、已解决、已关闭）
`System.WorkItemType`	类型（缺陷、任务、用户故事、史诗、特性）
`System.AssignedTo`	分配用户（邮箱或显示名称）
`System.Description`	HTML描述
`System.AreaPath`	区域路径（例如 `Fusion\Backend` ）
`System.IterationPath`	迭代/冲刺路径
`System.Tags`	分号分隔的标签
`Microsoft.VSTS.Common.Priority`	优先级（1-4）
`Microsoft.VSTS.Common.Severity`	严重程度（1-4）
`Microsoft.VSTS.Common.ResolvedReason`	解决原因

WIQL (Work Item Query Language)

WIQL（工作项查询语言）

WIQL is Microsoft's query language for work items, similar to SQL:

sql

SELECT [System.Id], [System.Title], [System.State]
FROM WorkItems
WHERE [System.TeamProject] = 'Fusion'
  AND [System.WorkItemType] = 'Bug'
  AND [System.State] <> 'Closed'
  AND [System.AssignedTo] = @Me
ORDER BY [System.CreatedDate] DESC

Key differences from Jira JQL:

Field names use brackets:
```
[System.Title]
```
String values use single quotes:
```
'Active'
```
Current user:
```
@Me
```
Not equal:
```
<>
```
Table:
```
FROM WorkItems
```
(always)

WIQL是微软针对工作项的查询语言，类似SQL：

sql

SELECT [System.Id], [System.Title], [System.State]
FROM WorkItems
WHERE [System.TeamProject] = 'Fusion'
  AND [System.WorkItemType] = 'Bug'
  AND [System.State] <> 'Closed'
  AND [System.AssignedTo] = @Me
ORDER BY [System.CreatedDate] DESC

与Jira JQL的主要区别：

字段名称使用方括号：
```
[System.Title]
```
字符串值使用单引号：
```
'Active'
```
当前用户：
```
@Me
```
不等于：
```
<>
```
固定表名：
```
FROM WorkItems
```

Important Notes

重要说明

PAT auth: Azure DevOps uses the PAT as the password in basic auth. The username is your email.
API version: All requests use
```
api-version=7.1
```
(latest stable).
JSON Patch: Create/update use
```
application/json-patch+json
```
format internally — the CLI handles this; just pass
```
--field Key=Value
```
.
default_project: Set in
```
options.default_project
```
to avoid
```
--project
```
on every command.
Proxy bypass: If your profile has a proxy for VPN services but Azure DevOps is on the public internet, set
```
proxy: none
```
on the service to bypass.
1Password integration: PAT in config can use
```
op://vault/item/field
```
and is resolved at runtime via
```
orbit auth
```
.

PAT认证：Azure DevOps在基本认证中使用PAT作为密码，用户名填写你的邮箱。
API版本：所有请求使用
```
api-version=7.1
```
（最新稳定版）。
JSON Patch：创建/更新操作内部使用
```
application/json-patch+json
```
格式——CLI会自动处理，只需传入
```
--field Key=Value
```
参数即可。
default_project：在
```
options.default_project
```
中设置后，可避免每次命令都添加
```
--project
```
参数。
代理绕过：如果你的配置文件为VPN服务设置了代理，但Azure DevOps处于公网，可在服务配置中设置
```
proxy: none
```
来绕过代理。
1Password集成：配置中的PAT可使用
```
op://vault/item/field
```
格式，运行
```
orbit auth
```
时会在运行时解析。