搜索 API - GitLab - GitLab 文档中心

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

Offering: JihuLab.com，私有化部署

使用此 API 在极狐GitLab 中搜索。每次调用此 API 都需要进行身份验证。

部分范围可用于基础搜索。当启用高级搜索或精确代码搜索时，全局搜索、群组搜索和项目搜索操作还可使用其他范围。

如果您想改用基础搜索，请参阅指定搜索类型。

使用高级搜索时，您最多可以检索 10,000 条结果（page 乘以 per_page）。超过该限制的请求会返回一个空页面，且不包含 next 链接，因此，如果客户端一直分页直到收到空响应，就会在该限制处停止。基础搜索和精确代码搜索不受影响。在 Elasticsearch 集群上提高 index.max_result_window 不会提高该限制，因为极狐GitLab 不会读取该设置。

搜索实例#

在整个极狐GitLab 实例中搜索词条。响应取决于所请求的范围。

plaintext
GET /search

属性	类型	是否必需	描述
scope	string	是	要搜索的范围。取值包括 projects、groups、issues、work_items、merge_requests、milestones、snippet_titles 和 users。其他范围包括 wiki_blobs、commits、blobs 和 notes。
search	string	是	搜索词条。
search_type	string	否	要使用的搜索类型。取值包括 basic、advanced 和 zoekt。
confidential	boolean	否	按机密性筛选。支持 issues 和 work_items 范围；其他范围将被忽略。
exclude_forks	boolean	否	从搜索中排除 forked 项目。适用于精确代码搜索。如果未设置，将排除 forks。引入于极狐GitLab 18.7。
regex	boolean	否	使用正则表达式搜索代码。适用于精确代码搜索。如果未设置，将使用正则表达式。引入于极狐GitLab 18.9。
fields	array of strings	否	您希望搜索的字段数组，允许的值仅为 title。仅支持 issues 和 merge_requests 范围。仅限专业版和旗舰版。
include_archived	boolean	否	在搜索中包含已归档项目。默认为 false。引入于极狐GitLab 18.7。
num_context_lines	integer	否	结果中每个匹配项周围包含的上下文行数。仅适用于高级搜索和精确代码搜索。引入于极狐GitLab 18.11。
state	string	否	按状态筛选。支持 issues、work_items 和 merge_requests 范围；其他范围将被忽略。
type	array of strings	否	按类型筛选工作项。仅适用于 work_items 范围。可用类型：issue、task、epic、incident、test_case、requirement、objective、key_result、ticket。
order_by	string	否	允许的值仅为 created_at。如果未设置，基础搜索的结果按 created_at 降序排序，高级搜索则按最相关的文档排序。
sort	string	否	允许的值仅为 asc 或 desc。如果未设置，基础搜索的结果按 created_at 降序排序，高级搜索则按最相关的文档排序。

范围：projects#

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/search?scope=projects&search=flight"

示例响应：

json
1[
2  {
3    "id": 6,
4    "description": "Nobis sed ipsam vero quod cupiditate veritatis hic.",
5    "name": "Flight",
6    "name_with_namespace": "Twitter / Flight",
7    "path": "flight",
8    "path_with_namespace": "twitter/flight",
9    "created_at": "2017-09-05T07:58:01.621Z",
10    "default_branch": "main",
11    "tag_list":[], //deprecated, use `topics` instead
12    "topics":[],
13    "ssh_url_to_repo": "ssh://jarka@localhost:2222/twitter/flight.git",
14    "http_url_to_repo": "http://localhost:3000/twitter/flight.git",
15    "web_url": "http://localhost:3000/twitter/flight",
16    "readme_url": "http://localhost:3000/twitter/flight/-/blob/main/README.md",
17    "avatar_url": null,
18    "star_count": 0,
19    "forks_count": 0,
20    "last_activity_at": "2018-01-31T09:56:30.902Z"
21  }
22]

范围：groups#

此范围的可用性由功能标志控制。

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/search?scope=groups&search=flight"

示例响应：

json
1[
2  {
3    "id": 3,
4    "web_url": "http://localhost:3000/groups/flightjs",
5    "name": "Flightjs"
6  }
7]

范围：issues#

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/search?scope=issues&search=file"

示例响应：

json
1[
2  {
3    "id": 83,
4    "iid": 1,
5    "project_id": 12,
6    "title": "Add file",
7    "description": "Add first file",
8    "state": "opened",
9    "created_at": "2018-01-24T06:02:15.514Z",
10    "updated_at": "2018-02-06T12:36:23.263Z",
11    "closed_at": null,
12    "labels":[],
13    "milestone": null,
14    "assignees": [{
15      "id": 20,
16      "name": "Ceola Deckow",
17      "username": "sammy.collier",
18      "state": "active",
19      "avatar_url": "https://www.gravatar.com/avatar/c23d85a4f50e0ea76ab739156c639231?s=80&d=identicon",
20      "web_url": "http://localhost:3000/sammy.collier"
21    }],
22    "author": {
23      "id": 1,
24      "name": "Administrator",
25      "username": "root",
26      "state": "active",
27      "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
28      "web_url": "http://localhost:3000/root"
29    },
30    "assignee": {
31      "id": 20,
32      "name": "Ceola Deckow",
33      "username": "sammy.collier",
34      "state": "active",
35      "avatar_url": "https://www.gravatar.com/avatar/c23d85a4f50e0ea76ab739156c639231?s=80&d=identicon",
36      "web_url": "http://localhost:3000/sammy.collier"
37    },
38    "user_notes_count": 0,
39    "upvotes": 0,
40    "downvotes": 0,
41    "due_date": null,
42    "confidential": false,
43    "discussion_locked": null,
44    "web_url": "http://localhost:3000/h5bp/7bp/subgroup-prj/issues/1",
45    "time_stats": {
46      "time_estimate": 0,
47      "total_time_spent": 0,
48      "human_time_estimate": null,
49      "human_total_time_spent": null
50    }
51  }
52]

assignee 列已弃用。为符合极狐GitLab 企业版 API，它显示为单元素数组 assignees。

范围：work_items#

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/search?scope=work_items&search=migrate"

示例响应：

json
1[
2  {
3    "id": 142,
4    "iid": 9,
5    "project_id": 12,
6    "title": "Migrate to new database",
7    "description": "Database migration task",
8    "state": "opened",
9    "created_at": "2018-03-15T08:12:31.489Z",
10    "updated_at": "2018-03-20T14:22:18.371Z",
11    "closed_at": null,
12    "labels": ["backend"],
13    "milestone": null,
14    "assignees": [{
15      "id": 25,
16      "name": "John Doe",
17      "username": "john.doe",
18      "state": "active",
19      "avatar_url": "https://www.gravatar.com/avatar/a1b2c3d4e5f6g7h8i9j0?s=80&d=identicon",
20      "web_url": "http://localhost:3000/john.doe"
21    }],
22    "author": {
23      "id": 1,
24      "name": "Administrator",
25      "username": "root",
26      "state": "active",
27      "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
28      "web_url": "http://localhost:3000/root"
29    },
30    "type": "TASK",
31    "user_notes_count": 2,
32    "upvotes": 1,
33    "downvotes": 0,
34    "due_date": "2018-04-01",
35    "confidential": false,
36    "discussion_locked": null,
37    "web_url": "http://localhost:3000/my-group/my-project/-/work_items/9",
38    "time_stats": {
39      "time_estimate": 0,
40      "total_time_spent": 0,
41      "human_time_estimate": null,
42      "human_total_time_spent": null
43    }
44  }
45]

您可以使用 type 参数按类型筛选工作项：

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/search?scope=work_items&search=backend&type[]=task&type[]=issue"

范围：merge_requests#

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/search?scope=merge_requests&search=file"

示例响应：

json
1[
2  {
3    "id": 56,
4    "iid": 8,
5    "project_id": 6,
6    "title": "Add first file",
7    "description": "This is a test MR to add file",
8    "state": "opened",
9    "created_at": "2018-01-22T14:21:50.830Z",
10    "updated_at": "2018-02-06T12:40:33.295Z",
11    "target_branch": "main",
12    "source_branch": "jaja-test",
13    "upvotes": 0,
14    "downvotes": 0,
15    "author": {
16      "id": 1,
17      "name": "Administrator",
18      "username": "root",
19      "state": "active",
20      "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
21      "web_url": "http://localhost:3000/root"
22    },
23    "assignee": {
24      "id": 5,
25      "name": "Jacquelyn Kutch",
26      "username": "abigail",
27      "state": "active",
28      "avatar_url": "https://www.gravatar.com/avatar/3138c66095ee4bd11a508c2f7f7772da?s=80&d=identicon",
29      "web_url": "http://localhost:3000/abigail"
30    },
31    "source_project_id": 6,
32    "target_project_id": 6,
33    "labels": [
34      "ruby",
35      "tests"
36    ],
37    "draft": false,
38    "work_in_progress": false,
39    "milestone": {
40      "id": 13,
41      "iid": 3,
42      "project_id": 6,
43      "title": "v2.0",
44      "description": "Qui aut qui eos dolor beatae itaque tempore molestiae.",
45      "state": "active",
46      "created_at": "2017-09-05T07:58:29.099Z",
47      "updated_at": "2017-09-05T07:58:29.099Z",
48      "due_date": null,
49      "start_date": null
50    },
51    "merge_when_pipeline_succeeds": false,
52    "merge_status": "can_be_merged",
53    "sha": "78765a2d5e0a43585945c58e61ba2f822e4d090b",
54    "merge_commit_sha": null,
55    "squash_commit_sha": null,
56    "user_notes_count": 0,
57    "discussion_locked": null,
58    "should_remove_source_branch": null,
59    "force_remove_source_branch": true,
60    "web_url": "http://localhost:3000/twitter/flight/merge_requests/8",
61    "time_stats": {
62      "time_estimate": 0,
63      "total_time_spent": 0,
64      "human_time_estimate": null,
65      "human_total_time_spent": null
66    }
67  }
68]

范围：milestones#

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/search?scope=milestones&search=release"

示例响应：

json
1[
2  {
3    "id": 44,
4    "iid": 1,
5    "project_id": 12,
6    "title": "next release",
7    "description": "Next release milestone",
8    "state": "active",
9    "created_at": "2018-02-06T12:43:39.271Z",
10    "updated_at": "2018-02-06T12:44:01.298Z",
11    "due_date": "2018-04-18",
12    "start_date": "2018-02-04"
13  }
14]

范围：snippet_titles#

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/search?scope=snippet_titles&search=sample"

示例响应：

json
1[
2  {
3    "id": 50,
4    "title": "Sample file",
5    "file_name": "file.rb",
6    "description": "Simple ruby file",
7    "author": {
8      "id": 1,
9      "name": "Administrator",
10      "username": "root",
11      "state": "active",
12      "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
13      "web_url": "http://localhost:3000/root"
14    },
15    "updated_at": "2018-02-06T12:49:29.104Z",
16    "created_at": "2017-11-28T08:20:18.071Z",
17    "project_id": 9,
18    "web_url": "http://localhost:3000/root/jira-test/snippets/50"
19  }
20]

范围：users#

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/search?scope=users&search=doe"

示例响应：

json
1[
2  {
3    "id": 1,
4    "name": "John Doe1",
5    "username": "user1",
6    "state": "active",
7    "avatar_url": "http://www.gravatar.com/avatar/c922747a93b40d1ea88262bf1aebee62?s=80&d=identicon",
8    "web_url": "http://localhost/user1"
9  }
10]

范围：wiki_blobs#

Tier: 专业版，旗舰版

使用此范围搜索 Wiki。

此范围仅在启用高级搜索时可用。

此范围可使用以下筛选条件：

filename
path
extension

要使用筛选条件，请将其包含在查询中（例如 a query filename:some_name*）。

您可以使用通配符（*）进行 glob 匹配。

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/search?scope=wiki_blobs&search=bye"

示例响应：

json
1
2[
3  {
4    "basename": "home",
5    "data": "hello\n\nand bye\n\nend",
6    "path": "home.md",
7    "filename": "home.md",
8    "id": null,
9    "ref": "main",
10    "startline": 5,
11    "project_id": 6,
12    "group_id": null
13  }
14]

filename 已弃用，请改用 path。两者都返回代码仓库中文件的完整路径，但将来 filename 将仅表示文件名，而非完整路径。有关详情，请参阅议题 34521。

范围：commits#

Tier: 专业版，旗舰版

此范围仅在启用高级搜索时可用。

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/search?scope=commits&search=bye"

示例响应：

json
1
2[
3  {
4  "id": "4109c2d872d5fdb1ed057400d103766aaea97f98",
5  "short_id": "4109c2d8",
6  "title": "goodbye $.browser",
7  "created_at": "2013-02-18T22:02:54.000Z",
8  "parent_ids": [
9    "59d05353ab575bcc2aa958fe1782e93297de64c9"
10  ],
11  "message": "goodbye $.browser\n",
12  "author_name": "angus croll",
13  "author_email": "anguscroll@gmail.com",
14  "authored_date": "2013-02-18T22:02:54.000Z",
15  "committer_name": "angus croll",
16  "committer_email": "anguscroll@gmail.com",
17  "committed_date": "2013-02-18T22:02:54.000Z",
18  "project_id": 6
19  }
20]

范围：blobs#

Tier: 专业版，旗舰版

使用此范围搜索代码。

此范围仅在启用高级搜索或精确代码搜索时可用。

此范围可使用以下筛选条件：

filename
path
extension

要使用筛选条件，请将其包含在查询中（例如 a query filename:some_name*）。

您可以使用通配符（*）进行 glob 匹配。

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/search?scope=blobs&search=installation"

示例响应：

json
1
2[
3  {
4    "basename": "README",
5    "data": "```\n\n## Installation\n\nQuick start using the [pre-built",
6    "path": "README.md",
7    "filename": "README.md",
8    "id": null,
9    "ref": "main",
10    "startline": 46,
11    "project_id": 6
12  }
13]

filename 已弃用，请改用 path。两者都返回代码仓库中文件的完整路径，但将来 filename 将仅表示文件名，而非完整路径。有关详情，请参阅议题 34521。 Elasticsearch 语法在精确代码搜索中可能无法正常工作。对于精确代码搜索，请将 Elasticsearch 通配符查询替换为正则表达式。有关详情，请参阅议题 521686。

范围：notes#

Tier: 专业版，旗舰版

此范围仅在启用高级搜索时可用。

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/search?scope=notes&search=maxime"

示例响应：

json
1[
2  {
3    "id": 191,
4    "body": "Harum maxime consequuntur et et deleniti assumenda facilis.",
5    "attachment": null,
6    "author": {
7      "id": 23,
8      "name": "User 1",
9      "username": "user1",
10      "state": "active",
11      "avatar_url": "https://www.gravatar.com/avatar/111d68d06e2d317b5a59c2c6c5bad808?s=80&d=identicon",
12      "web_url": "http://localhost:3000/user1"
13    },
14    "created_at": "2017-09-05T08:01:32.068Z",
15    "updated_at": "2017-09-05T08:01:32.068Z",
16    "system": false,
17    "noteable_id": 22,
18    "noteable_type": "Issue",
19    "project_id": 6,
20    "noteable_iid": 2
21  }
22]

搜索群组#

在指定群组中搜索词条。

如果用户不是群组成员且该群组为私有，则对该群组发起 GET 请求会返回 404 Not Found 状态码。

plaintext
GET /groups/:id/search

属性	类型	是否必需	描述
id	integer or string	是	群组的 ID 或 URL 编码路径。
scope	string	是	要搜索的范围。取值包括 projects、groups、issues、work_items、merge_requests、milestones 和 users。其他范围包括 wiki_blobs、commits、blobs 和 notes。
search	string	是	搜索词条。
search_type	string	否	要使用的搜索类型。取值包括 basic、advanced 和 zoekt。
confidential	boolean	否	按机密性筛选。支持 issues 和 work_items 范围；其他范围将被忽略。
exclude_forks	boolean	否	从搜索中排除 forked 项目。适用于精确代码搜索。如果未设置，将排除 forks。引入于极狐GitLab 18.7。
regex	boolean	否	使用正则表达式搜索代码。适用于精确代码搜索。如果未设置，将使用正则表达式。引入于极狐GitLab 18.9。
fields	array of strings	否	您希望搜索的字段数组，允许的值仅为 title。仅支持 issues 和 merge_requests 范围。仅限专业版和旗舰版。
include_archived	boolean	否	在搜索中包含已归档项目。默认为 false。引入于极狐GitLab 18.7。
num_context_lines	integer	否	结果中每个匹配项周围包含的上下文行数。仅适用于高级搜索和精确代码搜索。引入于极狐GitLab 18.11。
state	string	否	按状态筛选。支持 issues、work_items 和 merge_requests 范围；其他范围将被忽略。
type	array of strings	否	按类型筛选工作项。仅适用于 work_items 范围。可用类型：issue、task、epic、incident、test_case、requirement、objective、key_result、ticket。
order_by	string	否	允许的值仅为 created_at。如果未设置，基础搜索的结果按 created_at 降序排序，高级搜索则按最相关的文档排序。
sort	string	否	允许的值仅为 asc 或 desc。如果未设置，基础搜索的结果按 created_at 降序排序，高级搜索则按最相关的文档排序。

响应取决于所请求的范围。

范围：projects#

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/3/search?scope=projects&search=flight"

示例响应：

json
1[
2  {
3    "id": 6,
4    "description": "Nobis sed ipsam vero quod cupiditate veritatis hic.",
5    "name": "Flight",
6    "name_with_namespace": "Twitter / Flight",
7    "path": "flight",
8    "path_with_namespace": "twitter/flight",
9    "created_at": "2017-09-05T07:58:01.621Z",
10    "default_branch": "main",
11    "tag_list":[], //deprecated, use `topics` instead
12    "topics":[],
13    "ssh_url_to_repo": "ssh://jarka@localhost:2222/twitter/flight.git",
14    "http_url_to_repo": "http://localhost:3000/twitter/flight.git",
15    "web_url": "http://localhost:3000/twitter/flight",
16    "readme_url": "http://localhost:3000/twitter/flight/-/blob/main/README.md",
17    "avatar_url": null,
18    "star_count": 0,
19    "forks_count": 0,
20    "last_activity_at": "2018-01-31T09:56:30.902Z"
21  }
22]

范围：groups#

此范围的可用性由功能标志控制。

此范围返回指定群组的子群组，而非该群组本身。

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/3/search?scope=groups&search=flight"

示例响应：

json
1[
2  {
3    "id": 8,
4    "web_url": "http://localhost:3000/groups/flightjs/flight-crew",
5    "name": "Flight Crew"
6  }
7]

范围：issues#

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/3/search?scope=issues&search=file"

示例响应：

json
1[
2  {
3    "id": 83,
4    "iid": 1,
5    "project_id": 12,
6    "title": "Add file",
7    "description": "Add first file",
8    "state": "opened",
9    "created_at": "2018-01-24T06:02:15.514Z",
10    "updated_at": "2018-02-06T12:36:23.263Z",
11    "closed_at": null,
12    "labels":[],
13    "milestone": null,
14    "assignees": [{
15      "id": 20,
16      "name": "Ceola Deckow",
17      "username": "sammy.collier",
18      "state": "active",
19      "avatar_url": "https://www.gravatar.com/avatar/c23d85a4f50e0ea76ab739156c639231?s=80&d=identicon",
20      "web_url": "http://localhost:3000/sammy.collier"
21    }],
22    "author": {
23      "id": 1,
24      "name": "Administrator",
25      "username": "root",
26      "state": "active",
27      "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
28      "web_url": "http://localhost:3000/root"
29    },
30    "assignee": {
31      "id": 20,
32      "name": "Ceola Deckow",
33      "username": "sammy.collier",
34      "state": "active",
35      "avatar_url": "https://www.gravatar.com/avatar/c23d85a4f50e0ea76ab739156c639231?s=80&d=identicon",
36      "web_url": "http://localhost:3000/sammy.collier"
37    },
38    "user_notes_count": 0,
39    "upvotes": 0,
40    "downvotes": 0,
41    "due_date": null,
42    "confidential": false,
43    "discussion_locked": null,
44    "web_url": "http://localhost:3000/h5bp/7bp/subgroup-prj/issues/1",
45    "time_stats": {
46      "time_estimate": 0,
47      "total_time_spent": 0,
48      "human_time_estimate": null,
49      "human_total_time_spent": null
50    }
51  }
52]

assignee 列已弃用。它现在是一个单元素 assignees 数组。

范围：work_items#

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/3/search?scope=work_items&search=migrate"

示例响应：

json
1[
2  {
3    "id": 142,
4    "iid": 9,
5    "project_id": 12,
6    "title": "Migrate to new database",
7    "description": "Database migration task",
8    "state": "opened",
9    "created_at": "2018-03-15T08:12:31.489Z",
10    "updated_at": "2018-03-20T14:22:18.371Z",
11    "closed_at": null,
12    "labels": ["backend"],
13    "milestone": null,
14    "assignees": [{
15      "id": 25,
16      "name": "John Doe",
17      "username": "john.doe",
18      "state": "active",
19      "avatar_url": "https://www.gravatar.com/avatar/a1b2c3d4e5f6g7h8i9j0?s=80&d=identicon",
20      "web_url": "http://localhost:3000/john.doe"
21    }],
22    "author": {
23      "id": 1,
24      "name": "Administrator",
25      "username": "root",
26      "state": "active",
27      "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
28      "web_url": "http://localhost:3000/root"
29    },
30    "type": "TASK",
31    "user_notes_count": 2,
32    "upvotes": 1,
33    "downvotes": 0,
34    "due_date": "2018-04-01",
35    "confidential": false,
36    "discussion_locked": null,
37    "web_url": "http://localhost:3000/my-group/my-project/-/work_items/9",
38    "time_stats": {
39      "time_estimate": 0,
40      "total_time_spent": 0,
41      "human_time_estimate": null,
42      "human_total_time_spent": null
43    }
44  }
45]

您可以使用 type 参数按类型筛选工作项：

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/3/search?scope=work_items&search=backend&type[]=task&type[]=issue"

范围：merge_requests#

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/3/search?scope=merge_requests&search=file"

示例响应：

json
1[
2  {
3    "id": 56,
4    "iid": 8,
5    "project_id": 6,
6    "title": "Add first file",
7    "description": "This is a test MR to add file",
8    "state": "opened",
9    "created_at": "2018-01-22T14:21:50.830Z",
10    "updated_at": "2018-02-06T12:40:33.295Z",
11    "target_branch": "main",
12    "source_branch": "jaja-test",
13    "upvotes": 0,
14    "downvotes": 0,
15    "author": {
16      "id": 1,
17      "name": "Administrator",
18      "username": "root",
19      "state": "active",
20      "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
21      "web_url": "http://localhost:3000/root"
22    },
23    "assignee": {
24      "id": 5,
25      "name": "Jacquelyn Kutch",
26      "username": "abigail",
27      "state": "active",
28      "avatar_url": "https://www.gravatar.com/avatar/3138c66095ee4bd11a508c2f7f7772da?s=80&d=identicon",
29      "web_url": "http://localhost:3000/abigail"
30    },
31    "source_project_id": 6,
32    "target_project_id": 6,
33    "labels": [
34      "ruby",
35      "tests"
36    ],
37    "draft": false,
38    "work_in_progress": false,
39    "milestone": {
40      "id": 13,
41      "iid": 3,
42      "project_id": 6,
43      "title": "v2.0",
44      "description": "Qui aut qui eos dolor beatae itaque tempore molestiae.",
45      "state": "active",
46      "created_at": "2017-09-05T07:58:29.099Z",
47      "updated_at": "2017-09-05T07:58:29.099Z",
48      "due_date": null,
49      "start_date": null
50    },
51    "merge_when_pipeline_succeeds": false,
52    "merge_status": "can_be_merged",
53    "sha": "78765a2d5e0a43585945c58e61ba2f822e4d090b",
54    "merge_commit_sha": null,
55    "squash_commit_sha": null,
56    "user_notes_count": 0,
57    "discussion_locked": null,
58    "should_remove_source_branch": null,
59    "force_remove_source_branch": true,
60    "web_url": "http://localhost:3000/twitter/flight/merge_requests/8",
61    "time_stats": {
62      "time_estimate": 0,
63      "total_time_spent": 0,
64      "human_time_estimate": null,
65      "human_total_time_spent": null
66    }
67  }
68]

范围：milestones#

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/3/search?scope=milestones&search=release"

示例响应：

json
1[
2  {
3    "id": 44,
4    "iid": 1,
5    "project_id": 12,
6    "title": "next release",
7    "description": "Next release milestone",
8    "state": "active",
9    "created_at": "2018-02-06T12:43:39.271Z",
10    "updated_at": "2018-02-06T12:44:01.298Z",
11    "due_date": "2018-04-18",
12    "start_date": "2018-02-04"
13  }
14]

范围：users#

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/3/search?scope=users&search=doe"

示例响应：

json
1[
2  {
3    "id": 1,
4    "name": "John Doe1",
5    "username": "user1",
6    "state": "active",
7    "avatar_url": "http://www.gravatar.com/avatar/c922747a93b40d1ea88262bf1aebee62?s=80&d=identicon",
8    "web_url": "http://localhost/user1"
9  }
10]

范围：wiki_blobs#

Tier: 专业版，旗舰版

使用此范围搜索 Wiki。

此范围仅在启用高级搜索时可用。

此范围可使用以下筛选条件：

filename
path
extension

要使用筛选条件，请将其包含在查询中（例如 a query filename:some_name*）。

您可以使用通配符（*）进行 glob 匹配。

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/6/search?scope=wiki_blobs&search=bye"

示例响应：

json
1
2[
3  {
4    "basename": "home",
5    "data": "hello\n\nand bye\n\nend",
6    "path": "home.md",
7    "filename": "home.md",
8    "id": null,
9    "ref": "main",
10    "startline": 5,
11    "project_id": 6,
12    "group_id": 1
13  }
14]

filename 已弃用，请改用 path。两者都返回代码仓库中文件的完整路径，但将来 filename 将仅表示文件名，而非完整路径。有关详情，请参阅议题 34521。

范围：commits#

Tier: 专业版，旗舰版

此范围仅在启用高级搜索时可用。

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/6/search?scope=commits&search=bye"

示例响应：

json
1
2[
3  {
4  "id": "4109c2d872d5fdb1ed057400d103766aaea97f98",
5  "short_id": "4109c2d8",
6  "title": "goodbye $.browser",
7  "created_at": "2013-02-18T22:02:54.000Z",
8  "parent_ids": [
9    "59d05353ab575bcc2aa958fe1782e93297de64c9"
10  ],
11  "message": "goodbye $.browser\n",
12  "author_name": "angus croll",
13  "author_email": "anguscroll@gmail.com",
14  "authored_date": "2013-02-18T22:02:54.000Z",
15  "committer_name": "angus croll",
16  "committer_email": "anguscroll@gmail.com",
17  "committed_date": "2013-02-18T22:02:54.000Z",
18  "project_id": 6
19  }
20]

范围：blobs#

Tier: 专业版，旗舰版

使用此范围搜索代码。

此范围仅在启用高级搜索或精确代码搜索时可用。

此范围可使用以下筛选条件：

filename
path
extension

要使用筛选条件，请将其包含在查询中（例如 a query filename:some_name*）。

您可以使用通配符（*）进行 glob 匹配。

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/6/search?scope=blobs&search=installation"

示例响应：

json
1
2[
3  {
4    "basename": "README",
5    "data": "```\n\n## Installation\n\nQuick start using the [pre-built",
6    "path": "README.md",
7    "filename": "README.md",
8    "id": null,
9    "ref": "main",
10    "startline": 46,
11    "project_id": 6
12  }
13]

范围：notes#

Tier: 专业版，旗舰版

此范围仅在启用高级搜索时可用。

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/6/search?scope=notes&search=maxime"

示例响应：

json
1[
2  {
3    "id": 191,
4    "body": "Harum maxime consequuntur et et deleniti assumenda facilis.",
5    "attachment": null,
6    "author": {
7      "id": 23,
8      "name": "User 1",
9      "username": "user1",
10      "state": "active",
11      "avatar_url": "https://www.gravatar.com/avatar/111d68d06e2d317b5a59c2c6c5bad808?s=80&d=identicon",
12      "web_url": "http://localhost:3000/user1"
13    },
14    "created_at": "2017-09-05T08:01:32.068Z",
15    "updated_at": "2017-09-05T08:01:32.068Z",
16    "system": false,
17    "noteable_id": 22,
18    "noteable_type": "Issue",
19    "project_id": 6,
20    "noteable_iid": 2
21  }
22]

搜索项目#

在指定项目中搜索词条。

如果用户不是项目成员且该项目为私有，则对该项目发起 GET 请求会返回 404 状态码。

plaintext
GET /projects/:id/search

属性	类型	是否必需	描述
id	integer or string	是	项目的 ID 或 URL 编码路径。
scope	string	是	要搜索的范围。取值包括 issues、work_items、merge_requests、milestones 和 users。其他范围包括 wiki_blobs、commits、blobs 和 notes。
search	string	是	搜索词条。
search_type	string	否	要使用的搜索类型。取值包括 basic、advanced 和 zoekt。
confidential	boolean	否	按机密性筛选。支持 issues 和 work_items 范围；其他范围将被忽略。
regex	boolean	否	使用正则表达式搜索代码。适用于精确代码搜索。如果未设置，将使用正则表达式。引入于极狐GitLab 18.9。
fields	array of strings	否	您希望搜索的字段数组，允许的值仅为 title。仅支持 issues 和 merge_requests 范围。仅限专业版和旗舰版。
num_context_lines	integer	否	结果中每个匹配项周围包含的上下文行数。仅适用于高级搜索和精确代码搜索。引入于极狐GitLab 18.11。
ref	string	否	要搜索的代码仓库分支或标签的名称。默认使用项目的默认分支。仅适用于 blobs、commits 和 wiki_blobs 范围。
state	string	否	按状态筛选。支持 issues、work_items 和 merge_requests 范围；其他范围将被忽略。
type	array of strings	否	按类型筛选工作项。仅适用于 work_items 范围。可用类型：issue、task、epic、incident、test_case、requirement、objective、key_result、ticket。
order_by	string	否	允许的值仅为 created_at。如果未设置，基础搜索的结果按 created_at 降序排序，高级搜索则按最相关的文档排序。
sort	string	否	允许的值仅为 asc 或 desc。如果未设置，基础搜索的结果按 created_at 降序排序，高级搜索则按最相关的文档排序。

响应取决于所请求的范围。

范围：issues#

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/12/search?scope=issues&search=file"

示例响应：

json
1[
2  {
3    "id": 83,
4    "iid": 1,
5    "project_id": 12,
6    "title": "Add file",
7    "description": "Add first file",
8    "state": "opened",
9    "created_at": "2018-01-24T06:02:15.514Z",
10    "updated_at": "2018-02-06T12:36:23.263Z",
11    "closed_at": null,
12    "labels":[],
13    "milestone": null,
14    "assignees": [{
15      "id": 20,
16      "name": "Ceola Deckow",
17      "username": "sammy.collier",
18      "state": "active",
19      "avatar_url": "https://www.gravatar.com/avatar/c23d85a4f50e0ea76ab739156c639231?s=80&d=identicon",
20      "web_url": "http://localhost:3000/sammy.collier"
21    }],
22    "author": {
23      "id": 1,
24      "name": "Administrator",
25      "username": "root",
26      "state": "active",
27      "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
28      "web_url": "http://localhost:3000/root"
29    },
30    "assignee": {
31      "id": 20,
32      "name": "Ceola Deckow",
33      "username": "sammy.collier",
34      "state": "active",
35      "avatar_url": "https://www.gravatar.com/avatar/c23d85a4f50e0ea76ab739156c639231?s=80&d=identicon",
36      "web_url": "http://localhost:3000/sammy.collier"
37    },
38    "user_notes_count": 0,
39    "upvotes": 0,
40    "downvotes": 0,
41    "due_date": null,
42    "confidential": false,
43    "discussion_locked": null,
44    "web_url": "http://localhost:3000/h5bp/7bp/subgroup-prj/issues/1",
45    "time_stats": {
46      "time_estimate": 0,
47      "total_time_spent": 0,
48      "human_time_estimate": null,
49      "human_total_time_spent": null
50    }
51  }
52]

assignee 列已弃用。它现在是一个单元素 assignees 数组。

范围：work_items#

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/12/search?scope=work_items&search=migrate"

示例响应：

json
1[
2  {
3    "id": 142,
4    "iid": 9,
5    "project_id": 12,
6    "title": "Migrate to new database",
7    "description": "Database migration task",
8    "state": "opened",
9    "created_at": "2018-03-15T08:12:31.489Z",
10    "updated_at": "2018-03-20T14:22:18.371Z",
11    "closed_at": null,
12    "labels": ["backend"],
13    "milestone": null,
14    "assignees": [{
15      "id": 25,
16      "name": "John Doe",
17      "username": "john.doe",
18      "state": "active",
19      "avatar_url": "https://www.gravatar.com/avatar/a1b2c3d4e5f6g7h8i9j0?s=80&d=identicon",
20      "web_url": "http://localhost:3000/john.doe"
21    }],
22    "author": {
23      "id": 1,
24      "name": "Administrator",
25      "username": "root",
26      "state": "active",
27      "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
28      "web_url": "http://localhost:3000/root"
29    },
30    "type": "TASK",
31    "user_notes_count": 2,
32    "upvotes": 1,
33    "downvotes": 0,
34    "due_date": "2018-04-01",
35    "confidential": false,
36    "discussion_locked": null,
37    "web_url": "http://localhost:3000/my-group/my-project/-/work_items/9",
38    "time_stats": {
39      "time_estimate": 0,
40      "total_time_spent": 0,
41      "human_time_estimate": null,
42      "human_total_time_spent": null
43    }
44  }
45]

您可以使用 type 参数按类型筛选工作项：

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/12/search?scope=work_items&search=backend&type[]=task&type[]=issue"

范围：merge_requests#

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/6/search?scope=merge_requests&search=file"

示例响应：

json
1[
2  {
3    "id": 56,
4    "iid": 8,
5    "project_id": 6,
6    "title": "Add first file",
7    "description": "This is a test MR to add file",
8    "state": "opened",
9    "created_at": "2018-01-22T14:21:50.830Z",
10    "updated_at": "2018-02-06T12:40:33.295Z",
11    "target_branch": "main",
12    "source_branch": "jaja-test",
13    "upvotes": 0,
14    "downvotes": 0,
15    "author": {
16      "id": 1,
17      "name": "Administrator",
18      "username": "root",
19      "state": "active",
20      "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
21      "web_url": "http://localhost:3000/root"
22    },
23    "assignee": {
24      "id": 5,
25      "name": "Jacquelyn Kutch",
26      "username": "abigail",
27      "state": "active",
28      "avatar_url": "https://www.gravatar.com/avatar/3138c66095ee4bd11a508c2f7f7772da?s=80&d=identicon",
29      "web_url": "http://localhost:3000/abigail"
30    },
31    "source_project_id": 6,
32    "target_project_id": 6,
33    "labels": [
34      "ruby",
35      "tests"
36    ],
37    "draft": false,
38    "work_in_progress": false,
39    "milestone": {
40      "id": 13,
41      "iid": 3,
42      "project_id": 6,
43      "title": "v2.0",
44      "description": "Qui aut qui eos dolor beatae itaque tempore molestiae.",
45      "state": "active",
46      "created_at": "2017-09-05T07:58:29.099Z",
47      "updated_at": "2017-09-05T07:58:29.099Z",
48      "due_date": null,
49      "start_date": null
50    },
51    "merge_when_pipeline_succeeds": false,
52    "merge_status": "can_be_merged",
53    "sha": "78765a2d5e0a43585945c58e61ba2f822e4d090b",
54    "merge_commit_sha": null,
55    "squash_commit_sha": null,
56    "user_notes_count": 0,
57    "discussion_locked": null,
58    "should_remove_source_branch": null,
59    "force_remove_source_branch": true,
60    "web_url": "http://localhost:3000/twitter/flight/merge_requests/8",
61    "time_stats": {
62      "time_estimate": 0,
63      "total_time_spent": 0,
64      "human_time_estimate": null,
65      "human_total_time_spent": null
66    }
67  }
68]

范围：milestones#

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/12/search?scope=milestones&search=release"

示例响应：

json
1[
2  {
3    "id": 44,
4    "iid": 1,
5    "project_id": 12,
6    "title": "next release",
7    "description": "Next release milestone",
8    "state": "active",
9    "created_at": "2018-02-06T12:43:39.271Z",
10    "updated_at": "2018-02-06T12:44:01.298Z",
11    "due_date": "2018-04-18",
12    "start_date": "2018-02-04"
13  }
14]

范围：users#

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/6/search?scope=users&search=doe"

示例响应：

json
1[
2  {
3    "id": 1,
4    "name": "John Doe1",
5    "username": "user1",
6    "state": "active",
7    "avatar_url": "http://www.gravatar.com/avatar/c922747a93b40d1ea88262bf1aebee62?s=80&d=identicon",
8    "web_url": "http://localhost/user1"
9  }
10]

范围：wiki_blobs#

使用此范围搜索 Wiki。

此范围可使用以下筛选条件：

filename
path
extension

要使用筛选条件，请将其包含在查询中（例如 a query filename:some_name*）。

您可以使用通配符（*）进行 glob 匹配。

Wiki blob 搜索会同时针对文件名和内容执行。搜索结果：

在文件名中找到的结果会显示在内容中找到的结果之前。
同一 blob 可能包含多个匹配项，因为搜索字符串可能同时出现在文件名和内容中，也可能在内容中出现多次。

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/6/search?scope=wiki_blobs&search=bye"

示例响应：

json
1
2[
3  {
4    "basename": "home",
5    "data": "hello\n\nand bye\n\nend",
6    "path": "home.md",
7    "filename": "home.md",
8    "id": null,
9    "ref": "main",
10    "startline": 5,
11    "project_id": 6,
12    "group_id": 1
13  }
14]

filename 已弃用，请改用 path。两者都返回代码仓库中文件的完整路径，但将来 filename 将仅表示文件名，而非完整路径。有关详情，请参阅议题 34521。

范围：commits#

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/6/search?scope=commits&search=bye"

示例响应：

json
1
2[
3  {
4  "id": "4109c2d872d5fdb1ed057400d103766aaea97f98",
5  "short_id": "4109c2d8",
6  "title": "goodbye $.browser",
7  "created_at": "2013-02-18T22:02:54.000Z",
8  "parent_ids": [
9    "59d05353ab575bcc2aa958fe1782e93297de64c9"
10  ],
11  "message": "goodbye $.browser\n",
12  "author_name": "angus croll",
13  "author_email": "anguscroll@gmail.com",
14  "authored_date": "2013-02-18T22:02:54.000Z",
15  "committer_name": "angus croll",
16  "committer_email": "anguscroll@gmail.com",
17  "committed_date": "2013-02-18T22:02:54.000Z",
18  "project_id": 6
19  }
20]

范围：blobs#

使用此范围搜索代码。

此范围可使用以下筛选条件：

filename
path
extension

要使用筛选条件，请将其包含在查询中（例如 a query filename:some_name*）。

您可以使用通配符（*）进行 glob 匹配。

Blob 搜索会同时针对文件名和内容执行。搜索结果：

在文件名中找到的结果会显示在内容中找到的结果之前。
同一 blob 可能包含多个匹配项，因为搜索字符串可能同时出现在文件名和内容中，也可能在内容中出现多次。

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/6/search?scope=blobs&search=keyword%20filename:*.py"

示例响应：

json
1
2[
3  {
4    "basename": "README",
5    "data": "```\n\n## Installation\n\nQuick start using the [pre-built",
6    "path": "README.md",
7    "filename": "README.md",
8    "id": null,
9    "ref": "main",
10    "startline": 46,
11    "project_id": 6
12  }
13]

范围：notes#

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/6/search?scope=notes&search=maxime"

示例响应：

json
1[
2  {
3    "id": 191,
4    "body": "Harum maxime consequuntur et et deleniti assumenda facilis.",
5    "attachment": null,
6    "author": {
7      "id": 23,
8      "name": "User 1",
9      "username": "user1",
10      "state": "active",
11      "avatar_url": "https://www.gravatar.com/avatar/111d68d06e2d317b5a59c2c6c5bad808?s=80&d=identicon",
12      "web_url": "http://localhost:3000/user1"
13    },
14    "created_at": "2017-09-05T08:01:32.068Z",
15    "updated_at": "2017-09-05T08:01:32.068Z",
16    "system": false,
17    "noteable_id": 22,
18    "noteable_type": "Issue",
19    "project_id": 6,
20    "noteable_iid": 2
21  }
22]

语义搜索#

Tier: 专业版，旗舰版

Add-on: 极狐GitLab Duo Core, Pro, or Enterprise

Offering: JihuLab.com，私有化部署

Status: 测试版

基于含义而非关键词匹配在项目中搜索代码。

plaintext
GET /projects/:id/search/semantic

属性	类型	是否必需	描述
id	integer or string	是	项目的 ID 或 URL 编码路径。
q	string	是	自然语言搜索查询。
directory_path	string	否	用于限定搜索范围的目录路径。
knn	integer	否	向量搜索期间要考虑的最近邻数量（1-100）。默认为 64。
limit	integer	否	要返回的最大结果数（1-100）。默认为 20。

示例请求：

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/12/search/semantic?q=authentication%20middleware"

示例响应：

响应是一个代码搜索结果数组。每个结果包含以下字段：

字段	类型	描述
path	string	相对于代码仓库根目录的文件路径。
content	string	匹配文件中的代码内容片段。
score	number	查询与结果之间的语义相似度分数（0-1）。分数越高表示匹配越好。
language	string	文件的编程语言。
start_line	integer	匹配代码片段起始的行号。
blob_id	string	文件的 Git blob ID。
file_url	string	在极狐GitLab 中查看该文件的 URL。

json
1[
2  {
3    "path": "app/services/auth/jwt_service.rb",
4    "content": "def verify_token(token)\n  JWT.decode(token, secret_key)...",
5    "score": 0.91,
6    "language": "ruby",
7    "start_line": 42,
8    "blob_id": "a1b2c3d4e5f6...",
9    "file_url": "https://gitlab.example.com/my-org/my-project/-/blob/main/app/services/auth/jwt_service.rb"
10  }
11]