GitHub Projects进阶指南：从看板到项目底座的高级实践

如果你印象里的 GitHub Projects 还停留在“把 Issues 拖进三列看板”，那这篇文章可能会让你重新评估它。过去一年，我把一个 3 人内部后台项目和一个 12 人客户交付项目全部迁到 GitHub Projects 上，从只会用 Board 视图拖卡片，到把自定义字段、多视图、自动化工作流、时间线图全部跑起来，最大的感受是：看板只是入口，真正提效的是背后那一套数据结构和规则。

这篇文章不讲基础拖拽操作，就说一件事：怎么把 GitHub Projects 从“便利贴墙”变成“项目底座”。我会拿一个真实场景举例——一个 SaaS 后台管理系统的 1.4 版本迭代，带你把高级能力逐项落地，顺便把那些官方文档里不会写的坑也讲清楚。

1. 看板之外的第一道坎：三列视图为什么越用越累

很多人第一次打开 GitHub Projects，看到的就是三个默认列：Todo、In Progress、Done。用起来也顺，拖一拖卡片，看起来团队在协作。但这种用法本质上只是把一张实体白板电子化了，项目里真正需要关心的信息仍然散落在 Issue 描述、评论、聊天记录和某人的脑子里。

1.1 一张典型的需求卡，在三列看板里丢了什么

以我们当时的登录权限改造为例，卡片看起来是“In Progress”，但实际状态非常复杂：接口文档做完了，前端只写了一半，后端还差环境配置，测试用例还没补。三列看板里只能显示“进行中”，具体卡在哪一步，必须点开卡片看评论才能摸到真相。

更麻烦的是跨部门信息。运营想知道这个需求排在哪个版本，测试想知道预计什么时候提测，前端想看接口联调是否就绪。如果看板里没有这些字段，每一次信息同步都要“点开卡片 → 翻评论 → 找人确认”，一天下来大量时间就耗在这种无意义的信息考古里。

这不是 GitHub Projects 的局限，而是你没有用它真正的数据结构。Projects 的底层不是一块看板，而是一张“具有动态视图的数据库表”。每一个 Item（Issue、PR、草稿卡片）都拥有一组字段值，列只是某个字段在视图里的映射。

1.2 先搭一个项目底座：新项目开启时的四步配置

我在新项目里不会先建看板，而是先搭底座。操作路径是：GitHub 仓库或组织页 → Projects → 新建 Project。

这里有一个关键选择：项目归组织所有还是个人所有。只要涉及多人协作，一律建在 Organization 下，这样项目不会被某位成员的离职带走，权限也能统一管。项目类型选 Table 模式，Board 视图等后面再加，因为 Table 能看到所有字段的值，配置起来最直观。

建完后立刻做四件事：

1. 添加数据源：Project 设置里把需要进入项目的仓库全部关联上，后续 Issue 和 PR 会自动涌入，不需要手动贴链接。
2. 加字段：删掉默认的 Status 字段，按自己团队的流程重建，后面我会给出一套可复制的字段组合。
3. 加视图：先保留一个 All Items 的总表，一个按状态分组的看板，一个按迭代分组的时间线，后面再按角色补充。
4. 设权限：管理成员是 Admin，核心研发是 Write，业务方和领导用 Read-only，避免有人顺手改掉结构。

提示：创建完项目后，默认会生成一个链接。把这个链接固定到团队文档的头部，否则三个月后就没人知道入口在哪了。

2. 自定义字段：让每张卡片把背景说清楚

Projects v2 的自定义字段是整个系统的灵魂。很多人做项目管理，喜欢把信息写在 Issue 标题里，比如“【重要】登录页验证码倒计时优化”，等 Issue 一多，搜索、排序、统计全部失效。正确的做法是把流程属性拆成字段，标题只描述“做什么”。

2.1 内置字段与自定义字段，到底怎么选

GitHub Projects 提供的字段类型包括 Single select、Iteration、Number、Date、Text、Milestone、Labels、Reviewers 等。我的选择逻辑很简单：凡是需要“按它筛选、分组、统计”的属性，都应该做成字段；只是偶尔简单补充的，才写成文本。

这里要特别提醒：Milestone 和 Iteration 是两回事。Milestone 是仓库级别的大目标，通常颗粒度比较大；Iteration 是 Projects 里专门的短周期字段，按两周一个迭代走，做冲刺规划比直接用日期字段方便很多。遇到跨仓库需求，Milestone 可能串不起来，而 Iteration 天然跨仓库，因为它是挂在项目上的。

2.2 一套能直接抄的研发流程字段组合

以 SaaS 后台 1.4 版本为例，我最终落地的是这套组合：

• Title：描述用户能感知到的具体能力，不写状态词。
• 状态：需求梳理 → 待排期 → 开发中 → 联调中 → 待验收 → 已上线。
• 版本批次：1.4 迭代A、1.4 迭代B，用 Single select，不用 Date 字段排期，因为日期会变，写着写着就没信心了。
• 优先级：P0 是阻断性问题，P1 是计划内核心功能，P2 是可延后优化项。
• 预估点：用 Fibonacci 数列 1 / 2 / 3 / 5 / 8，不引导大家把时间估得很细，只用来算迭代负载。
• 需求来源：方便月底复盘时快速统计“多少需求来自客户反馈”。

这套字段只加不加超过 6 个。字段越多，成员填写的负担越大，最终一定会出现字段常年为空的情况。我见过 team 一口气加了 16 个字段，结果一周后没人填，最后全部删掉。设计字段的原则是：每个人只填与他工作最相关的那两三列，其余字段让他保持默认值或由自动化维护。

2.3 批量操作和快捷填值，别让字段成为负担

字段太多最大的阻力是录入成本。GitHub Projects 的表格视图里有很多提升录入效率的设计，很多人不知道：

• 按住 Shift 点击多行，可以批量修改某一列的字段值。
• 在 Single select 字段上输入数字 1、2、3，会直接选中第一、第二、第三个选项，按住键盘向下快速操作。
• 用 Ctrl/Command + 方向键可以直接在卡片之间跳转，配合字段快捷键，录入速度接近 Excel。
• 把 GitHub Issue 或 PR 拖入 Projects 后，如果仓库里的事件有对应状态，比如 PR 被 Merge，Workflows 能自动把它移动到“已上线”，这个后文专门说。

我自己的习惯是：每周一早上花 15 分钟把这一周新增的 Issue 拉进项目，批量填好状态、版本、优先级、预估点，然后整个团队在项目里的可见性就建立起来了。

3. 视图切换：同一个项目，七种身份七张脸

GitHub Projects 最有价值的设计之一是 Saved Views。同一个数据库，不同的筛选和分组对应下来就是不同的视图。用好了，一个项目可以同时满足开发、测试、运营、管理层的查看需求，不需要任何人二次整理。

3.1 四种视图布局，各自适合什么场景

Projects 支持的四种布局是 Table、Board、Timeline、Calendar。很多人的误区是只记住 Board，其实另外三种在特定场景里更高效。

• Table：最大的价值是能看到字段全貌，适合批量录入、筛选、排序，是我的默认视图。
• Board：按某个 Single select 字段分组，适合每日站会时快速看状态流转。
• Timeline：按日期或迭代字段做甘特图式排期，适合给管理层讲版本计划。
• Calendar：按日期字段显示，适合给运营和市场看里程碑节点。

这四种布局不是静态的。同一个表视图下，我可以随时切换布局，每一种布局都是对同一个数据集的重新解读。切换不会破坏数据，只会改变展示方式，所以大胆切，不用担心搞乱项目。

3.2 我会保存哪几个视图，按什么逻辑命名

视图命名直接影响团队接受度。我见过有人存了十几个视图，每个都有自己的命名风格，最后没人用，原因不是视图不好，而是大家不知道“今天该看哪个”。我现在的做法是只保留六个视图，按使用场景划分：

这里设置“风险清单”有一个小技巧：用 Date 字段来标记“计划完成日期”，再筛选那些计划完成日期已经落在本周内但状态还没到“已上线”的 Item。这种筛选在 Table 视图里只需要两三个条件，但往往最能暴露项目风险。

3.3 排序和拖拽隐藏的坑：为什么卡片总是不听话

用 Table 视图时，很多新手会在“排序”和“分组”里来回切换，然后发现拖拽卡片并不能自由移动。原因是：一旦视图启用了排序规则，拖拽就会根据字段值重排，而不是让你自由放置。比如按“状态”分组后，你根本不能把一张“开发中”的卡片拖到“待验收”组下，除非你修改它的“状态”字段值。

这个机制看着简单，实际很容易造成困惑。我有一个可复用的建议：把视图分成两类。一类是“录入视图”，不要分组，按创建顺序或编号排序，用来快速改字段；另一类是“协作视图”，按状态分组，用来拖拽。不要试图在同一张视图里同时做这两件事，不然你会被“为什么拖不动”折磨疯。

4. 自动化工作流：让机器替你更新状态

Projects v2 内嵌的 Workflows 是提效的第二个大杀器。它是内置的自动化引擎，可以在特定事件发生时自动修改 Item 的字段、状态，甚至添加评论。设置入口在项目右上角菜单里的 Workflows。

