Projects API

Tier: 基础版，专业版，旗舰版
Offering: JihuLab.com，私有化部署

使用此 API 来管理极狐GitLab 项目及其相关设置。项目是协作的中心枢纽，您可以在其中存储代码、跟踪议题和组织团队活动。有关更多信息，请参阅创建项目。

Projects API 包含以下端点：

检索项目信息和元数据
创建、编辑和删除项目
控制项目的可见性、访问权限和安全设置
管理项目功能，如议题跟踪、合并请求和 CI/CD
归档和取消归档项目
在命名空间之间转移项目
管理部署和容器注册表设置

权限#

具有以下权限的用户：

项目上的任何默认角色都可以读取项目的属性。
项目的所有者或维护者角色也可以编辑项目的属性。

项目可见性级别#

极狐GitLab 中的项目可以具有以下可见性级别：

私有
内部
公开

可见性级别由项目中的 visibility 字段决定。

有关更多信息，请参阅项目可见性。

响应中返回的字段根据经过身份验证的用户的权限而有所不同。

已弃用属性#

这些属性已弃用，可能会在未来版本的 REST API 中删除。请使用替代属性。

已弃用属性	替代属性
tag_list	topics 属性
marked_for_deletion_at	marked_for_deletion_on。仅适用于专业版和旗舰版。
approvals_before_merge	合并请求批准 API。仅适用于专业版和旗舰版。

获取单个项目#

获取特定项目。如果项目公开可访问，则可以在不进行身份验证的情况下访问此端点。

plaintext
GET /projects/:id

支持的属性：

属性	类型	是否必需	描述
id	整数或字符串	是	项目的 ID 或 URL 编码路径。
license	布尔值	否	包含项目许可证数据。
statistics	布尔值	否	包含项目统计数据。仅对拥有至少报告者角色的用户可用。
with_custom_attributes	布尔值	否	在响应中包含自定义属性。(仅限管理员)

响应中包括与容器注册表存储大小相关的属性：

container_registry_size：项目中所有容器存储库使用的总存储大小（字节）。每当推送或删除容器镜像时更新。对于极狐GitLab 私有化部署实例，需要启用容器注册表元数据数据库。

示例响应：

json
1{
2  "id": 3,
3  "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
4  "description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
5  "default_branch": "main",
6  "visibility": "private",
7  "ssh_url_to_repo": "git@example.com:diaspora/diaspora-project-site.git",
8  "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
9  "web_url": "http://example.com/diaspora/diaspora-project-site",
10  "readme_url": "http://example.com/diaspora/diaspora-project-site/blob/main/README.md",
11  "tag_list": [ //deprecated, use `topics` instead
12    "example",
13    "disapora project"
14  ],
15  "topics": [
16    "example",
17    "disapora project"
18  ],
19  "owner": {
20    "id": 3,
21    "name": "Diaspora",
22    "created_at": "2013-09-30T13:46:02Z"
23  },
24  "name": "Diaspora Project Site",
25  "name_with_namespace": "Diaspora / Diaspora Project Site",
26  "path": "diaspora-project-site",
27  "path_with_namespace": "diaspora/diaspora-project-site",
28  "issues_enabled": true,
29  "open_issues_count": 1,
30  "merge_requests_enabled": true,
31  "jobs_enabled": true,
32  "wiki_enabled": true,
33  "snippets_enabled": false,
34  "can_create_merge_request_in": true,
35  "resolve_outdated_diff_discussions": false,
36  "container_registry_enabled": false, // deprecated, use container_registry_access_level instead
37  "container_registry_access_level": "disabled",
38  "security_and_compliance_access_level": "disabled",
39  "container_expiration_policy": {
40    "cadence": "7d",
41    "enabled": false,
42    "keep_n": null,
43    "older_than": null,
44    "name_regex": null, // to be deprecated in GitLab 13.0 in favor of `name_regex_delete`
45    "name_regex_delete": null,
46    "name_regex_keep": null,
47    "next_run_at": "2020-01-07T21:42:58.658Z"
48  },
49  "created_at": "2013-09-30T13:46:02Z",
50  "updated_at": "2013-09-30T13:46:02Z",
51  "last_activity_at": "2013-09-30T13:46:02Z",
52  "creator_id": 3,
53  "namespace": {
54    "id": 3,
55    "name": "Diaspora",
56    "path": "diaspora",
57    "kind": "group",
58    "full_path": "diaspora",
59    "avatar_url": "http://localhost:3000/uploads/group/avatar/3/foo.jpg",
60    "web_url": "http://localhost:3000/groups/diaspora"
61  },
62  "import_url": null,
63  "import_type": null,
64  "import_status": "none",
65  "import_error": null,
66  "permissions": {
67    "project_access": {
68      "access_level": 10,
69      "notification_level": 3
70    },
71    "group_access": {
72      "access_level": 50,
73      "notification_level": 3
74    }
75  },
76  "archived": false,
77  "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png",
78  "license_url": "http://example.com/diaspora/diaspora-client/blob/main/LICENSE",
79  "license": {
80    "key": "lgpl-3.0",
81    "name": "GNU Lesser General Public License v3.0",
82    "nickname": "GNU LGPLv3",
83    "html_url": "http://choosealicense.com/licenses/lgpl-3.0/",
84    "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt"
85  },
86  "shared_runners_enabled": true,
87  "group_runners_enabled": true,
88  "forks_count": 0,
89  "star_count": 0,
90  "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b",
91  "ci_default_git_depth": 50,
92  "ci_forward_deployment_enabled": true,
93  "ci_forward_deployment_rollback_allowed": true,
94  "ci_allow_fork_pipelines_to_run_in_parent_project": true,
95  "ci_id_token_sub_claim_components": ["project_path", "ref_type", "ref"],
96  "ci_separated_caches": true,
97  "ci_restrict_pipeline_cancellation_role": "developer",
98  "ci_pipeline_variables_minimum_override_role": "maintainer",
99  "ci_push_repository_for_job_token_allowed": false,
100  "public_jobs": true,
101  "shared_with_groups": [
102    {
103      "group_id": 4,
104      "group_name": "Twitter",
105      "group_full_path": "twitter",
106      "group_access_level": 30
107    },
108    {
109      "group_id": 3,
110      "group_name": "Gitlab Org",
111      "group_full_path": "gitlab-org",
112      "group_access_level": 10
113    }
114  ],
115  "repository_storage": "default",
116  "only_allow_merge_if_pipeline_succeeds": false,
117  "allow_merge_on_skipped_pipeline": false,
118  "allow_pipeline_trigger_approve_deployment": false,
119  "restrict_user_defined_variables": false,
120  "only_allow_merge_if_all_discussions_are_resolved": false,
121  "remove_source_branch_after_merge": false,
122  "printing_merge_requests_link_enabled": true,
123  "request_access_enabled": false,
124  "merge_method": "merge",
125  "squash_option": "default_on",
126  "auto_devops_enabled": true,
127  "auto_devops_deploy_strategy": "continuous",
128  "approvals_before_merge": 0, // Deprecated. Use merge request approvals API instead.
129  "mirror": false,
130  "mirror_user_id": 45,
131  "mirror_trigger_builds": false,
132  "only_mirror_protected_branches": false,
133  "mirror_overwrites_diverged_branches": false,
134  "external_authorization_classification_label": null,
135  "packages_enabled": true,
136  "service_desk_enabled": false,
137  "service_desk_address": null,
138  "autoclose_referenced_issues": true,
139  "suggestion_commit_message": null,
140  "enforce_auth_checks_on_uploads": true,
141  "merge_commit_template": null,
142  "squash_commit_template": null,
143  "issue_branch_template": "gitlab/%{id}-%{title}",
144  "marked_for_deletion_at": "2020-04-03", // Deprecated in favor of marked_for_deletion_on. Planned for removal in a future version of the REST API.
145  "marked_for_deletion_on": "2020-04-03",
146  "compliance_frameworks": [ "sox" ],
147  "warn_about_potentially_unwanted_characters": true,
148  "secret_push_protection_enabled": false,
149  "statistics": {
150    "commit_count": 37,
151    "storage_size": 1038090,
152    "repository_size": 1038090,
153    "wiki_size" : 0,
154    "lfs_objects_size": 0,
155    "job_artifacts_size": 0,
156    "pipeline_artifacts_size": 0,
157    "packages_size": 0,
158    "snippets_size": 0,
159    "uploads_size": 0,
160    "container_registry_size": 0
161  },
162  "container_registry_image_prefix": "registry.example.com/diaspora/diaspora-client",
163  "_links": {
164    "self": "http://example.com/api/v4/projects",
165    "issues": "http://example.com/api/v4/projects/1/issues",
166    "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
167    "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
168    "labels": "http://example.com/api/v4/projects/1/labels",
169    "events": "http://example.com/api/v4/projects/1/events",
170    "members": "http://example.com/api/v4/projects/1/members",
171    "cluster_agents": "http://example.com/api/v4/projects/1/cluster_agents"
172  }
173}

在极狐GitLab 旗舰版的用户可以使用极狐GitLab 15.5 及更高版本查看 only_allow_merge_if_all_status_checks_passed 参数：

json
1{
2  "id": 1,
3  "project_id": 3,
4  "only_allow_merge_if_all_status_checks_passed": false,
5  ...
6}

如果项目是分叉项目，则响应中会出现 forked_from_project 字段。对于此字段，如果上游项目是私有的，则必须提供有效的身份验证令牌。字段 mr_default_target_self 也会出现。如果此值为 false，则所有合并请求默认目标为上游项目。

json
1{
2   "id":3,
3
4   ...
5
6   "mr_default_target_self": false,
7   "forked_from_project":{
8      "id":13083,
9      "description":"GitLab Community Edition",
10      "name":"GitLab Community Edition",
11      "name_with_namespace":"GitLab.org / GitLab Community Edition",
12      "path":"gitlab-foss",
13      "path_with_namespace":"gitlab-org/gitlab-foss",
14      "created_at":"2013-09-26T06:02:36.000Z",
15      "default_branch":"main",
16      "tag_list":[], //deprecated, use `topics` instead
17      "topics":[],
18      "ssh_url_to_repo":"git@gitlab.com:gitlab-org/gitlab-foss.git",
19      "http_url_to_repo":"https://gitlab.com/gitlab-org/gitlab-foss.git",
20      "web_url":"https://gitlab.com/gitlab-org/gitlab-foss",
21      "avatar_url":"https://gitlab.com/uploads/-/system/project/avatar/13083/logo-extra-whitespace.png",
22      "license_url": "https://gitlab.com/gitlab-org/gitlab/-/blob/main/LICENSE",
23      "license": {
24        "key": "mit",
25        "name": "MIT License",
26        "nickname": null,
27        "html_url": "http://choosealicense.com/licenses/mit/",
28        "source_url": "https://opensource.org/licenses/MIT"
29      },
30      "star_count":3812,
31      "forks_count":3561,
32      "last_activity_at":"2018-01-02T11:40:26.570Z",
33      "namespace": {
34            "id": 72,
35            "name": "GitLab.org",
36            "path": "gitlab-org",
37            "kind": "group",
38            "full_path": "gitlab-org",
39            "parent_id": null
40      },
41      "repository_storage": "default"
42   }
43
44   ...
45
46}

议题和合并请求的模板#

Tier: 专业版，旗舰版
Offering: JihuLab.com，极狐GitLab 私有化部署，极狐GitLab 专属

使用极狐GitLab 专业版或旗舰版的用户还可以查看 issues_template 和 merge_requests_template 参数以管理议题和合并请求描述模板。

json
1{
2  "id": 3,
3  "issues_template": null,
4  "merge_requests_template": null,
5  ...
6}

列出项目#

列出项目。

列出所有项目#

History

响应中的 _links.cluster_agents 属性在极狐GitLab 15.0 中引入。

获取经过身份验证的用户在极狐GitLab 中所有可见项目的列表。在不进行身份验证的情况下访问时，仅返回具有 simple 字段的公共项目。

plaintext
GET /projects

支持的属性：

属性	类型	是否必需	描述
archived	布尔值	否	根据存档状态限制结果。
id_after	整数	否	限制结果为 ID 大于指定 ID 的项目。
id_before	整数	否	限制结果为 ID 小于指定 ID 的项目。
imported	布尔值	否	限制结果为当前用户从外部系统导入的项目。
include_hidden	布尔值	否	包括隐藏项目。(仅限管理员) 专业版和旗舰版仅。
include_pending_delete	布尔值	否	包括待删除项目。(仅限管理员)
last_activity_after	datetime	否	限制结果为最后活动时间在指定时间之后的项目。格式：ISO 8601 (YYYY-MM-DDTHH:MM:SSZ)
last_activity_before	datetime	否	限制结果为最后活动时间在指定时间之前的项目。格式：ISO 8601 (YYYY-MM-DDTHH:MM:SSZ)
membership	布尔值	否	限制结果为当前用户所属的项目。
min_access_level	整数	否	限制结果为当前用户最低角色 (access_level)。
order_by	字符串	否	返回按 id、name、path、created_at、updated_at、star_count、last_activity_at 或 similarity 字段排序的项目。 repository_size、storage_size、packages_size 或 wiki_size 字段仅允许管理员使用。 similarity 仅在搜索时可用，并且仅限于当前用户所属的项目。默认值为 created_at。
owned	布尔值	否	限制结果为当前用户明确拥有的项目。
repository_checksum_failed	布尔值	否	限制结果为存储库校验和计算失败的项目。专业版和旗舰版仅。
repository_storage	字符串	否	限制结果为存储在 repository_storage 上的项目。(仅限管理员)
search_namespaces	布尔值	否	在匹配搜索条件时包括祖先命名空间。默认值为 false。
search	字符串	否	返回项目列表，其中 path、name 或 description 匹配搜索条件（不区分大小写，子字符串匹配）。可以提供多个术语，用转义空格分隔，使用 + 或 %20，并将它们组合在一起。例如：one+two 将匹配子字符串 one 和 two（任何顺序）。
simple	布尔值	否	仅返回每个项目的有限字段。此操作在没有身份验证的情况下无效，只有简单字段返回。
sort	字符串	否	返回按 asc 或 desc 顺序排序的项目。默认值为 desc。
starred	布尔值	否	限制结果为当前用户标星的项目。
statistics	布尔值	否	包括项目统计数据。仅对拥有至少报告者角色的用户可用。
topic_id	整数	否	限制结果为分配了由主题 ID 指定的主题的项目。
topic	字符串	否	逗号分隔的主题名称。限制结果为与给定主题全部匹配的项目。请参阅 topics 属性。
updated_after	datetime	否	限制结果为最后更新时间在指定时间之后的项目。格式：ISO 8601 (YYYY-MM-DDTHH:MM:SSZ)。在极狐GitLab 15.10 中引入。要使此过滤器生效，您还必须提供 updated_at 作为 order_by 属性。
updated_before	datetime	否	限制结果为最后更新时间在指定时间之前的项目。格式：ISO 8601 (YYYY-MM-DDTHH:MM:SSZ)。在极狐GitLab 15.10 中引入。要使此过滤器生效，您还必须提供 updated_at 作为 order_by 属性。
visibility	字符串	否	限制结果为可见性 public、internal 或 private。
wiki_checksum_failed	布尔值	否	限制结果为 Wiki 校验和计算失败的项目。专业版和旗舰版仅。
with_custom_attributes	布尔值	否	在响应中包含自定义属性。(仅限管理员)
with_issues_enabled	布尔值	否	限制结果为启用了议题功能的项目。
with_merge_requests_enabled	布尔值	否	限制结果为启用了合并请求功能的项目。
with_programming_language	字符串	否	限制结果为使用给定编程语言的项目。
marked_for_deletion_on	日期	否	按项目标记为删除的日期进行过滤。在极狐GitLab 17.1 中引入。专业版和旗舰版仅。

此端点支持所选 order_by 选项的键集分页。

当 simple=true 或用户未进行身份验证时，返回如下内容：

示例请求：

shell
curl --request GET "https://gitlab.example.com/api/v4/projects"

示例响应：

