GitHub Projects

GitHub Projects 是一个灵活的项目管理工具，可以帮你规划、追踪和管理团队的工作。它与 GitHub Issues 和 Pull Requests 深度集成，提供表格、看板和路线图三种视图。

概述

Projects 是 GitHub 的新一代项目管理工具，取代了经典的 Projects 看板。它提供了更强大的自定义能力和自动化功能。

核心特性

多视图支持：同一个项目可以用不同视角查看——表格视图适合批量编辑和数据分析，看板视图适合工作流管理，路线图视图适合时间线规划。

深度集成：直接关联 Issues 和 Pull Requests，状态变更自动同步。在 Projects 中修改的字段会反映到原始 Issue 上。

自定义字段：除了默认的标题、状态、指派人等，还可以添加自定义字段来追踪特定信息，如优先级、复杂度、目标日期等。

自动化工作流：内置自动化规则可以自动设置字段值、归档已完成项目、添加新项目等，减少手动操作。

Insights 图表：通过可视化图表了解项目进展，支持自定义筛选和图表类型。

Projects 与经典项目板的区别

特性	新 Projects	经典项目板
视图类型	表格、看板、路线图	仅看板
自定义字段	最多 50 个字段	有限
自动化	内置工作流	需手动配置
图表分析	Insights	无
API	GraphQL API	REST API

建议新项目使用新的 Projects。

快速开始

创建项目

在 GitHub 导航栏点击 Projects，然后点击 New project。

选择创建方式：

• Start from scratch：空白项目
• Start with a template：使用模板

选择视图类型：

• Table：表格视图
• Board：看板视图
• Roadmap：路线图视图

添加项目内容

创建项目后，可以添加以下类型的项目：

• Existing issues：从仓库添加现有 Issues
• New item：创建草稿项目（还未关联 Issue）

添加 Issue 的方式：
1. 点击项目中的 "+ Add item"
2. 输入 Issue 编号（如 #123）搜索
3. 选择要添加的 Issue

基础操作

在表格视图中，可以直接编辑单元格：

• 点击单元格编辑内容
• 拖拽行调整顺序
• 右键查看更多操作

在看板视图中：

• 拖拽卡片改变状态
• 点击卡片查看详情
• 按 E 快速编辑

视图类型

表格视图

表格视图提供电子表格式的界面，适合批量编辑和数据分析：

| Title          | Status  | Assignee | Priority | Sprint   |
|----------------|---------|----------|----------|----------|
| 实现用户登录   | Done    | 张三     | High     | Sprint 1 |
| 修复支付问题   | In      | 李四     | Critical | Sprint 1 |
|                | Progress|          |          |          |
| 优化首页性能   | Todo    | 王五     | Medium   | Sprint 2 |

表格视图的优势：

• 一次查看大量项目信息
• 快速编辑多个字段
• 支持排序和筛选
• 方便导出数据

看板视图

看板视图以列的形式展示项目状态，适合追踪工作流：

┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│    Todo     │ │  In         │ │   Review    │ │    Done     │
│             │ │  Progress   │ │             │ │             │
├─────────────┤ ├─────────────┤ ├─────────────┤ ├─────────────┤
│ □ 设计新版   │ │ ▶ 开发API   │ │ ✓ 完成登录  │ │ ✓ 数据库    │
│   UI界面    │ │   接口      │ │   功能      │ │   迁移      │
│             │ │             │ │             │ │             │
│ □ 编写测试   │ │ ▶ 重构代码  │ │             │ │ ✓ 用户      │
│   用例      │ │   结构      │ │             │ │   认证      │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘

看板视图的优势：

• 直观展示工作流状态
• 拖拽操作改变状态
• 限制在制品数量
• 可视化瓶颈

路线图视图

路线图视图按时间线展示项目，适合规划和追踪长期目标：

         January    February   March      April
         ├──────────┼──────────┼──────────┤
发布v2.0 ████████████████████████
API重构   ░░░░████████████████░░░░░░░░░░░
性能优化 ░░░░░░░░░░░░░░░░░░░░░░████████
移动端   ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░████████

路线图视图的优势：

• 查看整体时间线
• 规划里程碑
• 识别依赖关系
• 调整资源分配

自定义字段

字段是 Projects 的核心，用于存储和追踪项目信息。

字段类型

类型	说明	示例
Text	单行文本	"高优先级需本周完成"
Number	数字	复杂度评分：1-10
Date	日期	截止日期：2024-03-15
Single select	单选	优先级：High/Medium/Low
Iteration	迭代周期	Sprint 1, Sprint 2
Labels	标签（从 Issue 继承）	bug, feature

添加自定义字段

在项目页面点击 "+" 按钮添加新字段：

1. 选择字段类型
2. 输入字段名称
3. 配置选项（如单选的选项列表）
4. 保存

迭代字段

迭代字段用于规划 Sprint：

配置迭代字段：
- Sprint 1 (Jan 1 - Jan 14)
- Sprint 2 (Jan 15 - Jan 28)
- Sprint 3 (Jan 29 - Feb 11)
- Break (Feb 12 - Feb 18)  // 休息周

迭代字段支持：

• 开始和结束日期
• 休息期（不安排工作）
• 自动推进到下一个迭代

使用字段分组

按字段值分组查看项目：

按 Assignee 分组：
张三
  └─ 实现用户登录
  └─ 修复支付问题
李四
  └─ 优化首页性能
  └─ 编写文档
未分配
  └─ 数据库迁移

在视图菜单中选择 "Group by"，然后选择分组字段。

筛选和排序

筛选语法

Projects 支持强大的筛选语法：

# 按状态筛选
status:"In Progress"

# 按指派人筛选
assignee:@me
assignee:username

# 按标签筛选
label:bug
label:enhancement

# 按迭代筛选
iteration:@current
iteration:"Sprint 1"

# 组合筛选
status:"In Progress" label:bug

# 排除筛选
-status:Done

# 按日期筛选
target:<=2024-03-15

保存视图

配置好筛选和排序后，可以保存为自定义视图：

1. 点击视图名称旁边的下拉菜单
2. 选择 "Save changes to view" 或 "Save as new view"
3. 为视图命名

团队成员可以切换到保存的视图查看项目。

排序规则

支持按多个字段排序，优先级从高到低：

1. 点击列标题排序
2. 再次点击切换升序/降序
3. Shift+点击添加次级排序

排序示例：
1. 先按 Priority 降序（Critical 在前）
2. 再按 Target Date 升序（早日期在前）

自动化

内置工作流

Projects 提供内置自动化，无需编写代码：

自动设置字段：当项目添加或状态变更时自动设置字段值。

配置方式：

1. 点击项目设置中的 "Workflows"
2. 选择要启用的工作流
3. 配置触发条件和动作

可用的工作流：

工作流	触发条件	动作
Item added	项目添加时	设置 Status 为 "Todo"
Item reopened	项目重新打开	设置 Status 为 "In Progress"
Item closed	项目关闭	设置 Status 为 "Done"
Pull request merged	PR 合并	设置 Status 为 "Done"

自动归档

配置自动归档规则，保持项目整洁：

自动归档配置：
- 触发条件：Status = Done
- 延迟时间：7 天后
- 动作：自动归档项目

自动添加项目

配置规则，新 Issue 或 PR 自动添加到项目：

自动添加配置：
- 仓库：my-org/my-repo
- 筛选条件：label:"needs-triage"
- 动作：添加到项目，设置 Status 为 "Todo"

使用 GitHub Actions

更复杂的自动化可以通过 GitHub Actions 实现：

name: Add to Project

on:
  issues:
    types: [opened, labeled]

jobs:
  add-to-project:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/add-to-project@v1
        with:
          project-url: https://github.com/orgs/my-org/projects/1
          github-token: ${{ secrets.PROJECT_TOKEN }}
          labeled: bug, enhancement
          label-operator: OR

这个工作流会在 Issue 被标记为 bug 或 enhancement 时自动添加到项目。

Insights 图表

Insights 提供项目数据可视化，帮助了解项目进展。

默认图表

每个项目都有默认图表：

• 按状态分组：展示各状态的项目数量
• 按迭代分组：展示各迭代的工作量
• 随时间变化：展示项目状态的时间趋势

创建自定义图表

点击 "New chart" 创建自定义图表：

1. 选择图表类型（柱状图、饼图、折线图）
2. 选择数据源字段
3. 应用筛选条件
4. 保存图表

示例：按优先级统计 Bug 数量

图表类型：饼图
筛选条件：label:bug
分组字段：Priority

图表分享

图表可以导出或嵌入：

• 复制图表链接分享给团队成员
• 导出为图片用于报告
• 嵌入到文档或仪表板

项目模板

创建模板

将配置好的项目保存为模板：

1. 进入项目设置
2. 找到 "Template" 部分
3. 点击 "Set as template"

模板会包含：

• 视图配置
• 自定义字段
• 草稿项目和字段
• 工作流配置（不含自动添加规则）
• Insights 图表

使用模板

创建新项目时选择模板：

1. 点击 "New project"
2. 选择 "Start with a template"
3. 选择组织模板或 GitHub 提供的模板

组织模板管理

组织管理员可以管理模板：

• 查看所有模板
• 设置默认模板
• 删除不再使用的模板

团队协作

项目权限

项目可以在用户级别或组织级别创建：

用户项目：仅创建者可访问，可以邀请协作者

组织项目：组织成员可访问，支持更细粒度的权限控制

权限级别：

权限	能力
Read	查看项目
Write	编辑项目内容
Admin	管理项目设置、删除项目

共享状态更新

定期分享项目进展：

1. 点击项目右上角的 "Share update"
2. 设置状态（On track, At risk, Off track）
3. 添加状态说明
4. 设置开始和目标日期

状态更新会显示在项目摘要和项目列表中。

与团队的沟通

在项目项目中可以直接添加评论：

• 使用 @mention 提及团队成员
• 引用其他 Issue 或 PR
• 添加表情反应

API 集成

GraphQL API

Projects 使用 GraphQL API 进行程序化操作：

query {
  node(id: "PROJECT_ID") {
    ... on ProjectV2 {
      items(first: 10) {
        nodes {
          id
          content {
            ... on Issue {
              title
              number
            }
          }
        }
      }
    }
  }
}

使用 GitHub Actions 自动化

添加项目项目的 Actions 示例：

name: Update Project Field

on:
  issues:
    types: [labeled]

jobs:
  update-field:
    runs-on: ubuntu-latest
    steps:
      - name: Update priority field
        uses: leonsteinhaeuser/project-beta-automations@v2
        with:
          gh_token: ${{ secrets.PROJECT_TOKEN }}
          organization: my-org
          project_id: 1
          resource_node_id: ${{ github.event.issue.node_id }}
          field_name: Priority
          field_value: High

最佳实践

字段设计原则

1. 保持简洁：只添加必要的字段，避免信息过载
2. 使用单选而非文本：便于筛选和分组
3. 设置默认值：减少手动输入

推荐的字段配置：
- Status: Todo/In Progress/Review/Done（必需）
- Priority: Critical/High/Medium/Low（必需）
- Sprint: 迭代字段（按团队需要）
- Effort: 数字字段（故事点估算）

视图配置建议

为不同目的创建不同视图：

推荐视图配置：
1. "All items" - 表格视图，默认排序
2. "Active sprint" - 看板视图，按当前迭代筛选
3. "By assignee" - 表格视图，按指派人分组
4. "Roadmap" - 路线图视图，按目标日期排序
5. "Bugs" - 看板视图，筛选 label:bug

工作流建议

1. 启用 "Item added" 工作流，自动设置初始状态
2. 启用 "Item closed" 工作流，自动标记完成
3. 配置自动归档，定期清理已完成项目

定期维护

• 每周审查项目状态
• 归档已完成的项目
• 更新过时的估算
• 调整优先级排序

参考资源

• Projects 官方文档
• Projects 快速入门
• Projects 最佳实践
• Projects GraphQL API