Super Productivity GitLab 集成指南生成带 api 权限的 GitLab Access TokenPersonal 与 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 TokenSuper 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、拉取评论以及在启用工时追踪后把时间日志回写回 GitLabPOST /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这一个 scopeGitLab 的api范围是一个总括性权限它同时授予对绝大多数 REST API 端点的完全读/写访问权包括读取项目与 IssueGET /projects/:id/issues、GET /projects/:id/issues/:issue_iid搜索 IssueGET /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。适用前提自托管 GitLabSelf-hostedProject 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主要字段如下配置字段说明默认值projectGitLab 项目引用可为数字项目 ID或命名空间限定路径如group/project支持子组及%2F编码形式无必填token本指南生成的 Access Token保存为密码类型输入框无scope拉取 Issue 的范围all/created-by-me/assigned-to-mecreated-by-me表单默认值代码默认配置为allgitlabBaseUrl自托管 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.mdGitHub 令牌指南互为补充。令牌在底层是如何被使用的理解令牌的底层使用方式有助于排查接入问题请求头传递所有请求通过PRIVATE-TOKEN请求头发送令牌见上文代码。这也是 GitLab REST API 官方支持的令牌认证方式。项目引用编码当project配置为group/project这类路径形式时应用会把斜杠编码为%2F再拼入 URLprojects/%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 中勾选了apiPersonal Token 与 Project Token 都属于 GitLab 管理页面中的不同入口注意不要填错位置。Project Access Token 提示无权限检查所选角色的权限是否足够若仅使用免费版 gitlab.com则无法使用 Project Access Token请改用 Personal Access Token。项目找不到 / 404project字段请填写数字项目 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 中撤销重建。延伸阅读GitHub 令牌的生成方式见 GitHub Access Token Instructions对应 GitHub Issue 集成各 Issue 集成提供方的完整对比见 docs/wiki/3.07-Issue-Integration-Comparison.mdGitLab 集成配置表单与校验规则的源码见 gitlab-cfg-form.const.tsAPI 层实现见 gitlab-api.service.ts【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
