仓库文件 API - GitLab - GitLab 文档中心

Tier: 基础版, 专业版, 旗舰版

Offering: JihuLab.com, 私有化部署

你可以使用此 API 获取、创建、更新和删除你的代码库中的文件。你也可以为此 API 配置速率限制。

个人访问令牌的可用范围#

Scope	Description
api	允许对代码库文件进行读写访问。
read_api	允许对代码库文件进行读取访问。
read_repository	允许对代码库文件进行读取访问。

从代码库获取文件#

允许你接收有关代码库中文件的信息，例如名称、大小和内容。文件内容是 Base64 编码的。如果代码库是公开访问的，你可以在不进行身份验证的情况下访问此端点。

plaintext
GET /projects/:id/repository/files/:file_path

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb?ref=main"

Attribute	Type	Required	Description
id	integer or string	yes	项目的 ID 或 URL 编码的项目路径。
file_path	string	yes	URL 编码的新文件完整路径，例如 lib%2Fclass%2Erb。
ref	string	yes	分支、标签或提交的名称。使用 HEAD 自动使用默认分支。

如果你不知道分支名称或想使用默认分支，你可以使用 HEAD 作为 ref 值。例如：

shell
curl --header "PRIVATE-TOKEN: " \
  --url "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb?ref=HEAD"

响应#

在响应中，blob_id 是 blob 的 SHA。请参阅极狐GitLab API 中的从代码库获取 blob。

响应示例：

json
1{
2  "file_name": "key.rb",
3  "file_path": "app/models/key.rb",
4  "size": 1476,
5  "encoding": "base64",
6  "content": "IyA9PSBTY2hlbWEgSW5mb3...",
7  "content_sha256": "4c294617b60715c1d218e61164a3abd4808a4284cbc30e6728a01ad9aada4481",
8  "ref": "main",
9  "blob_id": "79f7bbd25901e8334750839545a9bd021f0e4c83",
10  "commit_id": "d5a3ff139356ce33e37e73add446f16869741b50",
11  "last_commit_id": "570e7b2abdd848b95f2f578043fc23bd6f6fd24d",
12  "execute_filemode": false
13}

仅获取文件元数据#

你也可以使用 HEAD 来仅获取文件元数据。

plaintext
HEAD /projects/:id/repository/files/:file_path

shell
curl --head --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb?ref=main"

响应示例：

plaintext
1HTTP/1.1 200 OK
2...
3X-Gitlab-Blob-Id: 79f7bbd25901e8334750839545a9bd021f0e4c83
4X-Gitlab-Commit-Id: d5a3ff139356ce33e37e73add446f16869741b50
5X-Gitlab-Content-Sha256: 4c294617b60715c1d218e61164a3abd4808a4284cbc30e6728a01ad9aada4481
6X-Gitlab-Encoding: base64
7X-Gitlab-File-Name: key.rb
8X-Gitlab-File-Path: app/models/key.rb
9X-Gitlab-Last-Commit-Id: 570e7b2abdd848b95f2f578043fc23bd6f6fd24d
10X-Gitlab-Ref: main
11X-Gitlab-Size: 1476
12X-Gitlab-Execute-Filemode: false
13...

从代码库获取文件责任信息#

检索责任信息。每个责任范围包含行及其对应的提交信息。

plaintext
GET /projects/:id/repository/files/:file_path/blame

Attribute	Type	Required	Description
file_path	string	yes	URL 编码的新文件完整路径，例如 lib%2Fclass%2Erb。
id	integer or string	yes	项目的 ID 或 URL 编码的项目路径。
range[end]	integer	yes	责任范围的最后一行。
range[start]	integer	yes	责任范围的第一行。
ref	string	yes	分支、标签或提交的名称。使用 HEAD 自动使用默认分支。
range	hash	no	责任范围。

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/13083/repository/files/path%2Fto%2Ffile.rb/blame?ref=main"

响应示例：

json
1[
2  {
3    "commit": {
4      "id": "d42409d56517157c48bf3bd97d3f75974dde19fb",
5      "message": "Add feature\n\nalso fix bug\n",
6      "parent_ids": [
7        "cc6e14f9328fa6d7b5a0d3c30dc2002a3f2a3822"
8      ],
9      "authored_date": "2015-12-18T08:12:22.000Z",
10      "author_name": "John Doe",
11      "author_email": "john.doe@example.com",
12      "committed_date": "2015-12-18T08:12:22.000Z",
13      "committer_name": "John Doe",
14      "committer_email": "john.doe@example.com"
15    },
16    "lines": [
17      "require 'fileutils'",
18      "require 'open3'",
19      ""
20    ]
21  },
22  ...
23]

仅获取文件元数据#

使用 HEAD 方法仅返回文件元数据，如从代码库获取文件中所示：

shell
curl --head --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/13083/repository/files/path%2Fto%2Ffile.rb/blame?ref=main"

响应#

响应示例：

plaintext
1HTTP/1.1 200 OK
2...
3X-Gitlab-Blob-Id: 79f7bbd25901e8334750839545a9bd021f0e4c83
4X-Gitlab-Commit-Id: d5a3ff139356ce33e37e73add446f16869741b50
5X-Gitlab-Content-Sha256: 4c294617b60715c1d218e61164a3abd4808a4284cbc30e6728a01ad9aada4481
6X-Gitlab-Encoding: base64
7X-Gitlab-File-Name: file.rb
8X-Gitlab-File-Path: path/to/file.rb
9X-Gitlab-Last-Commit-Id: 570e7b2abdd848b95f2f578043fc23bd6f6fd24d
10X-Gitlab-Ref: main
11X-Gitlab-Size: 1476
12X-Gitlab-Execute-Filemode: false
13...

请求责任范围#

要请求责任范围，请指定 range[start] 和 range[end] 参数及文件的起始和结束行号。

shell
curl --head --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/13083/repository/files/path%2Fto%2Ffile.rb/blame?ref=main&range[start]=1&range[end]=2"

响应示例：

json
1[
2  {
3    "commit": {
4      "id": "d42409d56517157c48bf3bd97d3f75974dde19fb",
5      "message": "Add feature\n\nalso fix bug\n",
6      "parent_ids": [
7        "cc6e14f9328fa6d7b5a0d3c30dc2002a3f2a3822"
8      ],
9      "authored_date": "2015-12-18T08:12:22.000Z",
10      "author_name": "John Doe",
11      "author_email": "john.doe@example.com",
12      "committed_date": "2015-12-18T08:12:22.000Z",
13      "committer_name": "John Doe",
14      "committer_email": "john.doe@example.com"
15    },
16    "lines": [
17      "require 'fileutils'",
18      "require 'open3'"
19    ]
20  },
21  ...
22]

从代码库获取原始文件#

plaintext
GET /projects/:id/repository/files/:file_path/raw

Attribute	Type	Required	Description
file_path	string	yes	URL 编码的新文件完整路径，例如 lib%2Fclass%2Erb。
id	integer or string	yes	项目的 ID 或 URL 编码的项目路径。
lfs	boolean	no	确定响应是否应为 Git LFS 文件内容，而不是指针。如果文件未被 Git LFS 跟踪，则忽略。默认值为 false。在极狐GitLab 15.7 中引入。
ref	string	no	分支、标签或提交的名称。默认是项目的 HEAD。

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb/raw?ref=main"

