GitLab调用手册

读取项目和仓库基本信息

按 Project ID 查询名称、可见性与默认分支,验证身份并为项目看板建立资源映射。

官方资料核对 2026-10-15示例代码,未进行真实接口实测
← 返回平台功能

接入准备

  • 拥有 GitLab.com 账号和可访问的测试项目;本例携带 read_api scope 的传统个人令牌。

准备环境变量

示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行;密钥不应放进公开网页。

GITLAB_TOKEN
GitLab.com 个人设置创建的传统 PAT;只读用 read_api,写入 Issue 需要 api,放在本地或服务器环境。
GITLAB_PROJECT_ID
在目标项目页面查看 Project ID;这里为虚构数字,替换为自己有权访问的项目。
终端
export GITLAB_TOKEN='glpat-replace_with_your_token'
export GITLAB_PROJECT_ID='12345678'

以上 export 适用于 macOS / Linux 的终端。按调用步骤保存代码文件,再在同一终端执行。

调用步骤

  1. 01

    登录 GitLab.com,头像 → Edit profile → Access → Personal access tokens,从 Generate token 选择 Legacy token。

  2. 02

    填写用途和到期日,按本场景勾选 scope。生成后安全保存,离开页面后不能再次查看完整令牌。

  3. 03

    打开目标测试项目,从项目界面取得 Project ID,写入 GITLAB_PROJECT_ID;不要把 Issue 的 iid 当成项目 ID。

  4. 04

    在本地终端或后端环境设置 GITLAB_TOKEN,先核对返回的项目名称与目标一致,再执行写操作。

调用 01

查询指定项目

示例只读取一个项目,返回字段会根据项目设置和调用用户权限变化。

GEThttps://gitlab.com/api/v4/projects/${GITLAB_PROJECT_ID}

请求头

PRIVATE-TOKEN
${GITLAB_TOKEN}
Accept
application/json

参数说明

参数表可左右滑动,查看完整说明。

字段 / 位置类型 / 必填说明
idPathinteger or URL-encoded string必填项目全局 ID;也可用完整 namespace/project 路径,但 / 必须编码为 %2F。
PRIVATE-TOKENHeaderstring必填本例为 read_api 传统个人访问令牌;公共可见项目的该接口允许匿名查询。
licenseQueryboolean可选是否包含项目许可证信息;示例省略。
statisticsQueryboolean可选包含统计信息需要 Reporter、Developer、Maintainer 或 Owner 角色;示例不请求。

调用代码

替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误,业务状态还需按下方返回示例核对。

cURL
# 执行后核对返回 JSON 的业务状态;HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
  --request GET \
  --url "https://gitlab.com/api/v4/projects/${GITLAB_PROJECT_ID}" \
  --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \
  --header "Accept: application/json"
Python 3
import json
import os
import re
import urllib.request
import urllib.error

def expand(value):
    return re.sub(r"\$\{([A-Z][A-Z0-9_]*)\}",
                  lambda match: os.environ[match.group(1)], value)

url = expand("https://gitlab.com/api/v4/projects/${GITLAB_PROJECT_ID}")
headers = {
    "PRIVATE-TOKEN": expand("${GITLAB_TOKEN}"),
    "Accept": expand("application/json"),
}
data = None
request = urllib.request.Request(url, data=data, headers=headers, method="GET")
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
    raise SystemExit(1)
print(json.dumps(result, ensure_ascii=False, indent=2))
Node.js
// Node.js 22+,保存为 request.mjs 后运行 node request.mjs
function expand(value) {
  return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (_, name) => {
    if (!process.env[name]) throw new Error(`缺少环境变量 ${name}`);
    return process.env[name];
  });
}

const url = expand("https://gitlab.com/api/v4/projects/${GITLAB_PROJECT_ID}");
const headers = Object.fromEntries(
  Object.entries({
  "PRIVATE-TOKEN": "${GITLAB_TOKEN}",
  "Accept": "application/json"
}).map(([key, value]) => [key, expand(value)])
);
const response = await fetch(url, {
  method: "GET",
  headers,
  signal: AbortSignal.timeout(30000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const result = JSON.parse(text);
console.log(JSON.stringify(result, null, 2));

返回示例

按官方字段整理的响应结构示意,项目 ID、名称、链接和内容均为虚构,非接口实测。default_branch 在空仓库等情况下可能为空,不应假定总是 main。 以下为结构示意,非本站实测结果。

JSON
{
  "id": 12345678,
  "name": "接入测试项目",
  "path_with_namespace": "example-team/example-project",
  "visibility": "private",
  "default_branch": "main",
  "web_url": "https://gitlab.com/example-team/example-project",
  "http_url_to_repo": "https://gitlab.com/example-team/example-project.git",
  "archived": false
}

常见错误与排查

HTTP 401未认证或令牌无效;部分权限问题也可能返回此状态。
检查 PRIVATE-TOKEN、有效期与撤销状态;确认使用 GitLab.com 对应账号的令牌。
HTTP 403 / insufficient_scope令牌 scope 或当前用户权限不足。
只读检查 read_api,创建检查 api;同时核对项目成员角色与功能可见性,勿仅扩大 scope 而忽略账号权限。
HTTP 404资源不存在或当前身份无权访问。
确认 Project ID、目标实例、项目可见性;路径形式的项目名必须 URL 编码。
HTTP 429请求超过端点或应用限流。
按 Retry-After 响应头等待并降低轮询频率;写入超时后先查重,避免重复创建。

调用注意

  • 成功为 HTTP 200。读取项目不会下载仓库文件;文件内容应使用 Repository Files 或 Repositories 相应接口。
  • 示例不请求管理员字段,也不触发 CI 或消耗 Runner 计算分钟。核心读取仍受 API 限流。

注意事项

  • GitLab.com 与自建实例项目 ID 不通用;如接入自建服务,应按实例文档改用其地址和实际版本。
  • 传统 PAT 的 read_api 可能覆盖用户可访问的多个项目;需要单资源约束时另行评估细粒度或项目令牌。

核验来源

本站按官方资料整理本场景的必要调用步骤与代码,覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。

  1. 01
    REST API 认证核验日期 2026-10-15
  2. 02
    创建传统个人访问令牌核验日期 2026-10-15
  3. 03
    访问令牌的 scope核验日期 2026-10-15
  4. 04
    Retrieve a project核验日期 2026-10-15
  5. 05
    REST API 错误与 Retry-After核验日期 2026-10-15

GitLab的其他调用手册

← 返回GitLab的全部功能