Super Productivity GitLab 集成指南：生成带 api 权限的 GitLab Access Token（Personal 与 Project）-开发者社区

Super Productivity GitLab 集成指南：生成带 api 权限的 GitLab Access Token（Personal 与 Project）

【免费下载链接】super-productivitySuper Productivity is an advanced todo list app with integrated Timeboxing and time tracking capabilities. It also comes with integrations for Jira, GitLab, GitHub and Open Project.项目地址: https://gitcode.com/GitHub_Trending/su/super-productivity

本指南围绕 Super Productivity 的 GitLab 问题（Issue）集成功能，系统讲解如何生成具有权限的 GitLab 访问令牌（Access Token）。你将掌握 Personal Access Token 与 Project Access Token 的完整生成步骤、api权限范围的作用原理，以及令牌在应用内部如何被用于轮询 Issue、回写工时日志，从而顺利把 GitLab Issue 接入你的任务管理流程。

为什么 GitLab 集成需要 Access Token

Super Productivity 通过 GitLab 的 REST API（/api/v4）轮询项目 Issue 数据。从源码看，GitlabApiService在每次请求中都会把令牌放入PRIVATE-TOKEN请求头：

// src/app/features/issue/providers/gitlab/gitlab-api/gitlab-api.service.ts headers: { ...(cfg.token ? { 'PRIVATE-TOKEN': cfg.token } : {}), ... }

GitLab 的 REST API 要求所有涉及 Issue 读取与写入的请求必须携带有效的访问令牌，因此令牌是 Super Productivity 轮询 GitLab Issues 的必填项。文档开篇即说明："For polling GitLab Issues, you need to provide an access token."（轮询 GitLab Issues 时，你必须提供一个访问令牌。）除了轮询 Issue，令牌还用于搜索 Issue、拉取评论，以及在启用工时追踪后把时间日志回写回 GitLab（POST /issues/:id/add_spent_time）。

方式一：生成 Personal Access Token（个人访问令牌）

Personal Access Token 是最通用、最推荐的接入方式，适用于 gitlab.com 官方托管实例以及绝大多数自托管 GitLab。

操作步骤

登录 GitLab，进入User Settings / Access tokens（用户设置 → 访问令牌）页面。
点击Add new token（添加新令牌），按需填写令牌名称与过期时间。
在权限范围（Scopes）中勾选api这一项。
点击创建后，立即复制并安全保存令牌值——GitLab 只在创建时完整展示一次，关闭页面后将无法再次查看。

为什么只需要`api`这一个 scope

GitLab 的api范围是一个"总括性"权限，它同时授予对绝大多数 REST API 端点的完全读/写访问权，包括：

读取项目与 Issue（GET /projects/:id/issues、GET /projects/:id/issues/:issue_iid）
搜索 Issue（GET /projects/:id/issues?search=...）
读取与创建评论（GET/POST /notes）
提交工时（POST /issues/:id/add_spent_time）
读取时间统计（GET /issues/:id/time_stats）

因此，勾选api即可覆盖 Super Productivity 在 gitlab-api.service.ts 中发起的所有请求类型，无需额外勾选read_api等其他 scope。

提示：若你的 GitLab 实例支持，也可以只使用read_api等最小权限范围；但使用api范围能同时保证工时回写等写操作正常工作，是最省心的选择。

方式二：生成 Project Access Token（项目访问令牌）

Project Access Token 是令牌的另一种形态，其特点是权限被限定在单个项目范围内，而非整个用户账号。文档明确指出：

如果你自托管 GitLab，或持有 Premium/Ultimate 许可证，则可以生成一个限定到项目（project-scoped）的 Project Access Token。其权限范围与 Personal Access Token 类似，但额外需要设置一个角色（role）。

适用前提

自托管 GitLab（Self-hosted）：Project Access Token 功能在自托管实例上普遍可用；
gitlab.com 付费版（Premium/Ultimate）：如果你使用的是官方托管服务，需要相应付费订阅才能启用该功能；
免费版（Free）的 gitlab.com 用户无法创建 Project Access Token，应改用 Personal Access Token。

操作步骤

进入目标项目，打开Settings → Access tokens（项目设置 → 访问令牌）。
点击Add new token，填写令牌名称、过期时间。
在权限范围中同样勾选api。
设置一个角色（role），令牌将以该角色的身份对项目内的资源执行操作。
创建后立即复制并妥善保存令牌值。

角色（Role）与权限的关系

Project Access Token 的最终权限 = 所选 scope 与所选角色权限的交集。文档建议：若要了解各角色（Guest / Reporter / Developer / Maintainer / Owner 等）能执行哪些操作，可查阅 GitLab 官方权限矩阵文档（Permissions and roles）。对于 Super Productivity 的日常使用场景：

仅需读取 Issue 时，Reporter或Developer角色通常已足够；
若还需回写工时日志（add_spent_time），则需要更高权限的角色（如Developer），具体以你的 GitLab 实例权限配置为准。

在 Super Productivity 中配置令牌

拿到令牌后，在 Super Productivity 的Settings → Issue Providers中启用 GitLab 提供方并填写配置。对应的配置表单定义位于 gitlab-cfg-form.const.ts，主要字段如下：

配置字段	说明	默认值
`project`	GitLab 项目引用，可为数字项目 ID，或命名空间限定路径（如`group/project`，支持子组及`%2F`编码形式）	无（必填）
`token`	本指南生成的 Access Token，保存为密码类型输入框	无
`scope`	拉取 Issue 的范围：`all`/`created-by-me`/`assigned-to-me`	`created-by-me`（表单默认值，代码默认配置为`all`）
`gitlabBaseUrl`	自托管 GitLab 的基础 URL；留空则使用`https://gitlab.com/`	空
`filterUsername`	轮询更新时过滤掉自己产生的评论与变更	空
`filter`	追加到请求 URL 的自定义查询参数	空
`isEnableTimeTracking`	是否启用向 GitLab 回写工时日志	关闭

对应的数据模型与默认配置见 gitlab.model.ts 与 gitlab.const.ts。其中默认实例地址为：

export const GITLAB_BASE_URL = 'https://gitlab.com/'; export const GITLAB_API_BASE_URL = `${GITLAB_BASE_URL}api/v4`;

也就是说，使用 gitlab.com 时无需填写gitlabBaseUrl；自托管用户则需要填写实例地址，应用会拼接为<baseUrl>/api/v4作为 API 端点（gitlab-api.service.ts 中的_projectApiLink实现）。

另外，配置表单中内置了一个指向本指南文档的链接（How to get a token），方便你随时回来查看令牌生成方法，与 github-access-token-instructions.md（GitHub 令牌指南）互为补充。

令牌在底层是如何被使用的

理解令牌的底层使用方式，有助于排查接入问题：

请求头传递：所有请求通过PRIVATE-TOKEN请求头发送令牌（见上文代码）。这也是 GitLab REST API 官方支持的令牌认证方式。
项目引用编码：当project配置为group/project这类路径形式时，应用会把斜杠编码为%2F再拼入 URL（projects/+%2F编码后的路径），因为 GitLab API 对项目路径形式的项目必须做此编码（源码_projectApiLink中的.replace(/\//gi, '%2F')）。因此你既可以填数字项目 ID，也可以填group/project形式。
轮询频率：GitLab 提供方的轮询间隔为 10 分钟（GITLAB_POLL_INTERVAL = 10 * 60 * 1000），首次轮询有 16 秒延迟（GITLAB_INITIAL_POLL_DELAY = 16000），这是出于 GitLab 对免费套餐 API 用量限制的考虑（源码注释："we need a high limit because git has low usage limits"）。
工时回写：启用isEnableTimeTracking后，每日总结（Finish Day）流程会把当天记录在 GitLab 任务上的工时，以add_spent_time请求回写到对应 Issue，并附带 "Submitted via Super Productivity" 摘要（见 gitlab-issue.effects.ts）。这一流程同样依赖令牌具备相应写权限。

常见问题排查

令牌无效 / 401 Unauthorized：确认令牌已正确复制（避免空格），且 scope 中勾选了api；Personal Token 与 Project Token 都属于 GitLab 管理页面中的不同入口，注意不要填错位置。
Project Access Token 提示无权限：检查所选角色的权限是否足够；若仅使用免费版 gitlab.com，则无法使用 Project Access Token，请改用 Personal Access Token。
项目找不到 / 404：project字段请填写数字项目 ID 或group/project完整路径；GitLab API 无法通过裸项目名（slug）解析项目（源码注释 #8665），单个段名如test_config在轮询时会直接 404。
令牌泄露风险：代码中明确禁止记录含PRIVATE-TOKEN的请求日志（gitlab-api.service.ts中注释 "DO NOT LOG allArgs - contains PRIVATE-TOKEN in headers"），但你自己仍应妥善保管令牌，并在怀疑泄露时立即到 GitLab 中撤销重建。

Super Productivity GitLab 集成指南：生成带 api 权限的 GitLab Access Token（Personal 与 Project）