如[从代码库获取文件](repository_files.md#get-file-from-repository)，你可以使用 `HEAD` 来仅获取文件元数据。

在代码库中创建新文件#

允许你创建单个文件。要使用单个请求创建多个文件，请参阅提交 API。

plaintext
POST /projects/:id/repository/files/:file_path

Attribute	Type	Required	Description
branch	string	yes	要创建的新分支的名称。提交添加到此分支。
commit_message	string	yes	提交信息。
content	string	yes	文件的内容。
file_path	string	yes	URL 编码的新文件完整路径。例如：lib%2Fclass%2Erb。
id	integer or string	yes	项目的 ID 或 URL 编码的项目路径。
author_email	string	no	提交作者的电子邮件地址。
author_name	string	no	提交作者的姓名。
encoding	string	no	将编码更改为 base64。默认是 text。
execute_filemode	boolean	no	启用或禁用文件的 execute 标志。可以是 true 或 false。
start_branch	string	no	要从中创建新分支的基分支名称。

shell
1curl --request POST \
2  --header 'PRIVATE-TOKEN: <your_access_token>' \
3  --header "Content-Type: application/json" \
4  --data '{"branch": "main", "author_email": "author@example.com", "author_name": "Firstname Lastname",
5            "content": "some content", "commit_message": "create a new file"}' \
6  --url "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb"

响应示例：

json
{
  "file_path": "app/project.rb",
  "branch": "main"
}

更新代码库中现有文件#

允许你更新单个文件。要使用单个请求更新多个文件，请参阅提交 API。

plaintext
PUT /projects/:id/repository/files/:file_path

Attribute	Type	Required	Description
branch	string	yes	要创建的新分支的名称。提交添加到此分支。
commit_message	string	yes	提交信息。
content	string	yes	文件的内容。
file_path	string	yes	URL 编码的新文件完整路径。例如：lib%2Fclass%2Erb。
id	integer or string	yes	项目的 ID 或 URL 编码的项目路径
author_email	string	no	提交作者的电子邮件地址。
author_name	string	no	提交作者的姓名。
encoding	string	no	将编码更改为 base64。默认是 text。
execute_filemode	boolean	no	启用或禁用文件的 execute 标志。可以是 true 或 false。
last_commit_id	string	no	最后已知的文件提交 ID。
start_branch	string	no	要从中创建新分支的基分支名称。

shell
1curl --request PUT \
2  --header 'PRIVATE-TOKEN: <your_access_token>' \
3  --header "Content-Type: application/json" \
4  --data '{"branch": "main", "author_email": "author@example.com", "author_name": "Firstname Lastname",
5       "content": "some content", "commit_message": "update file"}' \
6  --url "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb"

响应示例：

json
{
  "file_path": "app/project.rb",
  "branch": "main"
}

如果提交因任何原因失败，我们会返回一个 400 Bad Request 错误，并附带一个非特定的错误消息。提交失败的可能原因包括：

file_path 包含 /../（尝试目录遍历）。
提交是空的：新文件内容与当前文件内容相同。
在文件编辑过程中，有人使用 git push 更新了分支。

极狐GitLab Shell 具有布尔返回代码，阻止极狐GitLab 指定错误。

删除代码库中现有文件#

删除单个文件。要使用单个请求删除多个文件，请参阅提交 API。

plaintext
DELETE /projects/:id/repository/files/:file_path

Attribute	Type	Required	Description
branch	string	yes	要创建的新分支的名称。提交添加到此分支。
commit_message	string	yes	提交信息。
file_path	string	yes	URL 编码的新文件完整路径。例如：lib%2Fclass%2Erb。
id	integer or string	yes	项目的 ID 或 URL 编码的项目路径。
author_email	string	no	提交作者的电子邮件地址。
author_name	string	no	提交作者的姓名。
last_commit_id	string	no	最后已知的文件提交 ID。
start_branch	string	no	要从中创建新分支的基分支名称。

shell
1curl --request DELETE \
2  --header 'PRIVATE-TOKEN: <your_access_token>' \
3  --header "Content-Type: application/json" \
4  --data '{"branch": "main", "author_email": "author@example.com", "author_name": "Firstname Lastname",
5       "commit_message": "delete file"}' \
6  --url "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb"