Back to Details

github-projects

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

GitHub Projects CLI

GitHub Projects CLI

GitHub Projects (v2) management via 
gh project
commands. Requires the 
project
scope which can be added with 
gh auth refresh -s project
.
通过
gh project
命令管理GitHub Projects (v2)。需要
project
权限范围，可通过
gh auth refresh -s project
添加。

Prerequisites

前提条件

Verify authentication includes project scope:
bash
gh auth status  # Check current scopes
gh auth refresh -s project  # Add project scope if missing
验证身份验证是否包含project权限范围：
bash
gh auth status  # 检查当前权限范围
gh auth refresh -s project  # 若缺失则添加project权限范围

Quick Reference

快速参考

List & View Projects

列出与查看项目

bash
undefined
bash
undefined

List your projects

列出你的项目

gh project list
gh project list

List org projects (including closed)

列出组织项目（包括已关闭的）

gh project list --owner ORG_NAME --closed
gh project list --owner ORG_NAME --closed

View project details

查看项目详情

gh project view PROJECT_NUM --owner OWNER
gh project view PROJECT_NUM --owner OWNER

Open in browser

在浏览器中打开

gh project view PROJECT_NUM --owner OWNER --web
gh project view PROJECT_NUM --owner OWNER --web

JSON output with jq filtering

结合jq过滤的JSON输出

gh project list --format json | jq '.projects[] | {number, title}'
undefined
gh project list --format json | jq '.projects[] | {number, title}'
undefined

Create & Edit Projects

创建与编辑项目

bash
undefined
bash
undefined

Create project

创建项目

gh project create --owner OWNER --title "Project Title"
gh project create --owner OWNER --title "Project Title"

Edit project

编辑项目

gh project edit PROJECT_NUM --owner OWNER --title "New Title" gh project edit PROJECT_NUM --owner OWNER --description "New description" gh project edit PROJECT_NUM --owner OWNER --visibility PUBLIC
gh project edit PROJECT_NUM --owner OWNER --title "New Title" gh project edit PROJECT_NUM --owner OWNER --description "New description" gh project edit PROJECT_NUM --owner OWNER --visibility PUBLIC

Close/reopen project

关闭/重新打开项目

gh project close PROJECT_NUM --owner OWNER gh project close PROJECT_NUM --owner OWNER --undo # Reopen
undefined
gh project close PROJECT_NUM --owner OWNER gh project close PROJECT_NUM --owner OWNER --undo # 重新打开
undefined

Link Projects to Repos

关联项目与仓库

bash
undefined
bash
undefined

Link to repo

关联到仓库

gh project link PROJECT_NUM --owner OWNER --repo REPO_NAME
gh project link PROJECT_NUM --owner OWNER --repo REPO_NAME

Link to team

关联到团队

gh project link PROJECT_NUM --owner ORG --team TEAM_NAME
gh project link PROJECT_NUM --owner ORG --team TEAM_NAME

Unlink

取消关联

gh project unlink PROJECT_NUM --owner OWNER --repo REPO_NAME
undefined
gh project unlink PROJECT_NUM --owner OWNER --repo REPO_NAME
undefined

Project Items

项目事项

Add Existing Issues/PRs

添加现有议题/拉取请求

bash
undefined
bash
undefined

Add issue to project

向项目添加议题

gh project item-add PROJECT_NUM --owner OWNER --url https://github.com/OWNER/REPO/issues/123
gh project item-add PROJECT_NUM --owner OWNER --url https://github.com/OWNER/REPO/issues/123

Add PR to project

向项目添加拉取请求

gh project item-add PROJECT_NUM --owner OWNER --url https://github.com/OWNER/REPO/pull/456
undefined
gh project item-add PROJECT_NUM --owner OWNER --url https://github.com/OWNER/REPO/pull/456
undefined

Create Draft Items

创建草稿事项

bash
gh project item-create PROJECT_NUM --owner OWNER --title "Draft item" --body "Description"
bash
gh project item-create PROJECT_NUM --owner OWNER --title "Draft item" --body "Description"

List Items

列出事项

bash
undefined
bash
undefined

List items (default 30)

列出事项（默认30条）

gh project item-list PROJECT_NUM --owner OWNER
gh project item-list PROJECT_NUM --owner OWNER

List more items

列出更多事项

gh project item-list PROJECT_NUM --owner OWNER --limit 100
gh project item-list PROJECT_NUM --owner OWNER --limit 100

JSON output

JSON输出

gh project item-list PROJECT_NUM --owner OWNER --format json
undefined
gh project item-list PROJECT_NUM --owner OWNER --format json
undefined

Edit Items

编辑事项

Items are edited by their ID (obtained from 
item-list --format json
).
bash
undefined
事项需通过其ID（从
item-list --format json
获取）进行编辑。
bash
undefined

Edit draft issue title/body

编辑草稿议题的标题/正文

gh project item-edit --id ITEM_ID --title "New Title" --body "New body"
gh project item-edit --id ITEM_ID --title "New Title" --body "New body"

Update field value (requires field-id and project-id)

更新字段值（需要field-id和project-id）

gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --text "value" gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --number 42 gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --date "2024-12-31" gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --single-select-option-id OPTION_ID gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --iteration-id ITER_ID
gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --text "value" gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --number 42 gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --date "2024-12-31" gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --single-select-option-id OPTION_ID gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --iteration-id ITER_ID

Clear field value

清空字段值

gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --clear
undefined
gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --clear
undefined

Archive/Delete Items

归档/删除事项

