project-init

project-init

新建 GitHub Project v2，设置标准字段并关联到仓库。还会指导用户配置内置工作流（自动更改状态、自动添加和自动归档）。

前提条件

• 已安装并完成身份验证的 gh CLI
• 已授予 project 作用域（使用 gh auth status 确认）

流程

Step 1：确认项目信息

向用户确认以下信息：

• 项目标题
• 所有者（用户或 Organization）
• 可见性（PUBLIC / PRIVATE）
• 描述（可选）

如果未指定所有者，则自动检测：

gh repo view --json owner -q '.owner.login'

Step 2：创建项目

gh project create \
  --owner <owner> \
  --title "<タイトル>" \
  --format json

从输出中获取项目编号。

Step 3：关联仓库

gh project link <number> --owner <owner>

Step 4：创建标准字段

依次创建以下字段：

# Status（デフォルトで存在する場合はスキップ）
gh project field-create <number> \
  --owner <owner> \
  --name "Status" \
  --data-type "SINGLE_SELECT" \
  --single-select-options "Todo,In Progress,In Review,Done"

# Priority
gh project field-create <number> \
  --owner <owner> \
  --name "Priority" \
  --data-type "SINGLE_SELECT" \
  --single-select-options "High,Medium,Low"

# Size
gh project field-create <number> \
  --owner <owner> \
  --name "Size" \
  --data-type "SINGLE_SELECT" \
  --single-select-options "XS,S,M,L,XL"

注意： GitHub 可能会自动创建 Status 字段。如果出现错误，请直接使用已有字段。

Step 5：设置项目描述

gh project edit <number> \
  --owner <owner> \
  --description "<説明文>" \
  --visibility <PUBLIC|PRIVATE>

Step 6：配置内置工作流

GitHub Projects v2 提供无需编写代码的内置工作流。在项目设置页面中指导用户启用以下工作流。

设置 URL：https://github.com/orgs/<owner>/projects/<number>/workflows （个人项目对应的 URL：https://github.com/users/<owner>/projects/<number>/workflows）

推荐的内置工作流

工作流	行为	默认状态	推荐操作
Item closed	Issue/PR 关闭后，Status → Done	已启用	保持不变
Pull request merged	PR 合并后，Status → Done	已启用	保持不变
Item reopened	Issue 重新打开后，Status → Todo	已禁用	建议启用
Item added to project	添加项目条目时，Status → Todo	已禁用	建议启用
Auto-add to project	自动添加符合筛选条件的 Issue/PR	已禁用	建议启用
Auto-archive items	在 Done 状态经过 N 天后自动归档	已禁用	可选
Auto-close issue	在看板上将状态设为 Done 时自动关闭 Issue	已禁用	强烈建议启用

重要： 如果未启用 Auto-close，即使在看板上将 Status 设为 Done，Issue 也不会自动关闭。这是实现双向同步的必要条件。

Auto-add 筛选条件示例

is:issue,pr is:open repo:<owner>/<repo>

按标签筛选时：

is:issue,pr is:open label:sprint-1 repo:<owner>/<repo>

Step 7：介绍持续自动同步

如果需要内置工作流无法涵盖的高级同步，例如关联 PR 生命周期（opened→In Progress、review_requested→In Review），请告知用户可以使用 project-sync-issues 技能生成 GitHub Actions 工作流。

Step 8：报告创建结果

显示以下信息：

• 项目 URL
• 项目编号
• 已创建的字段列表
• 已关联的仓库
• 内置工作流设置 URL
• 推荐设置检查清单

注意事项

• 可根据用户的要求自定义 Status 选项值
• 创建字段时若发生错误（例如字段已存在），则跳过并继续
• Organization 项目需要相应权限
• 无法通过 CLI/API 配置内置工作流，因此必须在 Web UI 中设置
• 需要网络连接（主要通过 API。请参阅下文的“在 sandbox 环境中运行”一节）

验证

完成 Step 8 后，使用以下命令确认创建结果：

gh project view <number> --owner <owner> --format json
gh project field-list <number> --owner <owner> --format json

如果输出中包含项目 URL 和字段列表（Status / Priority / Size），则表示已完成。

在 sandbox 环境中运行

此技能必须通过网络执行 GitHub 操作（创建 Project v2 并配置字段）。运行相关命令时，应逐条命令禁用 sandbox。在无法解除网络限制的环境中，无法运行此技能。