开放能力导航
首页/GitLab/调用手册
GitLab调用手册

查询并创建项目 Issue

把外部反馈写入测试项目，并保留项目内 iid 和网页链接供后续同步。

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

接入准备

  • 目标项目已启用 Issues，账号有创建 Issue 的权限；使用 api scope 的传统 PAT，仅只读查询可改用 read_api。
  • 创建动作会生成真实事项并可能发送通知，请先使用自己的测试项目并改好标题和正文。

准备环境变量

示例值需要替换为自己的凭证或资源 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，先核对返回的项目名称与目标一致，再执行写操作。

  5. 05

    只需要读取时使用 read_api；本页创建请求需要 api。先查询事项列表确认目标，再编辑请求体中的测试文字。

  6. 06

    收到创建结果后保存项目 ID + iid + 外部记录 ID 的映射；若请求超时，先在项目或列表查询中确认是否已创建。

调用 01

列出项目内待处理 Issue

返回指定项目打开中的事项第一页，按更新时间倒序，便于构建处理看板。

GEThttps://gitlab.com/api/v4/projects/${GITLAB_PROJECT_ID}/issues?state=opened&order_by=updated_at&sort=desc&per_page=20&page=1

请求头

PRIVATE-TOKEN
${GITLAB_TOKEN}
Accept
application/json

参数说明

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

字段 / 位置类型 / 必填说明
idPathinteger or URL-encoded string必填目标项目 ID 或编码后的 namespace/project 路径。
stateQuerystring可选opened、closed 或 all；本例 opened。
order_by / sortQuerystring可选本例 updated_at 与 desc，最近更新在前。
per_page / pageQueryinteger可选每页默认 20、最多 100；page 从 1 开始。仅取得第一页不是全部事项。
searchQuerystring可选可按标题与描述搜索；用于查重时仍应结合外部唯一 ID，不能只靠标题。

调用代码

替换示例 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}/issues?state=opened&order_by=updated_at&sort=desc&per_page=20&page=1" \
  --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}/issues?state=opened&order_by=updated_at&sort=desc&per_page=20&page=1")
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}/issues?state=opened&order_by=updated_at&sort=desc&per_page=20&page=1");
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 是全局事项 ID，iid 是当前项目内的编号。 以下为结构示意，非本站实测结果。

JSON
[
  {
    "id": 987654321,
    "iid": 42,
    "project_id": 12345678,
    "title": "外部反馈示例",
    "state": "opened",
    "web_url": "https://gitlab.com/example-team/example-project/-/issues/42",
    "labels": []
  }
]

常见错误与排查

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；按 Link 响应头的 rel=next 翻页，不要自行假设总数或抓取全部页。
  • 私有或机密事项需要相应可见性；列表里没出现某项不代表它不存在。
List all project issuesREST API 分页与 ID / iidREST API 错误与 Retry-After
调用 02

创建一条测试 Issue

最小请求只提供标题和描述，不自动添加负责人、标签或里程碑。

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

请求头

PRIVATE-TOKEN
${GITLAB_TOKEN}
Accept
application/json
Content-Type
application/json

参数说明

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

字段 / 位置类型 / 必填说明
idPathinteger or URL-encoded string必填目标项目 ID，与前一个读取操作一致。
title请求体string必填Issue 标题；请修改测试文字，不能留空。
description请求体string可选Markdown 描述；示例写入外部记录的虚构编号，便于排查重复。
confidential请求体boolean可选默认 false；机密事项的访问规则不同，示例不设置。

调用代码

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

cURL
cat > request-body.json <<'JSON'
{
  "title": "接入测试：同步一条外部反馈",
  "description": "这是测试项目中的说明文字。外部记录编号：example-feedback-001。"
}
JSON

# 执行后核对返回 JSON 的业务状态；HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://gitlab.com/api/v4/projects/${GITLAB_PROJECT_ID}/issues" \
  --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data-binary @request-body.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}/issues")
headers = {
    "PRIVATE-TOKEN": expand("${GITLAB_TOKEN}"),
    "Accept": expand("application/json"),
    "Content-Type": expand("application/json"),
}
body = {
    "title": "接入测试：同步一条外部反馈",
    "description": "这是测试项目中的说明文字。外部记录编号：example-feedback-001。",
}
data = json.dumps(body, ensure_ascii=False).encode("utf-8")
request = urllib.request.Request(url, data=data, headers=headers, method="POST")
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}/issues");
const headers = Object.fromEntries(
  Object.entries({
  "PRIVATE-TOKEN": "${GITLAB_TOKEN}",
  "Accept": "application/json",
  "Content-Type": "application/json"
}).map(([key, value]) => [key, expand(value)])
);
const body = {
  "title": "接入测试：同步一条外部反馈",
  "description": "这是测试项目中的说明文字。外部记录编号：example-feedback-001。"
};
const response = await fetch(url, {
  method: "POST",
  headers,
  body: JSON.stringify(body),
  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));

返回示例

按官方字段整理的 HTTP 201 响应结构示意。这里的 ID、iid、链接与文本为虚构，非真实写入结果；后续项目事项端点用 iid。 以下为结构示意，非本站实测结果。

JSON
{
  "id": 987654322,
  "iid": 43,
  "project_id": 12345678,
  "title": "接入测试：同步一条外部反馈",
  "description": "这是测试项目中的说明文字。外部记录编号：example-feedback-001。",
  "state": "opened",
  "web_url": "https://gitlab.com/example-team/example-project/-/issues/43"
}

常见错误与排查

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

调用注意

  • 创建为真实写入，不具备天然查重。业务端在创建前锁定外部记录并保存返回 iid，超时后核对再决定是否重试。
  • api scope 权限较广；撤销测试令牌并清理测试 Issue 均应由用户在自己的项目中按需完成。
Create an issueREST API 错误与 Retry-After

注意事项

  • 本页不触发流水线、合并代码或更改项目设置。项目和 Issues 接口受 Free / Premium / Ultimate 功能及角色规则约束。
  • 分页、限流和鉴权是三项独立条件；没有拿到第二页不表示没有更多数据。

核验来源

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

  1. 01
    REST API 认证核验日期 2026-10-15
  2. 02
    创建传统个人访问令牌核验日期 2026-10-15
  3. 03
    访问令牌的 scope核验日期 2026-10-15
  4. 04
    REST API 分页与 ID / iid核验日期 2026-10-15
  5. 05
    List all project issues核验日期 2026-10-15
  6. 06
    REST API 错误与 Retry-After核验日期 2026-10-15
  7. 07
    Create an issue核验日期 2026-10-15

GitLab的其他调用手册

读取项目和仓库基本信息

← 返回GitLab的全部功能