bash
gh project item-archive PROJECT_NUM --owner OWNER --id ITEM_ID
gh project item-delete PROJECT_NUM --owner OWNER --id ITEM_ID
bash
gh project item-archive PROJECT_NUM --owner OWNER --id ITEM_ID
gh project item-delete PROJECT_NUM --owner OWNER --id ITEM_ID

Project Fields

项目字段

List Fields

列出字段

bash
gh project field-list PROJECT_NUM --owner OWNER
gh project field-list PROJECT_NUM --owner OWNER --format json
bash
gh project field-list PROJECT_NUM --owner OWNER
gh project field-list PROJECT_NUM --owner OWNER --format json

Create Fields

创建字段

bash
undefined
bash
undefined

Text field

文本字段

gh project field-create PROJECT_NUM --owner OWNER --name "Notes" --data-type TEXT
gh project field-create PROJECT_NUM --owner OWNER --name "Notes" --data-type TEXT

Number field

数字字段

gh project field-create PROJECT_NUM --owner OWNER --name "Points" --data-type NUMBER
gh project field-create PROJECT_NUM --owner OWNER --name "Points" --data-type NUMBER

Date field

日期字段

gh project field-create PROJECT_NUM --owner OWNER --name "Due Date" --data-type DATE
gh project field-create PROJECT_NUM --owner OWNER --name "Due Date" --data-type DATE

Single select with options

带选项的单选字段

gh project field-create PROJECT_NUM --owner OWNER --name "Priority"
--data-type SINGLE_SELECT
--single-select-options "Low,Medium,High,Critical"
undefined
gh project field-create PROJECT_NUM --owner OWNER --name "Priority"
--data-type SINGLE_SELECT
--single-select-options "Low,Medium,High,Critical"
undefined

Delete Fields

删除字段

bash
gh project field-delete --id FIELD_ID
bash
gh project field-delete --id FIELD_ID

Common Workflows

常见工作流

Add Issue and Set Status

添加议题并设置状态

bash
undefined
bash
undefined

1. Add issue to project

1. 向项目添加议题

gh project item-add 1 --owner "@me" --url https://github.com/owner/repo/issues/123
gh project item-add 1 --owner "@me" --url https://github.com/owner/repo/issues/123

2. Get item ID and field IDs

2. 获取事项ID和字段ID

gh project item-list 1 --owner "@me" --format json | jq '.items[-1]' gh project field-list 1 --owner "@me" --format json
gh project item-list 1 --owner "@me" --format json | jq '.items[-1]' gh project field-list 1 --owner "@me" --format json

3. Update status field

3. 更新状态字段

gh project item-edit --id ITEM_ID --project-id PROJECT_ID
--field-id STATUS_FIELD_ID --single-select-option-id OPTION_ID
undefined
gh project item-edit --id ITEM_ID --project-id PROJECT_ID
--field-id STATUS_FIELD_ID --single-select-option-id OPTION_ID
undefined

Bulk Add Issues

批量添加议题

bash
undefined
bash
undefined

Add all open issues from a repo

添加仓库中所有开放的议题

gh issue list --repo owner/repo --state open --json url -q '.[].url' |
xargs -I {} gh project item-add 1 --owner "@me" --url {}
undefined
gh issue list --repo owner/repo --state open --json url -q '.[].url' |
xargs -I {} gh project item-add 1 --owner "@me" --url {}
undefined

JSON Output & jq Patterns

JSON输出与jq模式

bash
undefined
bash
undefined

Get project IDs

获取项目ID

gh project list --format json | jq '.projects[] | {number, id, title}'
gh project list --format json | jq '.projects[] | {number, id, title}'

Get field IDs and options

获取字段ID和选项

gh project field-list 1 --owner "@me" --format json | jq '.fields[] | {id, name, options}'
gh project field-list 1 --owner "@me" --format json | jq '.fields[] | {id, name, options}'

Get item IDs with field values

获取带有字段值的事项ID

gh project item-list 1 --owner "@me" --format json | jq '.items[] | {id, title, fieldValues}'
gh project item-list 1 --owner "@me" --format json | jq '.items[] | {id, title, fieldValues}'

Filter items by status

按状态过滤事项

gh project item-list 1 --owner "@me" --format json |
jq '.items[] | select(.status == "In Progress")'
undefined
gh project item-list 1 --owner "@me" --format json |
jq '.items[] | select(.status == "In Progress")'
undefined

Reference Files

参考文件

  • items.md: Item management, editing field values, bulk operations
  • fields.md: Field types, creating custom fields, option management
  • items.md: 事项管理、编辑字段值、批量操作
  • fields.md: 字段类型、创建自定义字段、选项管理

Command Summary

命令汇总

CommandPurpose
project list
List projects
project view
View project details
project create
Create new project
project edit
Modify project settings
project close
Close/reopen project
project link/unlink
Connect to repo/team
project item-add
Add existing issue/PR
project item-create
Create draft item
project item-list
List project items
project item-edit
Update item fields
project item-archive
Archive item
project item-delete
Remove item
project field-list
List project fields
project field-create
Add custom field
project field-delete
Remove field
命令用途
project list
列出项目
project view
查看项目详情
project create
创建新项目
project edit
修改项目设置
project close
关闭/重新打开项目
project link/unlink
关联到仓库/团队
project item-add
添加现有议题/拉取请求
project item-create
创建草稿事项
project item-list
列出项目事项
project item-edit
更新事项字段
project item-archive
归档事项
project item-delete
删除事项
project field-list
列出项目字段
project field-create
添加自定义字段
project field-delete
删除字段