GitHub Projects v2 技能

认证前提条件

gh auth status                  # 验证权限范围
gh auth refresh -s project      # 若缺少 project 权限，则添加该权限

ID 注意事项：大多数 gh project 命令接受项目 编号（例如 1）并配合 --owner 参数使用。
item-edit 是例外 —— 它要求使用 --project-id 参数，并传入 GraphQL 节点 ID（例如 PVT_xxx）。
可通过以下命令获取：gh project list --owner --format json | jq '.projects[] | select(.number==1) | .id'

1. 列出待办事项列表（Backlog）中的条目

# 列出所有条目（默认 30 条，使用 --limit 提高数量上限）
gh project item-list  --owner  --limit 100

# 按状态筛选 —— 仅显示 Backlog 中的条目
gh project item-list  --owner  --query "status:Backlog"

# 筛选分配给你的开放 Issue
gh project item-list  --owner  --query "assignee:@me is:issue is:open"

# 输出 JSON 格式，便于脚本处理
gh project item-list  --owner  --format json 
  | jq '.items[] | {id, title, status}'

2. 设置条目的字段值（如状态、迭代周期、优先级等）

item-edit 命令需要提供项目节点 ID 和条目节点 ID —— 这两个 ID 均可通过 item-list --format json 获取。

# 获取项目节点 ID
PROJECT_ID=$(gh project list --owner  --format json 
  | jq -r '.projects[] | select(.number==) | .id')

# 获取条目 ID 及当前字段值
gh project item-list  --owner  --format json | jq '.items[]'

# 获取字段 ID 和选项 ID（单选字段和迭代字段必需）
gh project field-list  --owner  --format json | jq '.fields[]'

# 设置单选字段（例如 Status、Priority）
gh project item-edit --project-id $PROJECT_ID --id  
  --field-id  --single-select-option-id 

# 设置迭代字段（例如 Sprint）
gh project item-edit --project-id $PROJECT_ID --id  
  --field-id  --iteration-id 

# 设置日期字段
gh project item-edit --project-id $PROJECT_ID --id  
  --field-id  --date "2025-12-31"

# 设置数字字段（例如 Story Points）
gh project item-edit --project-id $PROJECT_ID --id  
  --field-id  --number 5

# 清空任意字段的值
gh project item-edit --project-id $PROJECT_ID --id  
  --field-id  --clear

3. 为 Issue 添加评论

# 添加评论（使用 Issue 编号，而非 Project 条目 ID）
gh issue comment  --repo / --body "Your comment here"

# 从文件读取评论内容
gh issue comment  --repo / --body-file comment.md

4. 创建 Issue 并将其加入项目

# 在仓库中创建 Issue
ISSUE_URL=$(gh issue create 
  --repo / 
  --title "Fix login timeout" 
  --body "Users are being logged out after 5 minutes." 
  --assignee "@me" 
  --label "bug")

# 将新创建的 Issue 加入项目
gh project item-add  --owner  --url "$ISSUE_URL"

5. 创建子 Issue（Sub-Issue）

原生 gh issue 命令暂不支持子 Issue。请使用 gh-sub-issue 扩展：

# 一次性安装扩展
gh extension install yahsan2/gh-sub-issue

# 创建一个新 Issue，并将其作为指定父 Issue 的子 Issue
gh sub-issue create --parent  
  --repo / 
  --title "Implement login endpoint" 
  --body "POST /api/login"

# 将已有 Issue 关联为某父 Issue 的子 Issue
gh sub-issue add   --repo /

# 列出某父 Issue 下的所有子 Issue
gh sub-issue list  --repo /

若该扩展不可用，可回退至 GraphQL 方式：

gh api graphql -f query='
  mutation($parentId: ID!, $childId: ID!) {
    addSubIssue(input: { issueId: $parentId, subIssueId: $childId }) {
      issue { number title }
      subIssue { number title }
    }
  }
' -F parentId= -F childId=