跳转至

获取项目Pull Request列表

GET /api/v5/repos/{owner}/{repo}/pulls

该接口用于获取指定仓库下的 Pull Request 列表，支持按状态、目标分支、时间范围、排序、分页等条件进行筛选，并可仅返回各状态的合并请求计数。

访问令牌支持说明

  • AtomGit 用户访问令牌（AtomGit user access tokens）

是否允许匿名访问

此接口允许匿名访问

请求参数

参数名 位置 类型 必填 说明
owner path string 是 仓库所属空间地址（企业、组织或个人的地址 path）
repo path string 是 仓库路径（path）
state query string 否 Pull Request 状态，枚举：all / open / closed / locked / merged；默认 all
base query string 否 Pull Request 提交目标分支的名称
since query string 否 起始的更新时间，要求时间格式为 ISO 8601，例如：2024-11-20T13:00:21+08:00
direction query string 否 排序方向：升序/降序，默认 desc（asc 或 desc）
sort query string 否 排序字段：created、updated，默认 created
milestone_number query integer 否 里程碑序号（id）
labels query string 否 以逗号分隔的标签名称列表
page query integer 否 当前页码，默认为 1
per_page query integer 否 每页数量，最大为 100，默认 20
author query string 否 PR 创建者用户名
assignee query string 否 PR 负责人用户名
reviewer query string 否 PR 评审人用户名
merged_after query string 否 返回在指定时间之后合并的合并请求，要求时间格式为 ISO 8601，例如：2024-11-20T13:00:21+08:00
merged_before query string 否 返回在指定时间之前合并的合并请求，要求时间格式为 ISO 8601
only_count query boolean 否 如果为 true，则仅返回合并请求的计数，默认为 false
created_after query string 否 返回在指定时间之后创建的合并请求，要求时间格式为 ISO 8601
created_before query string 否 返回在指定时间之前创建的合并请求，要求时间格式为 ISO 8601
updated_before query string 否 返回在指定时间之前更新的合并请求，要求时间格式为 ISO 8601
updated_after query string 否 返回在指定时间之后更新的合并请求，要求时间格式为 ISO 8601

响应参数

响应为 Pull Request 对象数组；当 only_count=true 时，响应为合并请求计数对象（见「only_count=true 计数响应」）。下表「可为空」列中标注 — 表示参考文档未提供该信息。

字段 类型 必返 可为空 说明
number integer 是 — Pull Request 编号
html_url string 是 — Pull Request 的网页地址
url string 是 — Pull Request 的 API 地址
close_related_issue integer 是 — 关联关闭的 Issue 数量
prune_branch boolean 是 — 合并后是否删除源分支
draft boolean 是 — 是否为草稿
labels object[] 是 — 标签列表
user object 是 — PR 创建者信息
assignees string[] 是 — 负责人用户名列表
testers string[] 是 — 测试人员用户名列表
head object 是 — 源分支（head）信息
base object 是 — 目标分支（base）信息
id integer 是 — Pull Request 的数据库 ID
iid integer 是 — 项目内 Pull Request 序号
project_id integer 是 — 项目 ID
title string 是 — 标题
body string 是 — 描述内容
state string 是 — 状态：open / closed / locked / merged
assignees_number integer 是 — 负责人数量
testers_number integer 是 — 测试人员数量
created_at string 是 — 创建时间
updated_at string 是 — 更新时间
merged_at string 是 是 合并时间，未合并时为 null
closed_at string 是 是 关闭时间，未关闭时为 null
target_branch string 是 — 目标分支名称
source_branch string 是 — 源分支名称
source_project_id integer 是 — 源项目 ID
force_remove_source_branch boolean 是 — 合并后是否强制删除源分支
web_url string 是 — 网页地址
merge_request_type string 是 — 合并请求类型
review_mode string 是 — 评审模式
added_lines integer 是 — 新增代码行数
removed_lines integer 是 — 删除代码行数
diff_refs object 是 — 差异引用信息
notes integer 是 — 评论数量
pipeline_status string 是 — 流水线状态
pipeline_status_with_code_quality string 是 — 含代码质量的流水线状态
source_git_url string 是 — 源仓库 Git 地址
can_merge_check boolean 是 — 该字段已废弃，如需判断是否可合并，请调用 Pull Request 详情接口
mergeable boolean 是 — 是否可合并
locked boolean 是 — 是否已锁定
closed_by object 是 是 关闭人信息，未关闭时为 null
visibility_reason string 是 — 可见性：public：公开可见，other：仅项目成员可见
merged_by object 否 是 合并人信息

labels 对象

字段 类型 必返 可为空 说明
labels.id integer 是 — 标签 ID
labels.name string 是 — 标签名称
labels.color string 是 — 标签颜色
labels.created_at string 是 — 标签添加时间
labels.updated_at string 是 — 标签更新时间

user 对象

字段 类型 必返 可为空 说明
user.id string 是 — 用户 ID
user.user_id string 是 — 用户账号 ID
user.object_id string 是 — 对象 ID
user.login string 是 — 登录名
user.name string 是 — 用户名称
user.state string 是 — 用户状态
user.avatar_url string 是 — 头像地址
user.email string 是 — 邮箱
user.name_cn string 是 — 中文名称
user.html_url string 是 — 用户主页地址
字段 类型 必返 可为空 说明
head.label string 是 — 源分支标签（owner:branch）
head.ref string 是 — 源分支引用
head.sha string 是 — 源分支提交 SHA
head.user object 是 — 源分支所属用户
head.repo object 是 — 源分支所属仓库

head.user 对象

字段 类型 必返 可为空 说明
head.user.id string 是 — 用户 ID
head.user.login string 是 — 登录名
head.user.name string 是 — 用户名称
head.user.state string 是 — 用户状态
head.user.avatar_url string 是 — 头像地址
head.user.email string 是 — 邮箱
head.user.name_cn string 是 — 中文名称
head.user.html_url string 是 — 用户主页地址

head.repo 对象

字段 类型 必返 可为空 说明
head.repo.id integer 是 — 仓库 ID
head.repo.full_path string 是 — 仓库完整路径
head.repo.full_name string 是 — 仓库完整名称
head.repo.human_name string 是 — 仓库显示名称
head.repo.name string 是 — 仓库名称
head.repo.path string 是 — 仓库路径
head.repo.description string 是 — 仓库描述
head.repo.owner object 是 — 仓库所属用户
head.repo.assigner object 是 — 仓库分配者
head.repo.internal boolean 是 — 是否内部仓库
head.repo.html_url string 是 — 仓库网页地址

head.repo.owner 对象

字段 类型 必返 可为空 说明
head.repo.owner.id string 是 — 用户 ID
head.repo.owner.login string 是 — 登录名
head.repo.owner.name string 是 — 用户名称
head.repo.owner.state string 是 — 用户状态
head.repo.owner.avatar_url string 是 — 头像地址
head.repo.owner.email string 是 — 邮箱
head.repo.owner.name_cn string 是 — 中文名称
head.repo.owner.html_url string 是 — 用户主页地址

head.repo.assigner 对象

字段 类型 必返 可为空 说明
head.repo.assigner.id string 是 — 用户 ID
head.repo.assigner.login string 是 — 登录名
head.repo.assigner.name string 是 — 用户名称
head.repo.assigner.state string 是 — 用户状态
head.repo.assigner.avatar_url string 是 — 头像地址
head.repo.assigner.email string 是 — 邮箱
head.repo.assigner.name_cn string 是 — 中文名称
head.repo.assigner.html_url string 是 — 用户主页地址

base 对象

字段 类型 必返 可为空 说明
base.label string 是 — 目标分支标签（owner:branch）
base.ref string 是 — 目标分支引用
base.sha string 是 — 目标分支提交 SHA
base.user object 是 — 目标分支所属用户
base.repo object 是 — 目标分支所属仓库

base.user 对象

字段 类型 必返 可为空 说明
base.user.id string 是 — 用户 ID
base.user.login string 是 — 登录名
base.user.name string 是 — 用户名称
base.user.state string 是 — 用户状态
base.user.avatar_url string 是 — 头像地址
base.user.email string 是 — 邮箱
base.user.name_cn string 是 — 中文名称
base.user.html_url string 是 — 用户主页地址

base.repo 对象

字段 类型 必返 可为空 说明
base.repo.id integer 是 — 仓库 ID
base.repo.full_path string 是 — 仓库完整路径
base.repo.full_name string 是 — 仓库完整名称
base.repo.human_name string 是 — 仓库显示名称
base.repo.name string 是 — 仓库名称
base.repo.path string 是 — 仓库路径
base.repo.description string 是 — 仓库描述
base.repo.owner object 是 — 仓库所属用户
base.repo.assigner object 是 — 仓库分配者
base.repo.internal boolean 是 — 是否内部仓库
base.repo.html_url string 是 — 仓库网页地址

base.repo.owner 对象

字段 类型 必返 可为空 说明
base.repo.owner.id string 是 — 用户 ID
base.repo.owner.login string 是 — 登录名
base.repo.owner.name string 是 — 用户名称
base.repo.owner.state string 是 — 用户状态
base.repo.owner.avatar_url string 是 — 头像地址
base.repo.owner.email string 是 — 邮箱
base.repo.owner.name_cn string 是 — 中文名称
base.repo.owner.html_url string 是 — 用户主页地址

base.repo.assigner 对象

字段 类型 必返 可为空 说明
base.repo.assigner.id string 是 — 用户 ID
base.repo.assigner.login string 是 — 登录名
base.repo.assigner.name string 是 — 用户名称
base.repo.assigner.state string 是 — 用户状态
base.repo.assigner.avatar_url string 是 — 头像地址
base.repo.assigner.email string 是 — 邮箱
base.repo.assigner.name_cn string 是 — 中文名称
base.repo.assigner.html_url string 是 — 用户主页地址

diff_refs 对象

字段 类型 必返 可为空 说明
diff_refs.base_sha string 是 — 目标分支基准提交 SHA
diff_refs.head_sha string 是 — 源分支头提交 SHA
diff_refs.start_sha string 是 — 起始提交 SHA

closed_by 对象

字段 类型 必返 可为空 说明
closed_by.id integer 是 — 用户 ID
closed_by.name string 是 — 用户名称
closed_by.username string 是 — 用户名
closed_by.iam_id string 是 — IAM ID
closed_by.nick_name string 是 — 昵称
closed_by.state string 是 — 用户状态
closed_by.avatar_url string 是 — 头像地址
closed_by.email string 是 — 邮箱
closed_by.name_cn string 是 — 中文名称
closed_by.web_url string 是 — 用户主页地址

merged_by 对象

字段 类型 必返 可为空 说明
merged_by.id string 是 — 用户 ID
merged_by.login string 是 — 登录名
merged_by.name string 是 — 用户名称
merged_by.avatar_url string 是 — 头像地址
merged_by.html_url string 是 — 用户主页地址

only_count=true 计数响应

当 only_count=true 时，不返回 Pull Request 数组，而是返回各状态的合并请求计数：

{
  "all": 1,
  "opened": 1,
  "closed": 0,
  "merged": 0,
  "locked": 0
}

失败响应

此接口允许匿名访问；当携带的访问令牌无效或已过期时，返回 401。错误响应字段名以后端实际返回为准。

400 参数错误

{
  "error": "invalid_request",
  "message": "参数 state 取值无效",
  "field": "state"
}

401 未认证

{
  "error": "unauthorized",
  "message": "缺少或无效的访问令牌"
}

HTTP 响应状态码

状态码 说明
200 成功（OK）
400 参数错误（Bad request）
401 需要认证（Requires authentication）
404 资源不存在（Not found）
429 请求过于频繁（Rate limited）
500 系统内部错误（Internal server error）

请求示例

参数说明

示例中的占位符含义如下：

<owner> 替换为仓库所属空间地址（企业、组织或个人的地址 path）； <repo> 替换为仓库路径（path）。

此接口允许匿名访问，示例未携带认证信息；如需以登录身份访问，可携带 AtomGit 用户访问令牌。

cURL

curl -X GET 'https://api.atomgit.com/api/v5/repos/<owner>/<repo>/pulls?state=all&per_page=20' \
  -H 'Accept: application/json'

JavaScript

// 原生 fetch (Node.js 18+ / 浏览器)
const response = await fetch(
  "https://api.atomgit.com/api/v5/repos/<owner>/<repo>/pulls?state=all&per_page=20",
  {
    headers: {
      "Accept": "application/json",
    },
  },
);

if (!response.ok) {
  throw new Error(`请求失败: ${response.status}`);
}

const data = await response.json();
console.log(data);

Python

import requests

resp = requests.get(
    "https://api.atomgit.com/api/v5/repos/<owner>/<repo>/pulls",
    params={"state": "all", "per_page": 20},
    headers={"Accept": "application/json"},
    timeout=10,
)
resp.raise_for_status()

print(resp.json())

响应示例

状态码： 200

[
  {
    "number": 1,
    "html_url": "https://api.atomgit.com/owner/repo/pulls/1",
    "url": "https://api.atomgit.com/api/v5/repos/owner/repo/pulls/1",
    "close_related_issue": 0,
    "prune_branch": true,
    "draft": false,
    "labels": [
      {
        "id": 100,
        "name": "bug",
        "color": "#ee0701",
        "created_at": "2024-11-20T13:00:21+08:00",
        "updated_at": "2024-11-20T13:00:21+08:00"
      }
    ],
    "user": {
      "id": "1",
      "user_id": "1001",
      "object_id": "u_1001",
      "login": "octocat",
      "name": "octocat",
      "state": "active",
      "avatar_url": "https://api.atomgit.com/avatar.png",
      "email": "octocat@example.com",
      "name_cn": "示例用户",
      "html_url": "https://api.atomgit.com/octocat"
    },
    "assignees": ["octocat"],
    "testers": [],
    "head": {
      "label": "octocat:feature",
      "ref": "feature",
      "sha": "abc123def456",
      "user": {
        "id": "1",
        "login": "octocat",
        "name": "octocat",
        "state": "active",
        "avatar_url": "https://api.atomgit.com/avatar.png",
        "email": "octocat@example.com",
        "name_cn": "示例用户",
        "html_url": "https://api.atomgit.com/octocat"
      },
      "repo": {
        "id": 1,
        "full_path": "owner/repo",
        "full_name": "owner/repo",
        "human_name": "repo",
        "name": "repo",
        "path": "repo",
        "description": "示例仓库",
        "owner": {
          "id": "1",
          "login": "owner",
          "name": "owner",
          "state": "active",
          "avatar_url": "https://api.atomgit.com/avatar.png",
          "email": "owner@example.com",
          "name_cn": "示例",
          "html_url": "https://api.atomgit.com/owner"
        },
        "assigner": {
          "id": "1",
          "login": "owner",
          "name": "owner",
          "state": "active",
          "avatar_url": "https://api.atomgit.com/avatar.png",
          "email": "owner@example.com",
          "name_cn": "示例",
          "html_url": "https://api.atomgit.com/owner"
        },
        "internal": false,
        "html_url": "https://api.atomgit.com/owner/repo"
      }
    },
    "base": {
      "label": "owner:main",
      "ref": "main",
      "sha": "def456abc789",
      "user": {
        "id": "1",
        "login": "owner",
        "name": "owner",
        "state": "active",
        "avatar_url": "https://api.atomgit.com/avatar.png",
        "email": "owner@example.com",
        "name_cn": "示例",
        "html_url": "https://api.atomgit.com/owner"
      },
      "repo": {
        "id": 1,
        "full_path": "owner/repo",
        "full_name": "owner/repo",
        "human_name": "repo",
        "name": "repo",
        "path": "repo",
        "description": "示例仓库",
        "owner": {
          "id": "1",
          "login": "owner",
          "name": "owner",
          "state": "active",
          "avatar_url": "https://api.atomgit.com/avatar.png",
          "email": "owner@example.com",
          "name_cn": "示例",
          "html_url": "https://api.atomgit.com/owner"
        },
        "assigner": {
          "id": "1",
          "login": "owner",
          "name": "owner",
          "state": "active",
          "avatar_url": "https://api.atomgit.com/avatar.png",
          "email": "owner@example.com",
          "name_cn": "示例",
          "html_url": "https://api.atomgit.com/owner"
        },
        "internal": false,
        "html_url": "https://api.atomgit.com/owner/repo"
      }
    },
    "id": 1,
    "iid": 1,
    "project_id": 1,
    "title": "示例 Pull Request",
    "body": "这是 Pull Request 的描述",
    "state": "open",
    "assignees_number": 1,
    "testers_number": 0,
    "created_at": "2024-11-20T13:00:21+08:00",
    "updated_at": "2024-11-20T13:00:21+08:00",
    "merged_at": null,
    "closed_at": null,
    "target_branch": "main",
    "source_branch": "feature",
    "source_project_id": 1,
    "force_remove_source_branch": true,
    "web_url": "https://api.atomgit.com/owner/repo/pulls/1",
    "merge_request_type": "merge",
    "review_mode": "standard",
    "added_lines": 120,
    "removed_lines": 30,
    "diff_refs": {
      "base_sha": "def456abc789",
      "head_sha": "abc123def456",
      "start_sha": "123456abcdef"
    },
    "notes": 3,
    "pipeline_status": "success",
    "pipeline_status_with_code_quality": "success",
    "source_git_url": "https://api.atomgit.com/octocat/repo.git",
    "can_merge_check": true,
    "mergeable": true,
    "locked": false,
    "closed_by": null,
    "visibility_reason": "public",
    "merged_by": {
      "id": "1",
      "login": "owner",
      "name": "owner",
      "avatar_url": "https://api.atomgit.com/avatar.png",
      "html_url": "https://api.atomgit.com/owner"
    }
  }
]

当 only_count=true 时，响应示例：

{
  "all": 1,
  "opened": 1,
  "closed": 0,
  "merged": 0,
  "locked": 0
}

错误码

错误码 说明
400 参数错误或请求无法解析
401 未认证或凭证无效（缺少/无效的访问凭证）
404 请求路径不存在或资源不存在
405 请求方法不支持
429 请求过于频繁，触发限流
500 系统内部错误

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 gitcode-dev/atomgit-api-doc