Help us learn about your current experience with the documentation. Take the survey.

分支 API

  • 版本: Free, Premium, Ultimate
  • 提供方式: GitLab.com, GitLab Self-Managed, GitLab Dedicated

使用分支 API 以编程方式管理项目的 Git 分支。

要更改项目的分支保护配置，请使用受保护分支 API。

列出仓库分支

获取项目的仓库分支列表，按名称字母顺序排序。按名称搜索，或 使用正则表达式查找特定的分支模式。返回分支的详细信息， 包括其保护状态、合并状态和提交详情。

如果仓库是公开可访问的，则无需身份验证即可访问此端点。

GET /projects/:id/repository/branches

参数：

属性 类型 必需 描述
id 整数或字符串 是 项目的 ID 或 URL 编码路径。
search 字符串 否 返回包含搜索字符串的分支列表。使用 ^term 查找以 term 开头的分支，使用 term$ 查找以 term 结尾的分支。
regex 字符串 否 返回名称匹配 re2 正则表达式的分支列表。

示例请求：

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/branches"

示例响应：

[
  {
    "name": "main",
    "merged": false,
    "protected": true,
    "default": true,
    "developers_can_push": false,
    "developers_can_merge": false,
    "can_push": true,
    "web_url": "https://gitlab.example.com/my-group/my-project/-/tree/main",
    "commit": {
      "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
      "short_id": "7b5c3cc",
      "created_at": "2024-06-28T03:44:20-07:00",
      "parent_ids": [
        "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
      ],
      "title": "add projects API",
      "message": "add projects API",
      "author_name": "John Smith",
      "author_email": "[email protected]",
      "authored_date": "2024-06-27T05:51:39-07:00",
      "committer_name": "John Smith",
      "committer_email": "[email protected]",
      "committed_date": "2024-06-28T03:44:20-07:00",
      "trailers": {},
      "extended_trailers": {},
      "web_url": "https://gitlab.example.com/my-group/my-project/-/commit/7b5c3cc8be40ee161ae89a06bba6229da1032a0c"
    }
  },
  ...
]

获取单个仓库分支

获取单个项目仓库分支。

如果仓库是公开可访问的，则无需身份验证即可访问此端点。

GET /projects/:id/repository/branches/:branch

参数：

属性 类型 必需 描述
id 整数或字符串 是 项目的 ID 或 URL 编码路径。
branch 字符串 是 分支的 URL 编码名称。

示例请求：

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/branches/main"

示例响应：

{
  "name": "main",
  "merged": false,
  "protected": true,
  "default": true,
  "developers_can_push": false,
  "developers_can_merge": false,
  "can_push": true,
  "web_url": "https://gitlab.example.com/my-group/my-project/-/tree/main",
  "commit": {
    "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
    "short_id": "7b5c3cc",
    "created_at": "2012-06-28T03:44:20-07:00",
    "parent_ids": [
      "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
    ],
    "title": "add projects API",
    "message": "add projects API",
    "author_name": "John Smith",
    "author_email": "[email protected]",
    "authored_date": "2012-06-27T05:51:39-07:00",
    "committer_name": "John Smith",
    "committer_email": "[email protected]",
    "committed_date": "2012-06-28T03:44:20-07:00",
    "trailers": {},
    "web_url": "https://gitlab.example.com/my-group/my-project/-/commit/7b5c3cc8be40ee161ae89a06bba6229da1032a0c"
  }
}

保护仓库分支

有关保护仓库分支的信息，请参阅 POST /projects/:id/protected_branches。

取消保护仓库分支

有关取消保护仓库分支的信息，请参阅 DELETE /projects/:id/protected_branches/:name。

创建仓库分支

在仓库中创建一个新分支。

POST /projects/:id/repository/branches

参数：

属性 类型 必需 描述
id 整数 是 项目的 ID 或 URL 编码路径。
branch 字符串 是 分支的名称。
ref 字符串 是 用于创建分支的分支名称或提交 SHA。

示例请求：

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/branches?branch=newbranch&ref=main"

示例响应：

{
  "commit": {
    "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
    "short_id": "7b5c3cc",
    "created_at": "2012-06-28T03:44:20-07:00",
    "parent_ids": [
      "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
    ],
    "title": "add projects API",
    "message": "add projects API",
    "author_name": "John Smith",
    "author_email": "[email protected]",
    "authored_date": "2012-06-27T05:51:39-07:00",
    "committer_name": "John Smith",
    "committer_email": "[email protected]",
    "committed_date": "2012-06-28T03:44:20-07:00",
    "trailers": {},
    "web_url": "https://gitlab.example.com/my-group/my-project/-/commit/7b5c3cc8be40ee161ae89a06bba6229da1032a0c"
  },
  "name": "newbranch",
  "merged": false,
  "protected": false,
  "default": false,
  "developers_can_push": false,
  "developers_can_merge": false,
  "can_push": true,
  "web_url": "https://gitlab.example.com/my-group/my-project/-/tree/newbranch"
}

删除仓库分支

从仓库中删除分支。

如果出现错误，会提供解释消息。

DELETE /projects/:id/repository/branches/:branch

参数：

属性 类型 必需 描述
id 整数/字符串 是 项目的 ID 或 URL 编码路径。
branch 字符串 是 分支的名称。

示例请求：

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/branches/newbranch"

删除分支不会完全擦除所有相关数据。 某些信息会保留以维护项目历史并支持恢复过程。 更多信息，请参阅处理敏感信息。

删除已合并的分支

删除所有已合并到项目默认分支的分支。

受保护分支不会作为此操作的一部分被删除。

DELETE /projects/:id/repository/merged_branches

参数：

属性 类型 必需 描述
id 整数/字符串 是 项目的 ID 或 URL 编码路径。

示例请求：

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/merged_branches"

相关主题