4.1 哪些自动化真正值得做，哪些做了反而添乱

我列过一个自动化需求清单，逐条评估之后，最后真正保留的是下面这几条：

• 当一个 Issue 被关闭时，自动把 Item 状态改为“已上线”。这条最基础，收益也最直接，免去了人工同步。
• 当一个 PR 被合并时，自动把关联的 Item 状态更新为“联调中”或“已上线”。这样开发者不需要从代码仓库跳回项目手动改卡片。
• 当一个新 Issue 首次被加入项目时，自动给它设置默认版本批次“待定”。防止有项被漏填，导致后续筛选统计失效。
• 当一个 Issue 状态变为“待验收”时，自动添加评论 @ 测试负责人。省掉一句人工通知。

不建议的自动化是：根据日期字段自动改状态。比如“提测日期到了就自动进入待验收”。研发进度受太多因素影响，机器直接改状态会造成状态失真，项目看板一旦失去真实性，所有人都会轻视它。

4.2 三条最值得落地的 Workflow 配置参考

第一条：Issue 关闭即完成。触发条件选 Issue 关闭，动作是设置 Status 为“已上线”。注意这个行为会受到分支影响，如果一个 Issue 在开发中途被误关，状态也会被带过去，所以在团队约定里要写明“只有真正上线才允许关闭 Issue”。

第二条：PR 合并联动。触发条件选 Pull Request 合并，动作是把关联 Item 的 Status 设置为“联调中”。这里我觉得比直接设为“已上线”更稳，因为多数团队 PR 合并之后还有上线前置检查和线上验证。

第三条：新增即落位。触发条件选 Item 被加入项目，动作是设置版本批次为“待定”，预防字段遗漏。这条不需要讨论，直接加。

配置 Wrokflows 的界面支持简单的“如果触发条件满足，则执行动作”的规则，语法不复杂。真正要花心思的不是配置本身，而是梳理你自己的流程状态机：哪些状态变化可以由事件驱动，哪些必须由人判断。

4.3 GitHub Actions 与 Projects 的分工：自动周报就从这里开始

Workflows 只能处理项目内部联动，一旦想把数据拉出去，生成周报、同步到外部表格，就要靠 GitHub Actions 加官方 GraphQL API。

我维护了一个 actions 调度任务，每周五下午自动跑一次，逻辑如下：

1. 用 gh api graphql 拉取当前迭代的 Item 列表和字段值。
2. 按“负责人”分组，计算每个人已完成点数和进行中点数的比例。
3. 把统计结果生成一段 Markdown，发到仓库的一个 Issues 里。
4. 周报 Issue 自动添加 label weekly-report，方便查阅。

这段脚本不需要写得很复杂，核心是对 projectV2 节点下的 items 结构做一次遍历，把 Single select 值和 Number 值读出来。GitHub 官方的 GraphQL 文档里有完整示例，我第一次跑通大概花了一个下午，但它之后每周都替我省掉半小时机械劳动。

提醒：GraphQL 读取自定义字段不能直接用字段名，需要先查字段 ID。别在字段名上写死字符串，一定要动态获取，不然字段配置一调整脚本就报废。

5. 权限和协作边界：多人用起来，项目才不算白建

单看个人项目，GitHub Projects 看不出特殊价值。一旦团队大于五个人，权限设计、操作规范、信息同步方式就成了真正决定项目能否长期用下去的关键。

5.1 不同角色的权限怎么分，才能既安全又高效

Projects 的权限设置很清晰：Admin 可以改项目结构，Write 可以编辑所有 Item 字段，Read-only 只能看视图。我为团队定的规则是：

• 技术负责人和项目经理给 Admin 权限，负责维护字段和视图。
• 所有一线工程师给 Write 权限，他们需要频繁改状态和预估。
• 运营、管理层和外部客户给 Read-only 权限，防止误操作。

权限还有一个隐藏知识点：Org 级项目里，默认所有成员可能都能看到项目内容。涉及客户敏感信息的项目，不要用对外可见的默认设置，在 Project 的 Settings 里改成 Private。这个问题红线级别，别等客户数据泄露再后悔。

5.2 评论、提醒和变更历史：为什么细粒度日志很重要

一个 Item 从创建到关闭，中间的评论和状态变化都会记录在案。我越来越觉得，项目管理工具最有价值的部分不是状态字段，而是这些留痕。有人会问：为什么不上飞书和钉钉？因为聊天记录没法追溯“这个决定是谁在什么依据下做的”，而 Projects 的每个字段变化都有时间戳和操作人。

实操层面有一个高频用法：在评论里 @ 某人，对方会在 GitHub 通知中心收到提醒，相当于把任务通过评论直接转派。Issue 描述区的清单列表（task list）会自动引用关联 Issue 和 PR，打开主页就能看到嵌套关系。我建议团队养成“每条状态改动都要写一句原因”的习惯，不用长，比如“后端接口延期，等联调环境”，半个月后复盘，你会感谢这些短句。

5.3 非工程团队怎么看项目：不留账号也能同步

不是所有人都有 GitHub 账号，也不是所有人都应该被拉进 Projects。每次需要给业务方同步进度时，我会打开 Table 视图，筛选出当前迭代，用项目的“导出 CSV”功能把数据拉下来，再转成 Excel 或表格粘贴到文档里发给对方。

这个操作 30 秒完成，但效果出奇地好。它让 GitHub Projects 不需要迫使所有人改变工具习惯，同时仍然承担底层数据源的角色。团队内部的实时协作在 Projects 完成，对外部的正式简报用导出的表格交付，两套节奏互不干扰。

6. 从半信半疑到真正提效：我踩过的坑和现在的用法

讲到这里，GitHub Projects 的主要能力都过了一遍。这一节不列功能清单，聊几个真实的坑，以及我现在会对一个“想认真落地 Projects 的团队”给出哪些建议。

6.1 字段漂移：团队嘴里说的状态，和系统里的状态渐渐不是一回事

最大的坑，我管它叫“字段漂移”。一开始大家都认真填写状态和版本，但一两周后，开始有人随手点一个选项，有人把“待验收”当“已完成”用，还有人根本忘了改状态。最后看板上的状态和实际情况严重脱节，大家就觉得工具没用。

我的解决办法是设立一个“每周五项目快检”习惯：花十五分钟扫一眼全部 Item，把状态明显不符的卡片改掉，并在评论区留下一句说明。这个动作不需要项目经理单独做，可以让团队轮流做，一个人检查一周。它带来的效果不是把所有字段变得绝对准确，而是让所有人意识到“这个数据是有人盯着的”，填写质量会大幅提升。

6.2 视图权限滥用：管理员加了 20 个视图，大家反而找不到入口

另一个坑是管理员视图疯狂扩张。功能一时好玩，加了十几个视图，每个视图筛选条件还互相重叠，结果团队成员根本不知道该看哪个。我现在严格控制视图数量，新加一个视图之前必须回答三个问题：给谁看？解决什么问题？已有视图能否覆盖？三个问题答不上来，就不加。

视图命名也尽量用“角色 + 用途”的组合，比如“产品-排期总览”“开发-我负责的”，而不是“视图 1”“重要列表”之类的模糊名词。命名是团队文档的一部分，不是管理员的自娱自乐。

6.3 多项目多仓库之间的依赖可视化

单个仓库的 Issues 好管理，真正难的是多个仓库之间有依赖关系，比如前端仓库的“登录页改造”要等后端仓库的“权限接口升级”完成才能启动。GitHub Projects 不直接提供依赖连线图，但可以分三步做到近似效果：

1. 把相关仓库的 Issue 全部拉进同一个 Projects。
2. 在后端 Issue 的描述里使用任务清单，引用前端 Issue。
3. 给后端 Issue 标记优先级 P0，并设置上线日期早于前端那一条的开发启动日期。

然后在“排期总览”视图里按“版本批次”分组，依赖顺序就一眼可见。虽然没有阻塞箭头，但日期和优先级已经承担了同样的管理职责。

6.4 我现在到底怎么用它

经过一年多的折腾，我现在的用法已经稳定下来：所有项目都至少包含 Table 总表、Roadmap 时间线、我的任务、交付日历四个视图；字段基本不超过 6 个；Workflow 只开 3 条左右；每两周复盘一次字段是否还有人填，没人填就说明这个字段对当前流程是多余的，可以直接删。

很多人问，GitHub Projects 和 Jira、Trello、Notion 比到底强在哪。我的体会是：它对开发者特别友好，因为 Issue、PR、Commit 天然在同一生态里，代码钩子和项目状态联动起来之后，数据是长在自己身上的，而不是从外部粘贴进去的。这不只是省事，更是准确。

如果你现在还在用三列看板拖卡片，我建议你下次迭代时先加一个“版本批次”单选字段，再存一个“当前迭代”视图。你会立刻发现，原来每天站会要花十分钟同步的信息，现在打开同一个视图就能对齐。从这里开始，GitHub Projects 才真的开始为你提效。