项目与仓库元数据
按 ID 或编码后的项目路径读取名称、可见性、默认分支、仓库地址和项目功能，支撑研发资产目录。
接入要求公开项目的查询可匿名；私有项目要求调用身份具备访问权，返回字段随角色变化。
读取项目和仓库基本信息站内调用手册 · 参数、代码与排错开发与云服务 / GitLab REST API & Webhooks
GitLab
通过 REST API 读取项目、同步 Issues、管理合并请求和流水线，并用项目 Webhooks 接收事件。本条目以 GitLab.com 为接入示例；自建 GitLab 可采用相同 API 家族，但版本、管理员配置、许可及限流须按实例文档确认。
01 / CAPABILITIES
开放功能
核心接口调用手册
2 个场景覆盖读取项目、查询和创建 Issue 两个场景，共三个具体操作。示例使用 GitLab.com 的传统 PAT 与 REST v4；未包含 OAuth 流程、合并代码或 CI 写入。
Issues 与外部工单同步
列出、创建、更新问题记录，维护描述、标签和里程碑，将用户反馈与项目中的 Issue 编号关联。
接入要求项目需启用 Issues；写入需 api scope 以及用户自身的事项操作权限，机密事项另受可见性约束。
查询并创建项目 Issue站内调用手册 · 参数、代码与排错合并请求与代码评审
查询待处理合并请求、读取变更与评审状态，按项目规则执行更新或合并，用于评审面板和发布检查。
接入要求私有数据需要认证；审批、合并与受保护分支须符合目标项目角色和对应套餐，不能只凭令牌绕过规则。
CI/CD 流水线管理
查询、创建、重试或取消流水线，读取 ref、SHA、状态和网页地址，把部署状态接入外部系统。
接入要求触发需要有效 CI 配置和足够权限；实例 Runner 可消耗计算分钟，使用自有 Runner 仍需自付基础设施费用。
项目事件 Webhooks
订阅推送、Issues、合并请求等事件并投递到自己的 HTTPS 服务，减少高频轮询。
接入要求创建项目 Webhook 需要相应项目管理角色；接收端按官方验证方法检查来源，并处理重投、重复和失败投递。
02 / REQUIREMENTS
接入条件
- 适用主体
- 研发协作工具开发者、工单同步与项目看板作者、CI 和运维自动化团队
- 接入方式
- 个人访问令牌，通过 PRIVATE-TOKEN 请求头传入 / OAuth 2.0 用户授权令牌 / 项目或群组访问令牌，受套餐与资源范围限制 / CI_JOB_TOKEN 仅用于官方明确支持的端点
- 申请概况
- GitLab 账号配合个人令牌即可接入自己可访问的项目；OAuth、项目令牌和 CI Job Token 有不同范围及套餐条件。
- 准备 GitLab.com 账号和自己控制的测试项目，确认项目可见性以及 Issues 等功能已开启。
- 个人脚本可创建带到期时间的个人令牌；只读项目和事项使用 read_api，创建 Issue 的传统令牌需要 api。两者均受用户实际权限约束。
- 传统 PAT 可覆盖用户可访问的多个项目；需要收紧资源范围时评估细粒度令牌、项目令牌或 OAuth。GitLab.com 项目访问令牌需 Premium 或 Ultimate，自建版条件不同。
- OAuth 应用按官方授权流程接入；CI_JOB_TOKEN 与 deploy token 不可作为通用 REST 凭证，deploy token 不支持公共 REST API。
- 接收 Webhooks 时提供可达的服务地址并核对事件类型、认证及失败重试；自建实例的网络限制由管理员配置。
03 / GET STARTED
开通步骤
- 01
选定目标实例和身份
先确认 GitLab.com 还是自建实例；示例使用 GitLab.com 个人令牌，避免把两个实例的账号、Key 和项目 ID 混用。
- 02
创建最小权限令牌
个人设置 → Access → Personal access tokens 选择所需类型，设定用途、到期时间和 scope，将令牌保存在本地或服务端。
- 03
先读取测试项目
从项目界面取得 Project ID，先核对项目名称与访问范围，再在测试项目中试写 Issue，记录返回的 iid。
- 04
处理限流与运行费用
保留 HTTP 状态及响应头，按 Retry-After 退避；触发 CI 前核对 Runner、计算分钟和资源额度。
04 / COSTS & LIMITS
费用、边界与测试方式
费用概况
区分 API 可用性、套餐席位以及 CI/存储资源，不把 API 免费理解为所有研发资源免费。
- 所读官方资料没有对核心 Projects、Issues REST 请求列出统一按次收费。相关接口覆盖 Free、Premium、Ultimate，但仍受权限、限流和具体功能套餐限制。
- GitLab.com Free 为 0 美元/用户/月，公开价列出每月 400 compute minutes、10 GiB Git 仓库和 LFS 存储；私有顶层群组有 5 人限制，公开群组适用条件不同。
- Premium 公开年付价为 29 美元/用户/月；Ultimate 需联系销售。席位订阅与额外资源不是同一收费项目。
- 使用 GitLab.com 实例 Runner 的计算分钟按 namespace 额度与 Runner 成本系数消耗。额外计算分钟公开价为 10 美元/1,000 分钟，有效期 12 个月且不自动续费。
- 自有 Runner 不消耗 GitLab.com 的这项计算分钟额度，但主机、网络和运维自行承担；额外 Git/LFS 存储按官方增购项付费，未据此推断其他存储全部包含。
使用范围与限制
- 此处的 API 示例固定 GitLab.com /api/v4；自建实例应替换为自己的官方实例地址并核对实际版本，不保证所有新字段可用。
- api scope 不是单项目的写入授权；传统个人令牌的作用范围由用户可访问资源共同决定。
- Issue 的全局 id 与项目内 iid 含义不同，后续事项详情 URL 使用 project ID + issue iid。
- 核心 API 可用不等于所有付费功能开放；高级审批、安全与管理端点按套餐及角色决定。
- 限流因端点、身份和实例配置变化；429 应按 Retry-After 等待，不能把套餐中的计算分钟当作 API 请求次数。
如何进行开发测试
- GitLab.com 正式 API 操作真实项目；没有把测试项目视作独立费用沙箱。
- 自建 GitLab 的 API 版本、限流、网络策略和可用产品由实例管理员决定；本站未连接任何自建实例。
- 未创建令牌、授权 OAuth、订阅 Webhook、触发流水线或执行真实 API 调用。
接入前再确认
- 本站手册使用传统个人令牌的 read_api / api scopes；细粒度令牌的具体端点权限应另行核对。
- GitLab.com 与自建实例价格、令牌类型和限额不通用。
- 所有 ID、返回数值和 Issue 文本均为说明示例。
05 / OFFICIAL SOURCES
官方资料
以下资料用于核对本页内容。申请与使用时，请以对应接口的最新规则为准。
- 01Projects API：项目、可见性与元数据已核对官方资料 · 2026-10-15
- 02Issues API：查询、创建和维护事项已核对官方资料 · 2026-10-15
- 03Merge requests API：变更与评审已核对官方资料 · 2026-10-15
- 04Pipelines API：流水线与运行状态已核对官方资料 · 2026-10-15
- 05项目 Webhooks 的事件订阅与条件已核对官方资料 · 2026-10-15
- 06REST API 认证与令牌支持范围已核对官方资料 · 2026-10-15
- 07个人访问令牌创建与有效期已核对官方资料 · 2026-10-15
- 08令牌类型与 read_api / api scopes已核对官方资料 · 2026-10-15
- 09GitLab 套餐、人数与资源额度已核对官方资料 · 2026-10-15
- 10额外 CI 计算分钟与自有 Runner 费用边界已核对官方资料 · 2026-10-15
- 11GitLab.com 限额与限流已核对官方资料 · 2026-10-15
- 12REST API HTTP 状态码与错误处理已核对官方资料 · 2026-10-15
- 13GitLab.com 个人令牌设置入口官方入口 · 细则待复核 · 2026-10-15
官方文档核对，未进行接口实测
最近核验 2026-10-15 · 查看核验说明
最近核验 2026-10-15 · 查看核验说明