json
1[
2  {
3    "id": 4,
4    "description": null,
5    "name": "Diaspora Client",
6    "name_with_namespace": "Diaspora / Diaspora Client",
7    "path": "diaspora-client",
8    "path_with_namespace": "diaspora/diaspora-client",
9    "created_at": "2013-09-30T13:46:02Z",
10    "default_branch": "main",
11    "tag_list": [
12      "example",
13      "disapora client"
14    ],
15    "topics": [
16      "example",
17      "disapora client"
18    ],
19    "ssh_url_to_repo": "git@gitlab.example.com:diaspora/diaspora-client.git",
20    "http_url_to_repo": "https://gitlab.example.com/diaspora/diaspora-client.git",
21    "web_url": "https://gitlab.example.com/diaspora/diaspora-client",
22    "avatar_url": "https://gitlab.example.com/uploads/project/avatar/4/uploads/avatar.png",
23    "star_count": 0,
24    "last_activity_at": "2013-09-30T13:46:02Z",
25    "namespace": {
26      "id": 2,
27      "name": "Diaspora",
28      "path": "diaspora",
29      "kind": "group",
30      "full_path": "diaspora",
31      "parent_id": null,
32      "avatar_url": null,
33      "web_url": "https://gitlab.example.com/diaspora"
34    }
35  },
36  {
37    ...
38  }

当用户进行身份验证且未设置 simple 时，此端点返回如下内容：

json
1[
2  {
3    "id": 4,
4    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
5    "description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
6    "name": "Diaspora Client",
7    "name_with_namespace": "Diaspora / Diaspora Client",
8    "path": "diaspora-client",
9    "path_with_namespace": "diaspora/diaspora-client",
10    "created_at": "2013-09-30T13:46:02Z",
11    "updated_at": "2013-09-30T13:46:02Z",
12    "default_branch": "main",
13    "tag_list": [ //deprecated, use `topics` instead
14      "example",
15      "disapora client"
16    ],
17    "topics": [
18      "example",
19      "disapora client"
20    ],
21    "ssh_url_to_repo": "git@gitlab.example.com:diaspora/diaspora-client.git",
22    "http_url_to_repo": "https://gitlab.example.com/diaspora/diaspora-client.git",
23    "web_url": "https://gitlab.example.com/diaspora/diaspora-client",
24    "readme_url": "https://gitlab.example.com/diaspora/diaspora-client/blob/main/README.md",
25    "avatar_url": "https://gitlab.example.com/uploads/project/avatar/4/uploads/avatar.png",
26    "forks_count": 0,
27    "star_count": 0,
28    "last_activity_at": "2022-06-24T17:11:26.841Z",
29    "namespace": {
30      "id": 3,
31      "name": "Diaspora",
32      "path": "diaspora",
33      "kind": "group",
34      "full_path": "diaspora",
35      "parent_id": null,
36      "avatar_url": "https://gitlab.example.com/uploads/project/avatar/6/uploads/avatar.png",
37      "web_url": "https://gitlab.example.com/diaspora"
38    },
39    "container_registry_image_prefix": "registry.gitlab.example.com/diaspora/diaspora-client",
40    "_links": {
41      "self": "https://gitlab.example.com/api/v4/projects/4",
42      "issues": "https://gitlab.example.com/api/v4/projects/4/issues",
43      "merge_requests": "https://gitlab.example.com/api/v4/projects/4/merge_requests",
44      "repo_branches": "https://gitlab.example.com/api/v4/projects/4/repository/branches",
45      "labels": "https://gitlab.example.com/api/v4/projects/4/labels",
46      "events": "https://gitlab.example.com/api/v4/projects/4/events",
47      "members": "https://gitlab.example.com/api/v4/projects/4/members",
48      "cluster_agents": "https://gitlab.example.com/api/v4/projects/4/cluster_agents"
49    },
50    "packages_enabled": true,
51    "empty_repo": false,
52    "archived": false,
53    "visibility": "public",
54    "resolve_outdated_diff_discussions": false,
55    "container_expiration_policy": {
56      "cadence": "1month",
57      "enabled": true,
58      "keep_n": 1,
59      "older_than": "14d",
60      "name_regex": "",
61      "name_regex_keep": ".*-main",
62      "next_run_at": "2022-06-25T17:11:26.865Z"
63    },
64    "issues_enabled": true,
65    "merge_requests_enabled": true,
66    "wiki_enabled": true,
67    "jobs_enabled": true,
68    "snippets_enabled": true,
69    "container_registry_enabled": true,
70    "service_desk_enabled": true,
71    "can_create_merge_request_in": true,
72    "issues_access_level": "enabled",
73    "repository_access_level": "enabled",
74    "merge_requests_access_level": "enabled",
75    "forking_access_level": "enabled",
76    "wiki_access_level": "enabled",
77    "builds_access_level": "enabled",
78    "snippets_access_level": "enabled",
79    "pages_access_level": "enabled",
80    "analytics_access_level": "enabled",
81    "container_registry_access_level": "enabled",
82    "security_and_compliance_access_level": "private",
83    "emails_disabled": null,
84    "emails_enabled": null,
85    "shared_runners_enabled": true,
86    "group_runners_enabled": true,
87    "lfs_enabled": true,
88    "creator_id": 1,
89    "import_url": null,
90    "import_type": null,
91    "import_status": "none",
92    "import_error": null,
93    "open_issues_count": 0,
94    "ci_default_git_depth": 20,
95    "ci_forward_deployment_enabled": true,
96    "ci_forward_deployment_rollback_allowed": true,
97    "ci_allow_fork_pipelines_to_run_in_parent_project": true,
98    "ci_id_token_sub_claim_components": ["project_path", "ref_type", "ref"],
99    "ci_job_token_scope_enabled": false,
100    "ci_separated_caches": true,
101    "ci_restrict_pipeline_cancellation_role": "developer",
102    "ci_pipeline_variables_minimum_override_role": "maintainer",
103    "ci_push_repository_for_job_token_allowed": false,
104    "public_jobs": true,
105    "build_timeout": 3600,
106    "auto_cancel_pending_pipelines": "enabled",
107    "ci_config_path": "",
108    "shared_with_groups": [],
109    "only_allow_merge_if_pipeline_succeeds": false,
110    "allow_merge_on_skipped_pipeline": null,
111    "allow_pipeline_trigger_approve_deployment": false,
112    "restrict_user_defined_variables": false,
113    "request_access_enabled": true,
114    "only_allow_merge_if_all_discussions_are_resolved": false,
115    "remove_source_branch_after_merge": true,
116    "printing_merge_request_link_enabled": true,
117    "merge_method": "merge",
118    "squash_option": "default_off",
119    "enforce_auth_checks_on_uploads": true,
120    "suggestion_commit_message": null,
121    "merge_commit_template": null,
122    "squash_commit_template": null,
123    "issue_branch_template": "gitlab/%{id}-%{title}",
124    "auto_devops_enabled": false,
125    "auto_devops_deploy_strategy": "continuous",
126    "autoclose_referenced_issues": true,
127    "keep_latest_artifact": true,
128    "runner_token_expiration_interval": null,
129    "external_authorization_classification_label": "",
130    "requirements_enabled": false,
131    "requirements_access_level": "enabled",
132    "security_and_compliance_enabled": false,
133    "secret_push_protection_enabled": false,
134    "compliance_frameworks": [],
135    "warn_about_potentially_unwanted_characters": true,
136    "permissions": {
137      "project_access": null,
138      "group_access": null
139    }
140  },
141  {
142    ...
143  }
144]

`last_activity_at` 是根据[项目活动](../user/project/working_with_projects.md#view-project-activity)和[项目事件](events.md)更新的。`updated_at` 是每当项目记录在数据库中更改时更新的。

您可以通过自定义属性进行过滤：

plaintext
GET /projects?custom_attributes[key]=value&custom_attributes[other_key]=other_value

示例请求：

shell
curl --globoff --request GET "https://gitlab.example.com/api/v4/projects?custom_attributes[location]=Antarctica&custom_attributes[role]=Developer"

分页限制#

您可以使用基于偏移量的分页访问最多 50,000 个项目。

使用键集分页检索超过此限制的项目。键集分页仅支持 order_by=id。其他排序选项不可用。

列出用户的项目#

获取给定用户拥有的可见项目的列表。在不进行身份验证的情况下访问时，仅返回公共项目。

先决条件：

要查看某些属性，您必须是管理员或具有项目的所有者角色。

仅返回用户（在 `user_id` 中指定）的命名空间中的项目。用户在任何群组或子群组中拥有的项目不会返回。如果配置文件设置为私有，则返回空列表。

此端点支持所选 order_by 选项的键集分页。

plaintext
GET /users/:user_id/projects

支持的属性：

属性	类型	是否必需	描述
user_id	字符串	是	用户的 ID 或用户名。
archived	布尔值	否	根据存档状态限制结果。
id_after	整数	否	限制结果为 ID 大于指定 ID 的项目。
id_before	整数	否	限制结果为 ID 小于指定 ID 的项目。
membership	布尔值	否	限制结果为当前用户所属的项目。
min_access_level	整数	否	限制结果为当前用户最低角色 (access_level)。
order_by	字符串	否	返回按 id、name、path、created_at、updated_at、star_count 或 last_activity_at 字段排序的项目。默认值为 created_at。
owned	布尔值	否	限制结果为当前用户明确拥有的项目。
search	字符串	否	返回匹配搜索条件的项目列表。
simple	布尔值	否	仅返回每个项目的有限字段。没有身份验证，此操作无效；仅返回简单字段。
sort	字符串	否	返回按 asc 或 desc 顺序排序的项目。默认值为 desc。
starred	布尔值	否	限制结果为当前用户标星的项目。
statistics	布尔值	否	包括项目统计数据。仅对拥有至少报告者角色的用户可用。
updated_after	datetime	否	限制结果为最后更新时间在指定时间之后的项目。格式：ISO 8601 (YYYY-MM-DDTHH:MM:SSZ)。在极狐GitLab 15.10 中引入。
updated_before	datetime	否	限制结果为最后更新时间在指定时间之前的项目。格式：ISO 8601 (YYYY-MM-DDTHH:MM:SSZ)。在极狐GitLab 15.10 中引入。
visibility	字符串	否	限制结果为可见性 public、internal 或 private。
with_custom_attributes	布尔值	否	在响应中包含自定义属性。(仅限管理员)
with_issues_enabled	布尔值	否	限制结果为启用了议题功能的项目。
with_merge_requests_enabled	布尔值	否	限制结果为启用了合并请求功能的项目。
with_programming_language	字符串	否	限制结果为使用给定编程语言的项目。

示例响应：

json
1[
2  {
3    "id": 4,
4    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
5    "description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
6    "default_branch": "main",
7    "visibility": "private",
8    "ssh_url_to_repo": "git@example.com:diaspora/diaspora-client.git",
9    "http_url_to_repo": "http://example.com/diaspora/diaspora-client.git",
10    "web_url": "http://example.com/diaspora/diaspora-client",
11    "readme_url": "http://example.com/diaspora/diaspora-client/blob/main/README.md",
12    "tag_list": [ //deprecated, use `topics` instead
13      "example",
14      "disapora client"
15    ],
16    "topics": [
17      "example",
18      "disapora client"
19    ],
20    "owner": {
21      "id": 3,
22      "name": "Diaspora",
23      "created_at": "2013-09-30T13:46:02Z"
24    },
25    "name": "Diaspora Client",
26    "name_with_namespace": "Diaspora / Diaspora Client",
27    "path": "diaspora-client",
28    "path_with_namespace": "diaspora/diaspora-client",
29    "issues_enabled": true,
30    "open_issues_count": 1,
31    "merge_requests_enabled": true,
32    "jobs_enabled": true,
33    "wiki_enabled": true,
34    "snippets_enabled": false,
35    "can_create_merge_request_in": true,
36    "resolve_outdated_diff_discussions": false,
37    "container_registry_enabled": false, // deprecated, use container_registry_access_level instead
38    "container_registry_access_level": "disabled",
39    "security_and_compliance_access_level": "disabled",
40    "created_at": "2013-09-30T13:46:02Z",
41    "updated_at": "2013-09-30T13:46:02Z",
42    "last_activity_at": "2013-09-30T13:46:02Z",
43    "creator_id": 3,
44    "import_url": null,
45    "import_type": null,
46    "import_status": "none",
47    "import_error": null,
48    "namespace": {
49      "id": 3,
50      "name": "Diaspora",
51      "path": "diaspora",
52      "kind": "group",
53      "full_path": "diaspora"
54    },
55    "import_status": "none",
56    "archived": false,
57    "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png",
58    "shared_runners_enabled": true,
59    "group_runners_enabled": true,
60    "forks_count": 0,
61    "star_count": 0,
62    "runners_token": "b8547b1dc37721d05889db52fa2f02",
63    "ci_default_git_depth": 50,
64    "ci_forward_deployment_enabled": true,
65    "ci_forward_deployment_rollback_allowed": true,
66    "ci_allow_fork_pipelines_to_run_in_parent_project": true,
67    "ci_id_token_sub_claim_components": ["project_path", "ref_type", "ref"],
68    "ci_separated_caches": true,
69    "ci_restrict_pipeline_cancellation_role": "developer",
70    "ci_pipeline_variables_minimum_override_role": "maintainer",
71    "ci_push_repository_for_job_token_allowed": false,
72    "public_jobs": true,
73    "shared_with_groups": [],
74    "only_allow_merge_if_pipeline_succeeds": false,
75    "allow_merge_on_skipped_pipeline": false,
76    "allow_pipeline_trigger_approve_deployment": false,
77    "restrict_user_defined_variables": false,
78    "only_allow_merge_if_all_discussions_are_resolved": false,
79    "remove_source_branch_after_merge": false,
80    "request_access_enabled": false,
81    "merge_method": "merge",
82    "squash_option": "default_on",
83    "autoclose_referenced_issues": true,
84    "enforce_auth_checks_on_uploads": true,
85    "suggestion_commit_message": null,
86    "merge_commit_template": null,
87    "squash_commit_template": null,
88    "secret_push_protection_enabled": false,
89    "issue_branch_template": "gitlab/%{id}-%{title}",
90    "marked_for_deletion_at": "2020-04-03", // Deprecated in favor of marked_for_deletion_on. Planned for removal in a future version of the REST API.
91    "marked_for_deletion_on": "2020-04-03",
92    "statistics": {
93      "commit_count": 37,
94      "storage_size": 1038090,
95      "repository_size": 1038090,
96      "wiki_size" : 0,
97      "lfs_objects_size": 0,
98      "job_artifacts_size": 0,
99      "pipeline_artifacts_size": 0,
100      "packages_size": 0,
101      "snippets_size": 0,
102      "uploads_size": 0,
103      "container_registry_size": 0
104    },
105    "container_registry_image_prefix": "registry.example.com/diaspora/diaspora-client",
106    "_links": {
107      "self": "http://example.com/api/v4/projects",
108      "issues": "http://example.com/api/v4/projects/1/issues",
109      "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
110      "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
111      "labels": "http://example.com/api/v4/projects/1/labels",
112      "events": "http://example.com/api/v4/projects/1/events",
113      "members": "http://example.com/api/v4/projects/1/members",
114      "cluster_agents": "http://example.com/api/v4/projects/1/cluster_agents"
115    }
116  },
117  {
118    "id": 6,
119    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
120    "description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
121    "default_branch": "main",
122    "visibility": "private",
123    "ssh_url_to_repo": "git@example.com:brightbox/puppet.git",
124    "http_url_to_repo": "http://example.com/brightbox/puppet.git",
125    "web_url": "http://example.com/brightbox/puppet",
126    "readme_url": "http://example.com/brightbox/puppet/blob/main/README.md",
127    "tag_list": [ //deprecated, use `topics` instead
128      "example",
129      "puppet"
130    ],
131    "topics": [
132      "example",
133      "puppet"
134    ],
135    "owner": {
136      "id": 4,
137      "name": "Brightbox",
138      "created_at": "2013-09-30T13:46:02Z"
139    },
140    "name": "Puppet",
141    "name_with_namespace": "Brightbox / Puppet",
142    "path": "puppet",
143    "path_with_namespace": "brightbox/puppet",
144    "issues_enabled": true,
145    "open_issues_count": 1,
146    "merge_requests_enabled": true,
147    "jobs_enabled": true,
148    "wiki_enabled": true,
149    "snippets_enabled": false,
150    "can_create_merge_request_in": true,
151    "resolve_outdated_diff_discussions": false,
152    "container_registry_enabled": false, // deprecated, use container_registry_access_level instead
153    "container_registry_access_level": "disabled",
154    "security_and_compliance_access_level": "disabled",
155    "created_at": "2013-09-30T13:46:02Z",
156    "updated_at": "2013-09-30T13:46:02Z",
157    "last_activity_at": "2013-09-30T13:46:02Z",
158    "creator_id": 3,
159    "import_url": null,
160    "import_type": null,
161    "import_status": "none",
162    "import_error": null,
163    "namespace": {
164      "id": 4,
165      "name": "Brightbox",
166      "path": "brightbox",
167      "kind": "group",
168      "full_path": "brightbox"
169    },
170    "import_status": "none",
171    "import_error": null,
172    "permissions": {
173      "project_access": {
174        "access_level": 10,
175        "notification_level": 3
176      },
177      "group_access": {
178        "access_level": 50,
179        "notification_level": 3
180      }
181    },
182    "archived": false,
183    "avatar_url": null,
184    "shared_runners_enabled": true,
185    "group_runners_enabled": true,
186    "forks_count": 0,
187    "star_count": 0,
188    "runners_token": "b8547b1dc37721d05889db52fa2f02",
189    "ci_default_git_depth": 0,
190    "ci_forward_deployment_enabled": true,
191    "ci_forward_deployment_rollback_allowed": true,
192    "ci_allow_fork_pipelines_to_run_in_parent_project": true,
193    "ci_id_token_sub_claim_components": ["project_path", "ref_type", "ref"],
194    "ci_separated_caches": true,
195    "ci_restrict_pipeline_cancellation_role": "developer",
196    "ci_pipeline_variables_minimum_override_role": "maintainer",
197    "ci_push_repository_for_job_token_allowed": false,
198    "public_jobs": true,
199    "shared_with_groups": [],
200    "only_allow_merge_if_pipeline_succeeds": false,
201    "allow_merge_on_skipped_pipeline": false,
202    "allow_pipeline_trigger_approve_deployment": false,
203    "restrict_user_defined_variables": false,
204    "only_allow_merge_if_all_discussions_are_resolved": false,
205    "remove_source_branch_after_merge": false,
206    "request_access_enabled": false,
207    "merge_method": "merge",
208    "squash_option": "default_on",
209    "auto_devops_enabled": true,
210    "auto_devops_deploy_strategy": "continuous",
211    "repository_storage": "default",
212    "approvals_before_merge": 0, // Deprecated. Use merge request approvals API instead.
213    "mirror": false,
214    "mirror_user_id": 45,
215    "mirror_trigger_builds": false,
216    "only_mirror_protected_branches": false,
217    "mirror_overwrites_diverged_branches": false,
218    "external_authorization_classification_label": null,
219    "packages_enabled": true,
220    "service_desk_enabled": false,
221    "service_desk_address": null,
222    "autoclose_referenced_issues": true,
223    "enforce_auth_checks_on_uploads": true,
224    "suggestion_commit_message": null,
225    "merge_commit_template": null,
226    "squash_commit_template": null,
227    "secret_push_protection_enabled": false,
228    "issue_branch_template": "gitlab/%{id}-%{title}",
229    "statistics": {
230      "commit_count": 12,
231      "storage_size": 2066080,
232      "repository_size": 2066080,
233      "wiki_size" : 0,
234      "lfs_objects_size": 0,
235      "job_artifacts_size": 0,
236      "pipeline_artifacts_size": 0,
237      "packages_size": 0,
238      "snippets_size": 0,
239      "uploads_size": 0,
240      "container_registry_size": 0
241    },
242    "container_registry_image_prefix": "registry.example.com/brightbox/puppet",
243    "_links": {
244      "self": "http://example.com/api/v4/projects",
245      "issues": "http://example.com/api/v4/projects/1/issues",
246      "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
247      "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
248      "labels": "http://example.com/api/v4/projects/1/labels",
249      "events": "http://example.com/api/v4/projects/1/events",
250      "members": "http://example.com/api/v4/projects/1/members",
251      "cluster_agents": "http://example.com/api/v4/projects/1/cluster_agents"
252    }
253  }
254]

列出用户贡献过的项目#

返回给定用户在过去一年内贡献过的可见项目列表。有关什么算作贡献的更多信息，请参见查看您贡献过的项目。

plaintext
GET /users/:user_id/contributed_projects

支持的属性：

属性	类型	必需	描述
user_id	string	是	用户的 ID 或用户名。
order_by	string	否	按 id、name、path、created_at、updated_at、star_count 或 last_activity_at 字段排序返回项目。默认是 created_at。
simple	boolean	否	仅返回每个项目的有限字段。没有身份验证，此操作无效；仅返回简单字段。
sort	string	否	按 asc 或 desc 顺序返回排序后的项目。默认是 desc。

示例请求：

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/5/contributed_projects"

示例响应：

json
1[
2  {
3    "id": 4,
4    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
5    "description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
6    "default_branch": "main",
7    "visibility": "private",
8    "ssh_url_to_repo": "git@example.com:diaspora/diaspora-client.git",
9    "http_url_to_repo": "http://example.com/diaspora/diaspora-client.git",
10    "web_url": "http://example.com/diaspora/diaspora-client",
11    "readme_url": "http://example.com/diaspora/diaspora-client/blob/main/README.md",
12    "tag_list": [ //deprecated, use `topics` instead
13      "example",
14      "disapora client"
15    ],
16    "topics": [
17      "example",
18      "disapora client"
19    ],
20    "owner": {
21      "id": 3,
22      "name": "Diaspora",
23      "created_at": "2013-09-30T13:46:02Z"
24    },
25    "name": "Diaspora Client",
26    "name_with_namespace": "Diaspora / Diaspora Client",
27    "path": "diaspora-client",
28    "path_with_namespace": "diaspora/diaspora-client",
29    "issues_enabled": true,
30    "open_issues_count": 1,
31    "merge_requests_enabled": true,
32    "jobs_enabled": true,
33    "wiki_enabled": true,
34    "snippets_enabled": false,
35    "can_create_merge_request_in": true,
36    "resolve_outdated_diff_discussions": false,
37    "container_registry_enabled": false, // deprecated, use container_registry_access_level instead
38    "container_registry_access_level": "disabled",
39    "security_and_compliance_access_level": "disabled",
40    "created_at": "2013-09-30T13:46:02Z",
41    "updated_at": "2013-09-30T13:46:02Z",
42    "last_activity_at": "2013-09-30T13:46:02Z",
43    "creator_id": 3,
44    "namespace": {
45      "id": 3,
46      "name": "Diaspora",
47      "path": "diaspora",
48      "kind": "group",
49      "full_path": "diaspora"
50    },
51    "import_status": "none",
52    "archived": false,
53    "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png",
54    "shared_runners_enabled": true,
55    "group_runners_enabled": true,
56    "forks_count": 0,
57    "star_count": 0,
58    "runners_token": "b8547b1dc37721d05889db52fa2f02",
59    "public_jobs": true,
60    "shared_with_groups": [],
61    "only_allow_merge_if_pipeline_succeeds": false,
62    "allow_merge_on_skipped_pipeline": false,
63    "allow_pipeline_trigger_approve_deployment": false,
64    "restrict_user_defined_variables": false,
65    "only_allow_merge_if_all_discussions_are_resolved": false,
66    "remove_source_branch_after_merge": false,
67    "request_access_enabled": false,
68    "merge_method": "merge",
69    "squash_option": "default_on",
70    "autoclose_referenced_issues": true,
71    "enforce_auth_checks_on_uploads": true,
72    "suggestion_commit_message": null,
73    "merge_commit_template": null,
74    "squash_commit_template": null,
75    "secret_push_protection_enabled": false,
76    "issue_branch_template": "gitlab/%{id}-%{title}",
77    "statistics": {
78      "commit_count": 37,
79      "storage_size": 1038090,
80      "repository_size": 1038090,
81      "lfs_objects_size": 0,
82      "job_artifacts_size": 0,
83      "pipeline_artifacts_size": 0,
84      "packages_size": 0,
85      "snippets_size": 0,
86      "uploads_size": 0,
87      "container_registry_size": 0
88    },
89    "container_registry_image_prefix": "registry.example.com/diaspora/diaspora-client",
90    "_links": {
91      "self": "http://example.com/api/v4/projects",
92      "issues": "http://example.com/api/v4/projects/1/issues",
93      "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
94      "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
95      "labels": "http://example.com/api/v4/projects/1/labels",
96      "events": "http://example.com/api/v4/projects/1/events",
97      "members": "http://example.com/api/v4/projects/1/members",
98      "cluster_agents": "http://example.com/api/v4/projects/1/cluster_agents"
99    }
100  },
101  {
102    "id": 6,
103    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
104    "description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
105    "default_branch": "main",
106    "visibility": "private",
107    "ssh_url_to_repo": "git@example.com:brightbox/puppet.git",
108    "http_url_to_repo": "http://example.com/brightbox/puppet.git",
109    "web_url": "http://example.com/brightbox/puppet",
110    "readme_url": "http://example.com/brightbox/puppet/blob/main/README.md",
111    "tag_list": [ //deprecated, use `topics` instead
112      "example",
113      "puppet"
114    ],
115    "topics": [
116      "example",
117      "puppet"
118    ],
119    "owner": {
120      "id": 4,
121      "name": "Brightbox",
122      "created_at": "2013-09-30T13:46:02Z"
123    },
124    "name": "Puppet",
125    "name_with_namespace": "Brightbox / Puppet",
126    "path": "puppet",
127    "path_with_namespace": "brightbox/puppet",
128    "issues_enabled": true,
129    "open_issues_count": 1,
130    "merge_requests_enabled": true,
131    "jobs_enabled": true,
132    "wiki_enabled": true,
133    "snippets_enabled": false,
134    "can_create_merge_request_in": true,
135    "resolve_outdated_diff_discussions": false,
136    "container_registry_enabled": false, // deprecated, use container_registry_access_level instead
137    "container_registry_access_level": "disabled",
138    "security_and_compliance_access_level": "disabled",
139    "created_at": "2013-09-30T13:46:02Z",
140    "updated_at": "2013-09-30T13:46:02Z",
141    "last_activity_at": "2013-09-30T13:46:02Z",
142    "creator_id": 3,
143    "namespace": {
144      "id": 4,
145      "name": "Brightbox",
146      "path": "brightbox",
147      "kind": "group",
148      "full_path": "brightbox"
149    },
150    "import_status": "none",
151    "import_error": null,
152    "permissions": {
153      "project_access": {
154        "access_level": 10,
155        "notification_level": 3
156      },
157      "group_access": {
158        "access_level": 50,
159        "notification_level": 3
160      }
161    },
162    "archived": false,
163    "avatar_url": null,
164    "shared_runners_enabled": true,
165    "group_runners_enabled": true,
166    "forks_count": 0,
167    "star_count": 0,
168    "runners_token": "b8547b1dc37721d05889db52fa2f02",
169    "public_jobs": true,
170    "shared_with_groups": [],
171    "only_allow_merge_if_pipeline_succeeds": false,
172    "allow_merge_on_skipped_pipeline": false,
173    "allow_pipeline_trigger_approve_deployment": false,
174    "restrict_user_defined_variables": false,
175    "only_allow_merge_if_all_discussions_are_resolved": false,
176    "remove_source_branch_after_merge": false,
177    "request_access_enabled": false,
178    "merge_method": "merge",
179    "squash_option": "default_on",
180    "auto_devops_enabled": true,
181    "auto_devops_deploy_strategy": "continuous",
182    "repository_storage": "default",
183    "approvals_before_merge": 0, // Deprecated. Use merge request approvals API instead.
184    "mirror": false,
185    "mirror_user_id": 45,
186    "mirror_trigger_builds": false,
187    "only_mirror_protected_branches": false,
188    "mirror_overwrites_diverged_branches": false,
189    "external_authorization_classification_label": null,
190    "packages_enabled": true,
191    "service_desk_enabled": false,
192    "service_desk_address": null,
193    "autoclose_referenced_issues": true,
194    "enforce_auth_checks_on_uploads": true,
195    "suggestion_commit_message": null,
196    "merge_commit_template": null,
197    "squash_commit_template": null,
198    "secret_push_protection_enabled": false,
199    "issue_branch_template": "gitlab/%{id}-%{title}",
200    "statistics": {
201      "commit_count": 12,
202      "storage_size": 2066080,
203      "repository_size": 2066080,
204      "lfs_objects_size": 0,
205      "job_artifacts_size": 0,
206      "pipeline_artifacts_size": 0,
207      "packages_size": 0,
208      "snippets_size": 0,
209      "uploads_size": 0,
210      "container_registry_size": 0
211    },
212    "container_registry_image_prefix": "registry.example.com/brightbox/puppet",
213    "_links": {
214      "self": "http://example.com/api/v4/projects",
215      "issues": "http://example.com/api/v4/projects/1/issues",
216      "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
217      "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
218      "labels": "http://example.com/api/v4/projects/1/labels",
219      "events": "http://example.com/api/v4/projects/1/events",
220      "members": "http://example.com/api/v4/projects/1/members",
221      "cluster_agents": "http://example.com/api/v4/projects/1/cluster_agents"
222    }
223  }
224]

按名称搜索项目#

按名称搜索对已认证用户可访问的项目。如果在没有身份验证的情况下访问此端点，它会列出公开可访问的项目。

plaintext
GET /projects

示例属性：

属性	类型	必需	描述
search	string	是	项目名称中包含的字符串。
order_by	string	否	按 id、name、created_at、star_count 或 last_activity_at 字段排序返回请求。
sort	string	否	按 asc 或 desc 顺序返回排序后的请求。

示例请求：

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects?search=test"

列出属性#

列出项目的属性。

列出用户#

获取项目的用户列表。

plaintext
GET /projects/:id/users

支持的属性：

属性	类型	必需	描述
id	integer or string	是	项目的 ID 或 URL 编码的路径。
search	string	否	搜索特定用户。
skip_users	integer array	否	过滤掉具有指定 ID 的用户。

示例响应：

json
1[
2  {
3    "id": 1,
4    "username": "john_smith",
5    "name": "John Smith",
6    "state": "active",
7    "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
8    "web_url": "http://localhost:3000/john_smith"
9  },
10  {
11    "id": 2,
12    "username": "jack_smith",
13    "name": "Jack Smith",
14    "state": "blocked",
15    "avatar_url": "http://gravatar.com/../e32131cd8.jpeg",
16    "web_url": "http://localhost:3000/jack_smith"
17  }
18]

列出群组#

获取此项目的祖先群组列表。

plaintext
GET /projects/:id/groups

支持的属性：

属性	类型	必需	描述
id	integer or string	是	项目的 ID 或 URL 编码的路径。
search	string	否	搜索特定群组。
shared_min_access_level	integer	否	限制为至少具有此角色 (access_level) 的共享群组。
shared_visible_only	boolean	否	限制为用户有权访问的共享群组。
skip_groups	array of integers	否	跳过传递的群组 ID。
with_shared	boolean	否	包括与此群组共享的项目。默认值为 false。

示例响应：

json
1[
2  {
3    "id": 1,
4    "name": "Foobar Group",
5    "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg",
6    "web_url": "http://localhost:3000/groups/foo-bar",
7    "full_name": "Foobar Group",
8    "full_path": "foo-bar"
9  },
10  {
11    "id": 2,
12    "name": "Shared Group",
13    "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/bar.jpg",
14    "web_url": "http://gitlab.example.com/groups/foo/bar",
15    "full_name": "Shared Group",
16    "full_path": "foo/shared"
17  }
18]

列出可共享的群组#

获取可以与项目共享的群组列表

plaintext
GET /projects/:id/share_locations

支持的属性：

属性	类型	必需	描述
id	integer or string	是	项目的 ID 或 URL 编码的路径。
search	string	否	搜索特定群组。

示例响应：

json
1[
2  {
3    "id": 22,
4    "web_url": "http://127.0.0.1:3000/groups/gitlab-org",
5    "name": "Gitlab Org",
6    "avatar_url": null,
7    "full_name": "Gitlab Org",
8    "full_path": "gitlab-org"
9  },
10  {
11    "id": 25,
12    "web_url": "http://127.0.0.1:3000/groups/gnuwget",
13    "name": "Gnuwget",
14    "avatar_url": null,
15    "full_name": "Gnuwget",
16    "full_path": "gnuwget"
17  }
18]

列出项目的邀请群组#

获取项目中的邀请群组列表。在没有身份验证的情况下访问时，仅返回公共邀请群组。此端点的速率限制为每分钟 60 次请求，按以下方式限制：

对于已认证用户的用户。
对于未认证用户的 IP 地址。

默认情况下，此请求一次返回 20 个结果，因为 API 结果是分页的。

plaintext
GET /projects/:id/invited_groups

支持的属性：

属性	类型	必需	描述
id	integer/string	是	群组的 ID 或 URL 编码的路径
search	string	否	返回匹配搜索条件的授权群组列表
min_access_level	integer	否	限制为当前用户至少具有指定角色 (access_level) 的群组
relation	array of strings	否	按关系（直接或继承）过滤群组
with_custom_attributes	boolean	否	在响应中包括自定义属性（仅限管理员）

示例响应：

json
1[
2  {
3    "id": 35,
4    "web_url": "https://gitlab.example.com/groups/twitter",
5    "name": "Twitter",
6    "avatar_url": null,
7    "full_name": "Twitter",
8    "full_path": "twitter"
9  }
10]

列出使用的编程语言#

获取项目中使用的编程语言列表及使用百分比。

plaintext
GET /projects/:id/languages

支持的属性：

属性	类型	必需	描述
id	integer or string	是	项目的 ID 或 URL 编码的路径。

示例请求：

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/languages"

示例响应：

json
1{
2  "Ruby": 66.69,
3  "JavaScript": 22.98,
4  "HTML": 7.91,
5  "CoffeeScript": 2.42
6}

管理项目#

管理项目，包括创建、删除和存档。

创建项目#

History

在极狐 GitLab 16.0 中，operations_access_level 已移除。
在极狐 GitLab 16.7 中，model_registry_access_level 已引入。

创建一个由已认证用户拥有的新项目。

如果您的 HTTP 仓库不是公开可访问的，请在 URL 中添加身份验证信息 https://username:password@gitlab.company.com/group/project.git，其中 password 是一个启用了 api 范围的公共访问密钥。

plaintext
POST /projects

支持的一般项目属性：

属性	类型	必需	描述
name	string	是（如果未提供 path）	新项目的名称。如果未提供，则等于路径。
path	string	是（如果未提供 name）	新项目的仓库名称。如果未提供，则基于名称生成（生成为小写并带有破折号）。路径不能以特殊字符开始或结束，并且不能包含连续的特殊字符。
allow_merge_on_skipped_pipeline	boolean	否	设置合并请求是否可以在跳过作业的情况下合并。
approvals_before_merge	integer	否	默认情况下应批准合并请求的批准者数量。要配置审批规则，请参见合并请求审批 API。在极狐 GitLab 16.0 中已弃用。专业版和旗舰版专用。
auto_cancel_pending_pipelines	string	否	自动取消挂起的流水线。此操作在启用状态和禁用状态之间切换；它不是一个布尔值。
auto_devops_deploy_strategy	string	否	自动部署策略（continuous、manual 或 timed_incremental）。
auto_devops_enabled	boolean	否	启用此项目的自动 DevOps。
autoclose_referenced_issues	boolean	否	设置是否在默认分支上自动关闭引用的议题。
avatar	mixed	否	项目头像的图像文件。
build_git_strategy	string	否	Git 策略。默认为 fetch。
build_timeout	integer	否	作业可以运行的最大时间（以秒为单位）。
ci_config_path	string	否	CI 配置文件的路径。
container_expiration_policy_attributes	hash	否	更新此项目的图像清理策略。接受：cadence（字符串）、keep_n（整数）、older_than（字符串）、name_regex（字符串）、name_regex_delete（字符串）、name_regex_keep（字符串）、enabled（布尔值）。有关 cadence、keep_n 和 older_than 值的更多信息，请参阅容器注册表文档。
container_registry_enabled	boolean	否	(已弃用) 启用此项目的容器注册表。请改用 container_registry_access_level。
default_branch	string	否	默认分支名称。需要 initialize_with_readme 为 true。
description	string	否	项目简短描述。
emails_disabled	boolean	否	(已弃用) 禁用电子邮件通知。请改用 emails_enabled。
emails_enabled	boolean	否	启用电子邮件通知。
external_authorization_classification_label	string	否	项目的分类标签。专业版和旗舰版专用。
group_runners_enabled	boolean	否	启用此项目的群组 runner。
group_with_project_templates_id	integer	否	对于群组级自定义模板，指定从中获取所有自定义项目模板的群组 ID。实例级模板留空。需要 use_custom_template 为 true。专业版和旗舰版专用。
import_url	string	否	从中导入仓库的 URL。当 URL 值不为空时，您不得将 initialize_with_readme 设置为 true。这样做可能会导致以下错误：not a git repository。
initialize_with_readme	boolean	否	是否创建仅包含 README.md 文件的 Git 仓库。默认是 false。当此布尔值为 true 时，您不得传递 import_url 或其他指定替代内容的此端点的属性。这样做可能会导致以下错误：not a git repository。
issues_enabled	boolean	否	(已弃用) 启用项目的议题。请改用 issues_access_level。
jobs_enabled	boolean	否	(已弃用) 启用项目的作业。请改用 builds_access_level。
lfs_enabled	boolean	否	启用 LFS。
merge_method	string	否	设置项目的合并方法。可以是 merge（合并提交）、rebase_merge（具有半线性历史的合并提交）或 ff（快进合并）。
merge_pipelines_enabled	boolean	否	启用或禁用合并结果流水线。
merge_requests_enabled	boolean	否	(已弃用) 启用项目的合并请求。请改用 merge_requests_access_level。
merge_trains_enabled	boolean	否	启用或禁用合并火车。
merge_trains_skip_train_allowed	boolean	否	允许合并火车合并请求无需等待流水线完成即可合并。
mirror_trigger_builds	boolean	否	拉取镜像触发构建。专业版和旗舰版专用。
mirror	boolean	否	启用项目中的拉取镜像。专业版和旗舰版专用。
namespace_id	integer	否	新项目的命名空间。指定群组 ID 或子群组 ID。如果未提供，则默认为当前用户的个人命名空间。
only_allow_merge_if_all_discussions_are_resolved	boolean	否	设置合并请求是否只能在所有讨论解决时合并。
only_allow_merge_if_all_status_checks_passed	boolean	否	表示合并请求的合并应被阻止，除非所有状态检查都通过。默认为 false。在极狐 GitLab 15.5 中引入了此功能，默认情况下禁用 only_allow_merge_if_all_status_checks_passed 功能标志。旗舰版专用。
only_allow_merge_if_pipeline_succeeds	boolean	否	设置合并请求是否只能在成功的流水线下合并。此设置在项目设置中被命名为流水线必须成功。
packages_enabled	boolean	否	启用或禁用软件包仓库功能。
printing_merge_request_link_enabled	boolean	否	显示从命令行推送时创建/查看合并请求的链接。
public_builds	boolean	否	(已弃用) 如果为 true，非项目成员可以查看作业。请改用 public_jobs。
public_jobs	boolean	否	如果为 true，非项目成员可以查看作业。
repository_object_format	string	否	仓库对象格式。默认为 sha1。在极狐 GitLab 16.9 中引入了此功能。
remove_source_branch_after_merge	boolean	否	默认情况下为所有新合并请求启用删除源分支选项。
repository_storage	string	否	仓库所在的存储分片。(仅限管理员)
request_access_enabled	boolean	否	允许用户请求成员访问。
resolve_outdated_diff_discussions	boolean	否	自动解决合并请求中的差异讨论。
shared_runners_enabled	boolean	否	启用此项目的实例 runner。
show_default_award_emojis	boolean	否	显示默认表情符号反应。
snippets_enabled	boolean	否	(已弃用) 启用项目的代码片段。请改用 snippets_access_level。
squash_option	string	否	选项之一：never、always、default_on 或 default_off。
tag_list	array	否	项目的标签列表；输入要最终分配给项目的标签数组。在极狐 GitLab 14.0 中已弃用。请改用 topics。
template_name	string	否	如果不使用 use_custom_template，则为内置项目模板的名称。如果使用 use_custom_template，则为自定义项目模板的名称。
template_project_id	integer	否	使用 use_custom_template 时，自定义项目模板的项目 ID。使用项目 ID 比使用 template_name 更可取，因为 template_name 可能不明确。专业版和旗舰版专用。
topics	array	否	项目的主题列表；输入要最终分配给项目的主题数组。
use_custom_template	boolean	否	使用自定义实例或群组（使用 group_with_project_templates_id）项目模板。专业版和旗舰版专用。
visibility	string	否	请参见项目可见性级别。
warn_about_potentially_unwanted_characters	boolean	否	启用有关项目中使用潜在不需要的字符的警告。
wiki_enabled	boolean	否	(已弃用) 启用项目的 wiki。请改用 wiki_access_level。

项目功能可见性设置具有访问控制选项，可以是：

disabled: 禁用功能。
private: 启用并将功能设置为 仅项目成员。
enabled: 启用并将功能设置为 具有访问权限的每个人。
public: 启用并将功能设置为 每个人。仅适用于 pages_access_level。

属性	类型	必需	描述
analytics_access_level	string	否	设置分析的可见性。
builds_access_level	string	否	设置流水线的可见性。
container_registry_access_level	string	否	设置容器注册表的可见性。
environments_access_level	string	否	设置环境的可见性。
feature_flags_access_level	string	否	设置特性标志的可见性。
forking_access_level	string	否	设置分叉的可见性。
infrastructure_access_level	string	否	设置基础设施管理的可见性。
issues_access_level	string	否	设置议题的可见性。
merge_requests_access_level	string	否	设置合并请求的可见性。
model_experiments_access_level	string	否	设置机器学习模型实验的可见性。
model_registry_access_level	string	否	设置机器学习模型注册表的可见性。
monitor_access_level	string	否	设置应用性能监控的可见性。
pages_access_level	string	否	设置极狐 GitLab Pages的可见性。
releases_access_level	string	否	设置发布的可见性。
repository_access_level	string	否	设置仓库的可见性。
requirements_access_level	string	否	设置需求管理的可见性。
security_and_compliance_access_level	string	否	设置安全与合规的可见性。
snippets_access_level	string	否	设置代码片段的可见性。
wiki_access_level	string	否	设置wiki的可见性。

示例请求：

shell
curl --request POST --header "PRIVATE-TOKEN: <your-token>" \
     --header "Content-Type: application/json" --data '{
        "name": "new_project", "description": "New Project", "path": "new_project",
        "namespace_id": "42", "initialize_with_readme": "true"}' \
     --url "https://gitlab.example.com/api/v4/projects/"

为用户创建项目#

History

在极狐 GitLab 16.0 中，operations_access_level 已移除。
在极狐 GitLab 16.7 中，model_registry_access_level 已引入。

为用户创建项目。

先决条件：

您必须是管理员。

如果您的 HTTP 仓库不是公开可访问的，请在 URL 中添加身份验证信息。例如，https://username:password@gitlab.company.com/group/project.git，其中 password 是一个启用了 api 范围的公共访问密钥。

plaintext
POST /projects/user/:user_id

支持的一般项目属性：

属性	类型	必需	描述
name	string	是	新项目的名称。
user_id	integer	是	项目所有者的用户 ID。
allow_merge_on_skipped_pipeline	boolean	否	设置合并请求是否可以在跳过作业的情况下合并。
approvals_before_merge	integer	否	默认情况下应批准合并请求的批准者数量。在极狐 GitLab 16.0 中已弃用。要配置审批规则，请参见合并请求审批 API。专业版和旗舰版专用。
auto_cancel_pending_pipelines	string	否	自动取消挂起的流水线。此操作在启用状态和禁用状态之间切换；它不是一个布尔值。
auto_devops_deploy_strategy	string	否	自动部署策略（continuous、manual 或 timed_incremental）。
auto_devops_enabled	boolean	否	启用此项目的自动 DevOps。
autoclose_referenced_issues	boolean	否	设置是否在默认分支上自动关闭引用的议题。
avatar	mixed	否	项目头像的图像文件。
build_git_strategy	string	否	Git 策略。默认为 fetch。
build_timeout	integer	否	作业可以运行的最大时间（以秒为单位）。
ci_config_path	string	否	CI 配置文件的路径。
container_registry_enabled	boolean	否	(已弃用) 启用此项目的容器注册表。请改用 container_registry_access_level。
default_branch	string	否	默认分支名称。需要 initialize_with_readme 为 true。
description	string	否	项目简短描述。
emails_disabled	boolean	否	(已弃用) 禁用电子邮件通知。请改用 emails_enabled。
emails_enabled	boolean	否	启用电子邮件通知。
enforce_auth_checks_on_uploads	boolean	否	在上传时强制执行身份验证检查。
external_authorization_classification_label	string	否	项目的分类标签。专业版和旗舰版专用。
group_runners_enabled	boolean	否	启用此项目的群组 runner。
group_with_project_templates_id	integer	否	对于群组级自定义模板，指定从中获取所有自定义项目模板的群组 ID。实例级模板留空。需要 use_custom_template 为 true。专业版和旗舰版专用。
import_url	string	否	从中导入仓库的 URL。
initialize_with_readme	boolean	否	默认为 false。
issue_branch_template	string	否	用于建议从议题创建分支的名称的模板。在极狐 GitLab 15.6 中引入。
issues_enabled	boolean	否	(已弃用) 启用项目的议题。请改用 issues_access_level。
jobs_enabled	boolean	否	(已弃用) 启用项目的作业。请改用 builds_access_level。
lfs_enabled	boolean	否	启用 LFS。
merge_commit_template	string	否	用于创建合并请求中的合并提交消息的模板。
merge_method	string	否	设置项目的合并方法。可以是 merge（合并提交）、rebase_merge（具有半线性历史的合并提交）或 ff（快进合并）。
merge_requests_enabled	boolean	否	(已弃用) 启用项目的合并请求。请改用 merge_requests_access_level。
mirror_trigger_builds	boolean	否	拉取镜像触发构建。专业版和旗舰版专用。
mirror	boolean	否	启用项目中的拉取镜像。专业版和旗舰版专用。
namespace_id	integer	否	新项目的命名空间（默认为当前用户的命名空间）。
only_allow_merge_if_all_discussions_are_resolved	boolean	否	设置合并请求是否只能在所有讨论解决时合并。
only_allow_merge_if_all_status_checks_passed	boolean	否	表示合并请求的合并应被阻止，除非所有状态检查都通过。默认为 false。在极狐 GitLab 15.5 中引入了此功能，默认情况下禁用 only_allow_merge_if_all_status_checks_passed 功能标志。旗舰版专用。
only_allow_merge_if_pipeline_succeeds	boolean	否	设置合并请求是否只能在成功的流水线下合并。
packages_enabled	boolean	否	启用或禁用软件包仓库功能。
path	string	否	新项目的自定义仓库名称。默认情况下基于名称生成。
printing_merge_request_link_enabled	boolean	否	显示从命令行推送时创建/查看合并请求的链接。
public_builds	boolean	否	(已弃用) 如果为 true，非项目成员可以查看作业。请改用 public_jobs。
public_jobs	boolean	否	如果为 true，非项目成员可以查看作业。
repository_object_format	string	否	仓库对象格式。默认为 sha1。在极狐 GitLab 16.9 中引入了此功能。
remove_source_branch_after_merge	boolean	否	默认情况下为所有新合并请求启用删除源分支选项。
repository_storage	string	否	仓库所在的存储分片。(仅限管理员)
request_access_enabled	boolean	否	允许用户请求成员访问权限。
resolve_outdated_diff_discussions	boolean	否	自动解决合并请求中已过时的差异讨论。
shared_runners_enabled	boolean	否	为此项目启用实例级 runner。
show_default_award_emojis	boolean	否	显示默认表情反应。
snippets_enabled	boolean	否	(已弃用) 为此项目启用代码片段。请改用 snippets_access_level。
squash_commit_template	string	否	用于在合并请求中创建压缩提交消息的模板。
squash_option	string	否	可以是 never、always、default_on 或 default_off 之一。
suggestion_commit_message	string	否	用于应用合并请求建议的提交消息。
tag_list	array	否	(在 GitLab 14.0 中已弃用) 项目的标签列表；放置最终应分配给项目的标签数组。请改用 topics。
template_name	string	否	当不使用 use_custom_template 时，指定内置项目模板的名称。当与 use_custom_template 一起使用时，指定自定义项目模板的名称。
topics	array	否	项目的主题列表。
use_custom_template	boolean	否	使用自定义实例或群组（与 group_with_project_templates_id 一起使用）项目模板。仅适用于高级版和旗舰版。
visibility	string	否	请参阅项目可见性级别。
warn_about_potentially_unwanted_characters	boolean	否	在此项目中启用关于使用潜在不需要字符的警告。
wiki_enabled	boolean	否	(已弃用) 为此项目启用 wiki。请改用 wiki_access_level。

项目功能可见性设置的访问控制选项可以是以下之一：

disabled：禁用该功能。
private：启用并将功能设置为仅项目成员。
enabled：启用并将功能设置为所有有访问权限的人。
public：启用并将功能设置为所有人。仅适用于 pages_access_level。

属性	类型	必需	描述
analytics_access_level	string	否	设置分析的可见性。
builds_access_level	string	否	设置流水线的可见性。
container_registry_access_level	string	否	设置容器注册表的可见性。
environments_access_level	string	否	设置环境的可见性。
feature_flags_access_level	string	否	设置功能标志的可见性。
forking_access_level	string	否	设置分叉的可见性。
infrastructure_access_level	string	否	设置基础设施管理的可见性。
issues_access_level	string	否	设置议题的可见性。
merge_requests_access_level	string	否	设置合并请求的可见性。
model_experiments_access_level	string	否	设置机器学习模型实验的可见性。
model_registry_access_level	string	否	设置机器学习模型注册表的可见性。
monitor_access_level	string	否	设置应用性能监控的可见性。
pages_access_level	string	否	设置GitLab Pages的可见性。
releases_access_level	string	否	设置发布的可见性。
repository_access_level	string	否	设置仓库的可见性。
requirements_access_level	string	否	设置需求管理的可见性。
security_and_compliance_access_level	string	否	设置安全和合规的可见性。
snippets_access_level	string	否	设置代码片段的可见性。
wiki_access_level	string	否	设置wiki的可见性。

编辑项目#

History

operations_access_level 在 GitLab 16.0 中移除。
model_registry_access_level 在 GitLab 16.7 中引入。

更新现有项目。

如果您的 HTTP 仓库不是公开可访问的，请在 URL 中添加身份验证信息 https://username:password@gitlab.company.com/group/project.git，其中 password 是启用了 api 范围的公共访问密钥。

导入成员

从另一个项目导入成员。

如果导入成员在目标项目中的角色是：

维护者，那么源项目中具有所有者角色的成员将被导入为维护者角色。
所有者，那么源项目中具有所有者角色的成员将被导入为所有者角色。

plaintext
POST /projects/:id/import_project_members/:project_id

支持的属性：

属性	类型	必需	描述
id	integer or string	是	目标项目接收成员的 ID 或 URL 编码路径。
project_id	integer or string	是	导入成员的源项目的 ID 或 URL 编码路径。

请求示例：

shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/import_project_members/32"

成功时返回 200 OK。
如果目标或源项目不存在或请求者无法访问，则返回 404 Project Not Found。
如果项目成员的导入未成功完成，则返回 422 Unprocessable Entity。

响应示例：

当所有电子邮件成功发送时 (200 HTTP 状态码):
```
json
{  "status":  "success"  }
```

当导入一个或多个成员时出现任何错误 (200 HTTP 状态码):

json
1{
2  "status": "error",
3  "message": {
4               "john_smith": "Some individual error message",
5               "jane_smith": "Some individual error message"
6             },
7  "total_members_count": 3
8}

当出现系统错误时 (404 和 422 HTTP 状态码):

json
{  "message":  "Import failed"  }

归档项目

归档一个项目。

先决条件：

你必须是管理员或被分配为项目的所有者角色。

此端点是幂等的。归档已归档的项目不会改变项目。

plaintext
POST /projects/:id/archive

支持的属性：

属性	类型	必需	描述
id	integer or string	是	项目的 ID 或 URL 编码路径。

请求示例：

shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/archive"

响应示例：

json
1{
2  "id": 3,
3  "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
4  "description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
5  "default_branch": "main",
6  "visibility": "private",
7  "ssh_url_to_repo": "git@example.com:diaspora/diaspora-project-site.git",
8  "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
9  "web_url": "http://example.com/diaspora/diaspora-project-site",
10  "readme_url": "http://example.com/diaspora/diaspora-project-site/blob/main/README.md",
11  "tag_list": [ //已弃用, 使用 `topics` 替代
12    "example",
13    "disapora project"
14  ],
15  "topics": [
16    "example",
17    "disapora project"
18  ],
19  "owner": {
20    "id": 3,
21    "name": "Diaspora",
22    "created_at": "2013-09-30T13:46:02Z"
23  },
24  "name": "Diaspora Project Site",
25  "name_with_namespace": "Diaspora / Diaspora Project Site",
26  "path": "diaspora-project-site",
27  "path_with_namespace": "diaspora/diaspora-project-site",
28  "repository_object_format": "sha1",
29  "issues_enabled": true,
30  "open_issues_count": 1,
31  "merge_requests_enabled": true,
32  "jobs_enabled": true,
33  "wiki_enabled": true,
34  "snippets_enabled": false,
35  "can_create_merge_request_in": true,
36  "resolve_outdated_diff_discussions": false,
37  "container_registry_enabled": false, // 已弃用, 使用 container_registry_access_level 代替
38  "container_registry_access_level": "disabled",
39  "security_and_compliance_access_level": "disabled",
40  "created_at": "2013-09-30T13:46:02Z",
41  "updated_at": "2013-09-30T13:46:02Z",
42  "last_activity_at": "2013-09-30T13:46:02Z",
43  "creator_id": 3,
44  "namespace": {
45    "id": 3,
46    "name": "Diaspora",
47    "path": "diaspora",
48    "kind": "group",
49    "full_path": "diaspora"
50  },
51  "import_status": "none",
52  "import_error": null,
53  "permissions": {
54    "project_access": {
55      "access_level": 10,
56      "notification_level": 3
57    },
58    "group_access": {
59      "access_level": 50,
60      "notification_level": 3
61    }
62  },
63  "archived": true,
64  "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png",
65  "license_url": "http://example.com/diaspora/diaspora-client/blob/main/LICENSE",
66  "license": {
67    "key": "lgpl-3.0",
68    "name": "GNU Lesser General Public License v3.0",
69    "nickname": "GNU LGPLv3",
70    "html_url": "http://choosealicense.com/licenses/lgpl-3.0/",
71    "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt"
72  },
73  "shared_runners_enabled": true,
74  "group_runners_enabled": true,
75  "forks_count": 0,
76  "star_count": 0,
77  "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b",
78  "ci_default_git_depth": 50,
79  "ci_forward_deployment_enabled": true,
80  "ci_forward_deployment_rollback_allowed": true,
81  "ci_allow_fork_pipelines_to_run_in_parent_project": true,
82  "ci_id_token_sub_claim_components": ["project_path", "ref_type", "ref"],
83  "ci_separated_caches": true,
84  "ci_restrict_pipeline_cancellation_role": "developer",
85  "ci_pipeline_variables_minimum_override_role": "maintainer",
86  "ci_push_repository_for_job_token_allowed": false,
87  "public_jobs": true,
88  "shared_with_groups": [],
89  "only_allow_merge_if_pipeline_succeeds": false,
90  "allow_merge_on_skipped_pipeline": false,
91  "allow_pipeline_trigger_approve_deployment": false,
92  "restrict_user_defined_variables": false,
93  "only_allow_merge_if_all_discussions_are_resolved": false,
94  "remove_source_branch_after_merge": false,
95  "request_access_enabled": false,
96  "merge_method": "merge",
97  "squash_option": "default_on",
98  "autoclose_referenced_issues": true,
99  "enforce_auth_checks_on_uploads": true,
100  "suggestion_commit_message": null,
101  "merge_commit_template": null,
102  "secret_push_protection_enabled": false,
103  "container_registry_image_prefix": "registry.example.com/diaspora/diaspora-project-site",
104  "_links": {
105    "self": "http://example.com/api/v4/projects",
106    "issues": "http://example.com/api/v4/projects/1/issues",
107    "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
108    "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
109    "labels": "http://example.com/api/v4/projects/1/labels",
110    "events": "http://example.com/api/v4/projects/1/events",
111    "members": "http://example.com/api/v4/projects/1/members",
112    "cluster_agents": "http://example.com/api/v4/projects/1/cluster_agents"
113  }
114}

取消归档项目

取消归档一个项目。

先决条件：

你必须是管理员或被分配为项目的所有者角色。

此端点是幂等的。取消归档未归档的项目不会改变项目。

plaintext
POST /projects/:id/unarchive

支持的属性：

属性	类型	必需	描述
id	integer or string	是	项目的 ID 或 URL 编码路径。

请求示例：

shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/unarchive"

响应示例：

json
1{
2  "id": 3,
3  "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
4  "description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
5  "default_branch": "main",
6  "visibility": "private",
7  "ssh_url_to_repo": "git@example.com:diaspora/diaspora-project-site.git",
8  "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
9  "web_url": "http://example.com/diaspora/diaspora-project-site",
10  "readme_url": "http://example.com/diaspora/diaspora-project-site/blob/main/README.md",
11  "tag_list": [ //已弃用, 使用 `topics` 替代
12    "example",
13    "disapora project"
14  ],
15  "topics": [
16    "example",
17    "disapora project"
18  ],
19  "owner": {
20    "id": 3,
21    "name": "Diaspora",
22    "created_at": "2013-09-30T13:46:02Z"
23  },
24  "name": "Diaspora Project Site",
25  "name_with_namespace": "Diaspora / Diaspora Project Site",
26  "path": "diaspora-project-site",
27  "path_with_namespace": "diaspora/diaspora-project-site",
28  "repository_object_format": "sha1",
29  "issues_enabled": true,
30  "open_issues_count": 1,
31  "merge_requests_enabled": true,
32  "jobs_enabled": true,
33  "wiki_enabled": true,
34  "snippets_enabled": false,
35  "can_create_merge_request_in": true,
36  "resolve_outdated_diff_discussions": false,
37  "container_registry_enabled": false, // 已弃用, 使用 container_registry_access_level 代替
38  "container_registry_access_level": "disabled",
39  "security_and_compliance_access_level": "disabled",
40  "created_at": "2013-09-30T13:46:02Z",
41  "updated_at": "2013-09-30T13:46:02Z",
42  "last_activity_at": "2013-09-30T13:46:02Z",
43  "creator_id": 3,
44  "namespace": {
45    "id": 3,
46    "name": "Diaspora",
47    "path": "diaspora",
48    "kind": "group",
49    "full_path": "diaspora"
50  },
51  "import_status": "none",
52  "import_error": null,
53  "permissions": {
54    "project_access": {
55      "access_level": 10,
56      "notification_level": 3
57    },
58    "group_access": {
59      "access_level": 50,
60      "notification_level": 3
61    }
62  },
63  "archived": false,
64  "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png",
65  "license_url": "http://example.com/diaspora/diaspora-client/blob/main/LICENSE",
66  "license": {
67    "key": "lgpl-3.0",
68    "name": "GNU Lesser General Public License v3.0",
69    "nickname": "GNU LGPLv3",
70    "html_url": "http://choosealicense.com/licenses/lgpl-3.0/",
71    "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt"
72  },
73  "shared_runners_enabled": true,
74  "group_runners_enabled": true,
75  "forks_count": 0,
76  "star_count": 0,
77  "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b",
78  "ci_default_git_depth": 50,
79  "ci_forward_deployment_enabled": true,
80  "ci_forward_deployment_rollback_allowed": true,
81  "ci_allow_fork_pipelines_to_run_in_parent_project": true,
82  "ci_id_token_sub_claim_components": ["project_path", "ref_type", "ref"],
83  "ci_separated_caches": true,
84  "ci_restrict_pipeline_cancellation_role": "developer",
85  "ci_pipeline_variables_minimum_override_role": "maintainer",
86  "ci_push_repository_for_job_token_allowed": false,
87  "public_jobs": true,
88  "shared_with_groups": [],
89  "only_allow_merge_if_pipeline_succeeds": false,
90  "allow_merge_on_skipped_pipeline": false,
91  "allow_pipeline_trigger_approve_deployment": false,
92  "restrict_user_defined_variables": false,
93  "only_allow_merge_if_all_discussions_are_resolved": false,
94  "remove_source_branch_after_merge": false,
95  "request_access_enabled": false,
96  "merge_method": "merge",
97  "squash_option": "default_on",
98  "autoclose_referenced_issues": true,
99  "enforce_auth_checks_on_uploads": true,
100  "suggestion_commit_message": null,
101  "merge_commit_template": null,
102  "container_registry_image_prefix": "registry.example.com/diaspora/diaspora-project-site",
103  "secret_push_protection_enabled": false,
104  "_links": {
105    "self": "http://example.com/api/v4/projects",
106    "issues": "http://example.com/api/v4/projects/1/issues",
107    "merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
108    "repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
109    "labels": "http://example.com/api/v4/projects/1/labels",
110    "events": "http://example.com/api/v4/projects/1/events",
111    "members": "http://example.com/api/v4/projects/1/members",
112    "cluster_agents": "http://example.com/api/v4/projects/1/cluster_agents"
113  }
114}

删除项目

删除一个项目。此端点：

删除项目及其所有相关资源，包括议题和合并请求。
在专业版或旗舰版级别，启用了延迟项目删除。
从极狐GitLab 15.11 开始，在专业版或旗舰版级别，如果：
- 项目已标记为删除。
- 传递了 permanently_remove 和 full_path 参数。
从极狐GitLab 16.0 开始，在专业版或旗舰版级别，默认启用延迟项目删除。删除将在默认删除延迟中指定的天数后发生。

在 **管理员** 区域从删除保护设置中立即删除项目的选项在极狐GitLab 15.9 中被弃用，并在极狐GitLab 16.0 中移除。

plaintext
DELETE /projects/:id

支持的属性：

属性	类型	必需	描述
id	integer or string	是	项目的 ID 或 URL 编码路径。
full_path	string	否	在极狐GitLab 15.11 中引入的项目的完整路径，用于与 permanently_remove 一起使用。要查找项目路径，请使用获取单个项目中的 path_with_namespace。仅限专业版和旗舰版。
permanently_remove	boolean/string	否	如果项目已标记为删除，则立即删除项目。在极狐GitLab 15.11 中引入。仅限专业版和旗舰版。

恢复标记为删除的项目

级别：专业版，旗舰版
提供：JihuLab.com，极狐GitLab 私有化部署，极狐GitLab 专属

恢复标记为删除的项目。

plaintext
POST /projects/:id/restore

支持的属性：

属性	类型	必需	描述
id	integer or string	是	项目的 ID 或 URL 编码路径。

将项目转移到新命名空间

将项目转移到新命名空间。

有关项目转移的先决条件的信息，请参阅将项目转移到其他命名空间。

plaintext
PUT /projects/:id/transfer

支持的属性：

属性	类型	必需	描述
id	integer or string	是	项目的 ID 或 URL 编码路径。
namespace	integer or string	是	要转移到的命名空间的 ID 或路径。

请求示例：

shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/transfer?namespace=14"

响应示例：

json
1  {
2  "id": 7,
3  "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
4  "description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
5  "name": "hello-world",
6  "name_with_namespace": "cute-cats / hello-world",
7  "path": "hello-world",
8  "path_with_namespace": "cute-cats/hello-world",
9  "created_at": "2020-10-15T16:25:22.415Z",
10  "updated_at": "2020-10-15T16:25:22.415Z",
11  "default_branch": "main",
12  "tag_list": [], //已弃用, 使用 `topics` 替代
13  "topics": [],
14  "ssh_url_to_repo": "git@gitlab.example.com:cute-cats/hello-world.git",
15  "http_url_to_repo": "https://gitlab.example.com/cute-cats/hello-world.git",
16  "web_url": "https://gitlab.example.com/cute-cats/hello-world",
17  "readme_url": "https://gitlab.example.com/cute-cats/hello-world/-/blob/main/README.md",
18  "avatar_url": null,
19  "forks_count": 0,
20  "star_count": 0,
21  "last_activity_at": "2020-10-15T16:25:22.415Z",
22  "namespace": {
23    "id": 18,
24    "name": "cute-cats",
25    "path": "cute-cats",
26    "kind": "group",
27    "full_path": "cute-cats",
28    "parent_id": null,
29    "avatar_url": null,
30    "web_url": "https://gitlab.example.com/groups/cute-cats"
31  },
32  "container_registry_image_prefix": "registry.example.com/cute-cats/hello-world",
33  "_links": {
34    "self": "https://gitlab.example.com/api/v4/projects/7",
35    "issues": "https://gitlab.example.com/api/v4/projects/7/issues",
36    "merge_requests": "https://gitlab.example.com/api/v4/projects/7/merge_requests",
37    "repo_branches": "https://gitlab.example.com/api/v4/projects/7/repository/branches",
38    "labels": "https://gitlab.example.com/api/v4/projects/7/labels",
39    "events": "https://gitlab.example.com/api/v4/projects/7/events",
40    "members": "https://gitlab.example.com/api/v4/projects/7/members"
41  },
42  "packages_enabled": true,
43  "empty_repo": false,
44  "archived": false,
45  "visibility": "private",
46  "resolve_outdated_diff_discussions": false,
47  "container_registry_enabled": true, // 已弃用, 使用 container_registry_access_level 代替
48  "container_registry_access_level": "enabled",
49  "container_expiration_policy": {
50    "cadence": "7d",
51    "enabled": false,
52    "keep_n": null,
53    "older_than": null,
54    "name_regex": null,
55    "name_regex_keep": null,
56    "next_run_at": "2020-10-22T16:25:22.746Z"
57  },
58  "issues_enabled": true,
59  "merge_requests_enabled": true,
60  "wiki_enabled": true,
61  "jobs_enabled": true,
62  "snippets_enabled": true,
63  "service_desk_enabled": false,
64  "service_desk_address": null,
65  "can_create_merge_request_in": true,
66  "issues_access_level": "enabled",
67  "repository_access_level": "enabled",
68  "merge_requests_access_level": "enabled",
69  "forking_access_level": "enabled",
70  "analytics_access_level": "enabled",
71  "wiki_access_level": "enabled",
72  "builds_access_level": "enabled",
73  "snippets_access_level": "enabled",
74  "pages_access_level": "enabled",
75  "security_and_compliance_access_level": "enabled",
76  "emails_disabled": null,
77  "emails_enabled": null,
78  "shared_runners_enabled": true,
79  "group_runners_enabled": true,
80  "lfs_enabled": true,
81  "creator_id": 2,
82  "import_status": "none",
83  "open_issues_count": 0,
84  "ci_default_git_depth": 50,
85  "public_jobs": true,
86  "build_timeout": 3600,
87  "auto_cancel_pending_pipelines": "enabled",
88  "ci_config_path": null,
89  "shared_with_groups": [],
90  "only_allow_merge_if_pipeline_succeeds": false,
91  "allow_merge_on_skipped_pipeline": null,
92  "allow_pipeline_trigger_approve_deployment": false,
93  "restrict_user_defined_variables": false,
94  "request_access_enabled": true,
95  "only_allow_merge_if_all_discussions_are_resolved": false,
96  "remove_source_branch_after_merge": true,
97  "printing_merge_request_link_enabled": true,
98  "merge_method": "merge",
99  "squash_option": "default_on",
100  "suggestion_commit_message": null,
101  "merge_commit_template": null,
102  "auto_devops_enabled": true,
103  "auto_devops_deploy_strategy": "continuous",
104  "autoclose_referenced_issues": true,
105  "approvals_before_merge": 0, // 已弃用. 请改用合并请求审批 API。
106  "mirror": false,
107  "compliance_frameworks": [],
108  "warn_about_potentially_unwanted_characters": true,
109  "secret_push_protection_enabled": false
110}

列出可用于项目转移的群组

History

在极狐GitLab 15.4 中引入。

检索用户可以将项目转移到的群组列表。

plaintext
GET /projects/:id/transfer_locations

支持的属性：

属性	类型	必需	描述
id	integer or string	是	项目的 ID 或 URL 编码路径。
search	string	否	要搜索的群组名称。

请求示例：

shell
curl --request GET "https://gitlab.example.com/api/v4/projects/1/transfer_locations"

响应示例：

json
1[
2  {
3    "id": 27,
4    "web_url": "https://gitlab.example.com/groups/gitlab",
5    "name": "GitLab",
6    "avatar_url": null,
7    "full_name": "GitLab",
8    "full_path": "GitLab"
9  },
10  {
11    "id": 31,
12    "web_url": "https://gitlab.example.com/groups/foobar",
13    "name": "FooBar",
14    "avatar_url": null,
15    "full_name": "FooBar",
16    "full_path": "FooBar"
17  }
18]

上传项目头像

上传头像到指定项目。

plaintext
PUT /projects/:id

支持的属性：

属性	类型	必需	描述
avatar	string	是	要上传的文件。
id	integer or string	是	项目的 ID 或 URL 编码路径。

要从文件系统上传头像，请使用 --form 参数。这会导致 cURL 使用 Content-Type: multipart/form-data 标头发布数据。file= 参数必须指向文件系统上的图像文件，并以 @ 开头。例如：

请求示例：

shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "avatar=@dk.png" "https://gitlab.example.com/api/v4/projects/5"

响应示例：

json
{
  "avatar_url": "https://gitlab.example.com/uploads/-/system/project/avatar/2/dk.png"
}

下载项目头像

History

在极狐GitLab 16.9 中引入。

下载项目头像。如果项目是公开访问的，可以在没有身份验证的情况下访问此端点。

plaintext
GET /projects/:id/avatar

支持的属性：

属性	类型	必需	描述
id	integer or string	是	项目的 ID 或 URL 编码路径。

请求示例：

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/avatar"

移除项目头像

History

在极狐GitLab 15.4 中引入。

要移除项目头像，请对 avatar 属性使用空值。

请求示例：

shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     --data "avatar=" "https://gitlab.example.com/api/v4/projects/5"

共享项目

将项目与群组共享。

与群组共享项目

将项目与群组共享。

plaintext
POST /projects/:id/share

支持的属性：

属性	类型	必需	描述
group_access	integer	是	授予群组的角色（access_level）。
group_id	integer	是	要共享的群组 ID。
id	integer or string	是	项目的 ID 或 URL 编码路径。
expires_at	string	否	共享的过期日期，ISO 8601 格式。例如，2016-09-26。

删除群组中的共享项目链接

取消项目与群组的共享。成功时返回 204 且无内容。

plaintext
DELETE /projects/:id/share/:group_id

支持的属性：

属性	类型	必需	描述
group_id	integer	是	群组的 ID。
id	integer or string	是	项目的 ID 或 URL 编码路径。

请求示例：

shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/share/17"

启动项目的维护任务

启动项目的维护任务。

plaintext
POST /projects/:id/housekeeping

支持的属性：

属性	类型	必需	描述
id	integer or string	是	项目的 ID 或 URL 编码路径。
task	string	否	prune 触发手动删除无法到达的对象或 eager 触发积极的维护任务。

实时安全扫描

级别：旗舰版
提供：JihuLab.com
状态：实验

History

在极狐GitLab 17.6 中引入。此功能是一个实验。

返回单个文件的实时 SAST 扫描结果。

plaintext
POST /projects/:id/security_scans/sast/scan

支持的属性：

属性	类型	必需	描述
id	integer or string	是	项目的 ID 或 URL 编码路径。

请求示例：

shell
1curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
2 --header "Content-Type: application/json" \
3 --data '{
4  "file_path":"src/main.c",
5  "content":"#include<string.h>\nint main(int argc, char **argv) {\n  char buff[128];\n  strcpy(buff, argv[1]);\n  return 0;\n}\n"
6 }' \
7 --url "https://gitlab.example.com/api/v4/projects/:id/security_scans/sast/scan"

