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

仓库文件 API

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

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

个人访问令牌的有效范围

个人访问令牌 支持以下范围：

范围 描述
api 允许对仓库文件进行读写访问。
read_api 允许对仓库文件进行读取访问。
read_repository 允许对仓库文件进行读取访问。

从仓库获取文件

允许您获取仓库中文件的信息，如名称、大小和内容。文件内容是 Base64 编码的。如果仓库是公开可访问的，您无需身份验证即可访问此端点。

对于大于 10 MB 的 blob，此端点的速率为每分钟 5 个请求。

GET /projects/:id/repository/files/:file_path
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb?ref=main"
属性 类型 必需 描述
id integer or string yes 项目的 ID 或 URL 编码路径。
file_path string yes 新文件的 URL 编码完整路径，例如 lib%2Fclass%2Erb。
ref string yes 分支、标签或提交的名称。使用 HEAD 自动使用默认分支。

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

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。请参阅 仓库 API 中的获取仓库中的 blob。

示例响应：

{
  "file_name": "key.rb",
  "file_path": "app/models/key.rb",
  "size": 1476,
  "encoding": "base64",
  "content": "IyA9PSBTY2hlbWEgSW5mb3...",
  "content_sha256": "4c294617b60715c1d218e61164a3abd4808a4284cbc30e6728a01ad9aada4481",
  "ref": "main",
  "blob_id": "79f7bbd25901e8334750839545a9bd021f0e4c83",
  "commit_id": "d5a3ff139356ce33e37e73add446f16869741b50",
  "last_commit_id": "570e7b2abdd848b95f2f578043fc23bd6f6fd24d",
  "execute_filemode": false
}

仅获取文件元数据

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

HEAD /projects/:id/repository/files/:file_path
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"

示例响应：

HTTP/1.1 200 OK
...
X-Gitlab-Blob-Id: 79f7bbd25901e8334750839545a9bd021f0e4c83
X-Gitlab-Commit-Id: d5a3ff139356ce33e37e73add446f16869741b50
X-Gitlab-Content-Sha256: 4c294617b60715c1d218e61164a3abd4808a4284cbc30e6728a01ad9aada4481
X-Gitlab-Encoding: base64
X-Gitlab-File-Name: key.rb
X-Gitlab-File-Path: app/models/key.rb
X-Gitlab-Last-Commit-Id: 570e7b2abdd848b95f2f578043fc23bd6f6fd24d
X-Gitlab-Ref: main
X-Gitlab-Size: 1476
X-Gitlab-Execute-Filemode: false
...

从仓库获取文件 blame

获取 blame 信息。每个 blame 范围包含行及其对应的提交信息。

GET /projects/:id/repository/files/:file_path/blame
属性 类型 必需 描述
file_path string yes 新文件的 URL 编码完整路径，例如 lib%2Fclass%2Erb。
id integer or string yes 项目的 ID 或 URL 编码路径。
range[end] integer yes 要 blame 的范围的最后一行。
range[start] integer yes 要 blame 的范围的第一行。
ref string yes 分支、标签或提交的名称。使用 HEAD 自动使用默认分支。
range hash no Blame 范围。 
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"

示例响应：

[
  {
    "commit": {
      "id": "d42409d56517157c48bf3bd97d3f75974dde19fb",
      "message": "Add feature\n\nalso fix bug\n",
      "parent_ids": [
        "cc6e14f9328fa6d7b5a0d3c30dc2002a3f2a3822"
      ],
      "authored_date": "2015-12-18T08:12:22.000Z",
      "author_name": "John Doe",
      "author_email": "[email protected]",
      "committed_date": "2015-12-18T08:12:22.000Z",
      "committer_name": "John Doe",
      "committer_email": "[email protected]"
    },
    "lines": [
      "require 'fileutils'",
      "require 'open3'",
      ""
    ]
  },
  ...
]

仅获取文件元数据

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

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"

响应

示例响应：

HTTP/1.1 200 OK
...
X-Gitlab-Blob-Id: 79f7bbd25901e8334750839545a9bd021f0e4c83
X-Gitlab-Commit-Id: d5a3ff139356ce33e37e73add446f16869741b50
X-Gitlab-Content-Sha256: 4c294617b60715c1d218e61164a3abd4808a4284cbc30e6728a01ad9aada4481
X-Gitlab-Encoding: base64
X-Gitlab-File-Name: file.rb
X-Gitlab-File-Path: path/to/file.rb
X-Gitlab-Last-Commit-Id: 570e7b2abdd848b95f2f578043fc23bd6f6fd24d
X-Gitlab-Ref: main
X-Gitlab-Size: 1476
X-Gitlab-Execute-Filemode: false
...

请求 blame 范围

要请求 blame 范围，请指定 range[start] 和 range[end] 参数，并设置文件中起始和结束的行号。

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"

示例响应：

[
  {
    "commit": {
      "id": "d42409d56517157c48bf3bd97d3f75974dde19fb",
      "message": "Add feature\n\nalso fix bug\n",
      "parent_ids": [
        "cc6e14f9328fa6d7b5a0d3c30dc2002a3f2a3822"
      ],
      "authored_date": "2015-12-18T08:12:22.000Z",
      "author_name": "John Doe",
      "author_email": "[email protected]",
      "committed_date": "2015-12-18T08:12:22.000Z",
      "committer_name": "John Doe",
      "committer_email": "[email protected]"
    },
    "lines": [
      "require 'fileutils'",
      "require 'open3'"
    ]
  },
  ...
]

从仓库获取原始文件

GET /projects/:id/repository/files/:file_path/raw
属性 类型 必需 描述
file_path string yes 新文件的 URL 编码完整路径，例如 lib%2Fclass%2Erb。
id integer or string yes 项目的 ID 或 URL 编码路径。
lfs boolean no 确定响应是否应为 Git LFS 文件内容，而不是指针。如果文件未被 Git LFS 跟踪，则忽略。默认为 false。
ref string no 分支、标签或提交的名称。默认为项目的 HEAD。 
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"

与 从仓库获取文件 类似，您可以使用 HEAD 来仅获取文件元数据。

在仓库中创建新文件

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

POST /projects/:id/repository/files/:file_path
属性 类型 必需 描述
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 用于创建新分支的基础分支的名称。 
curl --request POST \
  --header 'PRIVATE-TOKEN: <your_access_token>' \
  --header "Content-Type: application/json" \
  --data '{"branch": "main", "author_email": "[email protected]", "author_name": "Firstname Lastname",
            "content": "some content", "commit_message": "create a new file"}' \
  --url "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb"

示例响应：

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

更新仓库中的现有文件

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

PUT /projects/:id/repository/files/:file_path
属性 类型 必需 描述
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 用于创建新分支的基础分支的名称。 
curl --request PUT \
  --header 'PRIVATE-TOKEN: <your_access_token>' \
  --header "Content-Type: application/json" \
  --data '{"branch": "main", "author_email": "[email protected]", "author_name": "Firstname Lastname",
       "content": "some content", "commit_message": "update file"}' \
  --url "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb"

示例响应：

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

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

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

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

删除仓库中的现有文件

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

DELETE /projects/:id/repository/files/:file_path
属性 类型 必需 描述
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 用于创建新分支的基础分支的名称。 
curl --request DELETE \
  --header 'PRIVATE-TOKEN: <your_access_token>' \
  --header "Content-Type: application/json" \
  --data '{"branch": "main", "author_email": "[email protected]", "author_name": "Firstname Lastname",
       "commit_message": "delete file"}' \
  --url "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb"