时间跟踪

时间跟踪有助于记录和管理在 GitLab 工作项上投入的时间。 时间跟踪功能：

• 记录在 issue、merge request、epic 和任务上实际花费的时间。
• 估算完成所需的总时间。
• 提供时间条目的详细报告。
• 使用标准化的时间单位计算总计。
• 通过快速操作和用户界面跟踪历史记录。

您可以在工作项的右侧边栏中查看时间跟踪信息：

使用 快速操作 或用户界面输入和删除时间跟踪数据。 快速操作需要单独成行。 如果在单个评论中多次使用任何快速操作，只有最后一次生效。

权限

根据您的角色，可以使用不同的时间跟踪功能：

• 要添加、编辑和移除估算，您需要至少拥有 issues 和任务的 Planner 角色，或者 merge request 的 Developer 角色。
• 要添加和编辑工时，您需要至少拥有项目的 Planner 角色。
• 要删除时间条目，您必须是作者或至少拥有 Maintainer 角色。

估算

估算旨在显示完成一项工作所需的全部时间。

当您将鼠标悬停在右侧边栏的时间跟踪信息上时，可以看到剩余的估算时间。

添加估算

先决条件：

• 在 issues 中，您必须至少拥有项目的 Planner 角色。
• 在任务中，您必须至少拥有项目的 Planner 角色。
• 在 merge requests 中，您必须至少拥有项目的 Developer 角色。

要输入估算，请使用 /estimate 快速操作，后跟时间。

例如，如果您需要输入 1 个月、2 周、3 天、4 小时和 5 分钟的估算， 请输入 /estimate 1mo 2w 3d 4h 5m。 请查看 可用的时间单位。

一个工作项只能有一个估算。 每次输入新的时间估算时，都会覆盖之前的值。

移除估算

先决条件：

• 在 issues 中，您必须至少拥有项目的 Planner 角色。
• 在任务中，您必须至少拥有项目的 Planner 角色。
• 在 merge requests 中，您必须至少拥有项目的 Developer 角色。

要完全移除估算，请使用 /remove_estimate 快速操作。

工时

工作时，您可以记录已花费的时间。

每个新的工时条目都会添加到 issue、任务或 merge request 的当前总工时中。

在 issue、任务或 merge request 上花费的总时间不能超过一年。

添加工时

先决条件：

• 您必须至少拥有项目的 Planner 角色。

使用用户界面

要使用用户界面添加时间条目：

1. 在侧边栏的 时间跟踪 部分，选择 添加时间条目（ ）。会打开一个对话框。

2. 输入：

   • 花费的时间量。
   • 可选。花费的时间。如果为空，则使用当前时间。
   • 可选。摘要。

3. 选择 保存。

侧边栏中的 已花费 总数会更新，您可以在 时间跟踪报告 中查看所有条目。

使用快速操作

要输入工时，请使用 /spend 快速操作，后跟时间。

例如，如果您需要记录 1 个月、2 周、3 天、4 小时和 5 分钟的工时， 请输入 /spend 1mo 2w 3d 4h 5m。 请查看 可用的时间单位。

要添加带有注释的 时间跟踪报告 条目，请创建一个包含描述和快速操作的评论。 它将显示在时间跟踪报告的 摘要/备注 列中。例如：

起草 MR 并回复初始评论

/spend 30m

要记录时间花费的时间，请在时间后输入日期，使用 YYYY-MM-DD 格式。

例如，要记录 2021 年 1 月 31 日花费的 1 小时工时， 请输入 /spend 1h 2021-01-31。

如果您输入未来日期，不会记录任何时间。

使用提交消息

您可以直接在提交消息中记录 issue 上的工时。当您想要跟踪工作时间而不单独更新 issue 时，这种方法很有用。

要在提交消息中添加工时，请包含 issue 引用和时间跟踪标记，格式为 @<time>，时间单位之间没有空格。

例如：

修复登录表单中的错误 #123 @1mo2d3h15m

此提交消息为 issue #123 添加了 1 个月、2 天、3 小时和 15 分钟的工时。

时间跟踪标记必须：

• 以 @ 符号开头。
• 紧接着时间单位，之间没有空格。
• 支持以下时间单位：月份（mo）、天（d）、小时（h）、分钟（m）和秒（s）。
• 使用与常规时间跟踪相同的 时间单位。

当您推送包含时间跟踪信息的提交时：

1. GitLab 从提交消息中提取花费的时间。
2. 时间会添加到同一提交消息中引用的任何 issue。
3. 系统会向 issue 添加一条注释，指示时间是从提交添加的。
4. 时间跟踪条目包含提交 SHA 和标题作为描述。

提交作者权限

只有当提交作者有权更新 issue 时，才会从提交消息向 issue 添加时间：

• 提交作者必须至少拥有 issue 所在项目的 Planner 角色。
• 如果作者没有足够的权限，其提交中的时间跟踪信息将被忽略。
• 权限检查使用与常规时间跟踪相同的规则。

已知问题

一个提交中的多个时间量

当提交消息引用多个具有不同时间量的 issue 时，只有第一个时间量会应用于所有引用的 issue。

例如，此提交消息：

修复 #41 @1h30m 并修复 #40 @2h

为 issue #41 和 issue #40 都添加了 1h30m。第二个时间量（@2h）被忽略。

提交 SHA 变更导致的重复时间条目

当提交的 SHA 发生变化时（例如在变基或修改后），GitLab 会将其视为用于时间跟踪的新提交。如果原始提交和新提交都在 issue 中被引用，这可能会创建重复的时间条目。

为了避免在提交 SHA 可能发生变化时出现重复的时间条目：

• 使用 UI 或快速操作直接向 issue 添加时间，而不是使用提交消息。
• 如果必须使用提交消息进行时间跟踪，仅在分支历史记录最终确定后添加时间。
• 合并前，检查 issue 的时间跟踪报告，以识别并删除任何潜在的重复条目。

防止 merge request 中的重复时间跟踪

当您合并包含时间跟踪信息的 merge request 时，GitLab 会防止重复时间跟踪：

• 每个提交只跟踪一次时间，即使相同的提交消息在存储库历史中多次出现。
• GitLab 通过检查 issue 是否已存在具有相同提交标题和 ID 的时间条目来防止重复时间跟踪。
• 当提交被合并时，不会跟踪额外的时间。这可以防止在功能分支合并到默认分支时重复计算时间。

减少工时

先决条件：

• 您必须至少拥有项目的 Planner 角色。

要减少时间，请输入负值。例如，/spend -3d 会从总工时中减少三天。您不能低于 0 分钟的工时，因此如果您移除的时间多于已输入的时间，GitLab 会忽略减法操作。

删除工时

时间日志是单个工时条目，可以是正数或负数。

先决条件：

• 您必须是时间日志的作者或至少拥有项目的 Maintainer 角色。

要删除时间日志，可以：

• 在时间跟踪报告中，在时间日志条目右侧，选择 删除工时（ ）。
• 使用 GraphQL API。

删除所有工时

先决条件：

• 您必须至少拥有项目的 Planner 角色。

要一次性删除所有工时，请使用 /remove_time_spent 快速操作。

查看工作项的时间跟踪报告

要查看工作项的时间跟踪报告：

• 在右侧边栏中，已花费 旁边，选择时间。

显示的工时分解最多限制为 100 个条目。

全局时间跟踪报告

查看整个 GitLab 中 issues、任务和 merge request 的工时报告。

此功能是一个 实验性功能。 如果您发现错误，请在 反馈问题 中告诉我们。

要查看全局时间跟踪报告：

1. 在浏览器中，输入全局报告的 URL：
   • 对于 GitLab Self-Managed，在基础 URL 后添加 /-/timelogs。例如，https://gitlab.example.com/-/timelogs。
   • 对于 GitLab.com，访问 https://gitlab.com/-/timelogs。
2. 可选。要按特定用户筛选，请输入其用户名，不带 @ 符号。
3. 选择开始和结束日期。
4. 选择 运行报告。

可用的时间单位

以下时间单位可用：

将显示的单位限制为小时

在 GitLab Self-Managed 上，您可以将时间单位的显示限制为小时。 为此：

1. 在左侧边栏，选择 搜索或转到。
2. 选择 设置 > 偏好设置。
3. 展开 本地化。
4. 在 时间跟踪 下，选择 将时间跟踪单位的显示限制为小时 复选框。
5. 选择 保存更改。

启用此选项后，将显示 75h 而不是 1w 4d 3h。

相关主题

• 时间跟踪 GraphQL 参考：
  • Connection
  • Edge
  • Fields
  • Timelogs
  • Group timelogs
  • Project Timelogs
  • User Timelogs