响应示例：

json
1{
2  "vulnerabilities": [
3    {
4      "name": "Insecure string processing function (strcpy)",
5      "description": "The `strcpy` family of functions do not provide the ability to limit or check buffer\nsizes before copying to a destination buffer. This can lead to buffer overflows. Consider\nusing more secure alternatives such as `strncpy` and provide the correct limit to the\ndestination buffer and ensure the string is null terminated.\n\nFor more information please see: https://linux.die.net/man/3/strncpy\n\nIf developing for C Runtime Library (CRT), more secure versions of these functions should be\nused, see:\nhttps://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l?view=msvc-170\n",
6      "severity": "High",
7      "location": {
8        "file": "src/main.c",
9        "start_line": 5,
10        "end_line": 5,
11        "start_column": 3,
12        "end_column": 23
13      }
14    }
15  ]
16}

下载 Git 仓库快照

只有管理员用户才能访问此端点。

下载项目（或维基，如果请求）Git 仓库的快照。此快照始终以未压缩的 tar) 格式。

如果仓库损坏到 git clone 不起作用的程度，快照可能允许检索部分数据。

plaintext
GET /projects/:id/snapshot

支持的属性：

属性	类型	必需	描述
id	integer or string	是	项目的 ID 或 URL 编码路径。
wiki	boolean	否	是否下载维基，而不是项目仓库。

获取仓库存储路径

如果未使用 Gitaly 集群，则获取指定项目的仓库存储路径。如果使用 Gitaly 集群，请参见 Praefect 生成的副本路径。

仅管理员可用。

plaintext
GET /projects/:id/storage

支持的属性：

属性	类型	必需	描述
id	integer or string	是	项目的 ID 或 URL 编码路径。

json
1[
2  {
3    "project_id": 1,
4    "disk_path": "@hashed/6b/86/6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b",
5    "created_at": "2012-10-12T17:04:47Z",
6    "repository_storage": "default"
7  }
8]

秘密推送保护状态

级别：旗舰版

History

在极狐GitLab 17.3 中引入。

如果您至少拥有开发者角色，以下请求也可能返回 secret_push_protection_enabled 值。请注意，其中一些请求对角色有更严格的要求。请参阅上述端点以获取说明。使用此信息确定项目是否启用了秘密推送保护。要修改 secret_push_protection_enabled 值，请使用项目安全设置 API。

GET /projects
GET /projects/:id
GET /users/:user_id/projects
GET /users/:user_id/contributed_projects
PUT /projects/:project_id/transfer?namespace=:namespace_id
PUT /projects/:id
POST /projects
POST /projects/user/:user_id
POST /projects/:id/archive
POST /projects/:id/unarchive

响应示例：

json
1{
2  "id": 1,
3  "project_id": 3,
4  "secret_push_protection_enabled": true,
5  ...
6}