{{< details >}}
- Tier: 基础版,专业版,旗舰版
- Offering: JihuLab.com,私有化部署
{{< /details >}}
使用此 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。仅适用于专业版和旗舰版。 |
获取单个项目
获取特定项目。如果项目公开可访问,则可以在不进行身份验证的情况下访问此端点。
GET /projects/:id
支持的属性:
属性 | 类型 | 是否必需 | 描述 |
---|---|---|---|
id |
整数或字符串 | 是 | 项目的 ID 或 URL 编码路径。 |
license |
布尔值 | 否 | 包含项目许可证数据。 |
statistics |
布尔值 | 否 | 包含项目统计数据。仅对拥有至少报告者角色的用户可用。 |
with_custom_attributes |
布尔值 | 否 | 在响应中包含自定义属性。(仅限管理员) |
响应中包括与容器注册表存储大小相关的属性:
-
container_registry_size
:项目中所有容器存储库使用的总存储大小(字节)。每当推送或删除容器镜像时更新。对于极狐GitLab 私有化部署实例,需要启用 容器注册表元数据数据库。
示例响应:
{
"id": 3,
"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
"description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
"default_branch": "main",
"visibility": "private",
"ssh_url_to_repo": "git@example.com:diaspora/diaspora-project-site.git",
"http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
"web_url": "http://example.com/diaspora/diaspora-project-site",
"readme_url": "http://example.com/diaspora/diaspora-project-site/blob/main/README.md",
"tag_list": [ //deprecated, use `topics` instead
"example",
"disapora project"
],
"topics": [
"example",
"disapora project"
],
"owner": {
"id": 3,
"name": "Diaspora",
"created_at": "2013-09-30T13:46:02Z"
},
"name": "Diaspora Project Site",
"name_with_namespace": "Diaspora / Diaspora Project Site",
"path": "diaspora-project-site",
"path_with_namespace": "diaspora/diaspora-project-site",
"issues_enabled": true,
"open_issues_count": 1,
"merge_requests_enabled": true,
"jobs_enabled": true,
"wiki_enabled": true,
"snippets_enabled": false,
"can_create_merge_request_in": true,
"resolve_outdated_diff_discussions": false,
"container_registry_enabled": false, // deprecated, use container_registry_access_level instead
"container_registry_access_level": "disabled",
"security_and_compliance_access_level": "disabled",
"container_expiration_policy": {
"cadence": "7d",
"enabled": false,
"keep_n": null,
"older_than": null,
"name_regex": null, // to be deprecated in GitLab 13.0 in favor of `name_regex_delete`
"name_regex_delete": null,
"name_regex_keep": null,
"next_run_at": "2020-01-07T21:42:58.658Z"
},
"created_at": "2013-09-30T13:46:02Z",
"updated_at": "2013-09-30T13:46:02Z",
"last_activity_at": "2013-09-30T13:46:02Z",
"creator_id": 3,
"namespace": {
"id": 3,
"name": "Diaspora",
"path": "diaspora",
"kind": "group",
"full_path": "diaspora",
"avatar_url": "http://localhost:3000/uploads/group/avatar/3/foo.jpg",
"web_url": "http://localhost:3000/groups/diaspora"
},
"import_url": null,
"import_type": null,
"import_status": "none",
"import_error": null,
"permissions": {
"project_access": {
"access_level": 10,
"notification_level": 3
},
"group_access": {
"access_level": 50,
"notification_level": 3
}
},
"archived": false,
"avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png",
"license_url": "http://example.com/diaspora/diaspora-client/blob/main/LICENSE",
"license": {
"key": "lgpl-3.0",
"name": "GNU Lesser General Public License v3.0",
"nickname": "GNU LGPLv3",
"html_url": "http://choosealicense.com/licenses/lgpl-3.0/",
"source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt"
},
"shared_runners_enabled": true,
"group_runners_enabled": true,
"forks_count": 0,
"star_count": 0,
"runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b",
"ci_default_git_depth": 50,
"ci_forward_deployment_enabled": true,
"ci_forward_deployment_rollback_allowed": true,
"ci_allow_fork_pipelines_to_run_in_parent_project": true,
"ci_id_token_sub_claim_components": ["project_path", "ref_type", "ref"],
"ci_separated_caches": true,
"ci_restrict_pipeline_cancellation_role": "developer",
"ci_pipeline_variables_minimum_override_role": "maintainer",
"ci_push_repository_for_job_token_allowed": false,
"public_jobs": true,
"shared_with_groups": [
{
"group_id": 4,
"group_name": "Twitter",
"group_full_path": "twitter",
"group_access_level": 30
},
{
"group_id": 3,
"group_name": "Gitlab Org",
"group_full_path": "gitlab-org",
"group_access_level": 10
}
],
"repository_storage": "default",
"only_allow_merge_if_pipeline_succeeds": false,
"allow_merge_on_skipped_pipeline": false,
"allow_pipeline_trigger_approve_deployment": false,
"restrict_user_defined_variables": false,
"only_allow_merge_if_all_discussions_are_resolved": false,
"remove_source_branch_after_merge": false,
"printing_merge_requests_link_enabled": true,
"request_access_enabled": false,
"merge_method": "merge",
"squash_option": "default_on",
"auto_devops_enabled": true,
"auto_devops_deploy_strategy": "continuous",
"approvals_before_merge": 0, // Deprecated. Use merge request approvals API instead.
"mirror": false,
"mirror_user_id": 45,
"mirror_trigger_builds": false,
"only_mirror_protected_branches": false,
"mirror_overwrites_diverged_branches": false,
"external_authorization_classification_label": null,
"packages_enabled": true,
"service_desk_enabled": false,
"service_desk_address": null,
"autoclose_referenced_issues": true,
"suggestion_commit_message": null,
"enforce_auth_checks_on_uploads": true,
"merge_commit_template": null,
"squash_commit_template": null,
"issue_branch_template": "gitlab/%{id}-%{title}",
"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.
"marked_for_deletion_on": "2020-04-03",
"compliance_frameworks": [ "sox" ],
"warn_about_potentially_unwanted_characters": true,
"secret_push_protection_enabled": false,
"statistics": {
"commit_count": 37,
"storage_size": 1038090,
"repository_size": 1038090,
"wiki_size" : 0,
"lfs_objects_size": 0,
"job_artifacts_size": 0,
"pipeline_artifacts_size": 0,
"packages_size": 0,
"snippets_size": 0,
"uploads_size": 0,
"container_registry_size": 0
},
"container_registry_image_prefix": "registry.example.com/diaspora/diaspora-client",
"_links": {
"self": "http://example.com/api/v4/projects",
"issues": "http://example.com/api/v4/projects/1/issues",
"merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
"repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
"labels": "http://example.com/api/v4/projects/1/labels",
"events": "http://example.com/api/v4/projects/1/events",
"members": "http://example.com/api/v4/projects/1/members",
"cluster_agents": "http://example.com/api/v4/projects/1/cluster_agents"
}
}
在极狐GitLab 旗舰版的用户可以使用极狐GitLab 15.5 及更高版本查看 only_allow_merge_if_all_status_checks_passed
参数:
{
"id": 1,
"project_id": 3,
"only_allow_merge_if_all_status_checks_passed": false,
...
}
如果项目是分叉项目,则响应中会出现 forked_from_project
字段。对于此字段,如果上游项目是私有的,则必须提供有效的身份验证令牌。字段 mr_default_target_self
也会出现。如果此值为 false
,则所有合并请求默认目标为上游项目。
{
"id":3,
...
"mr_default_target_self": false,
"forked_from_project":{
"id":13083,
"description":"GitLab Community Edition",
"name":"GitLab Community Edition",
"name_with_namespace":"GitLab.org / GitLab Community Edition",
"path":"gitlab-foss",
"path_with_namespace":"gitlab-org/gitlab-foss",
"created_at":"2013-09-26T06:02:36.000Z",
"default_branch":"main",
"tag_list":[], //deprecated, use `topics` instead
"topics":[],
"ssh_url_to_repo":"git@gitlab.com:gitlab-org/gitlab-foss.git",
"http_url_to_repo":"https://gitlab.com/gitlab-org/gitlab-foss.git",
"web_url":"https://gitlab.com/gitlab-org/gitlab-foss",
"avatar_url":"https://gitlab.com/uploads/-/system/project/avatar/13083/logo-extra-whitespace.png",
"license_url": "https://gitlab.com/gitlab-org/gitlab/-/blob/main/LICENSE",
"license": {
"key": "mit",
"name": "MIT License",
"nickname": null,
"html_url": "http://choosealicense.com/licenses/mit/",
"source_url": "https://opensource.org/licenses/MIT"
},
"star_count":3812,
"forks_count":3561,
"last_activity_at":"2018-01-02T11:40:26.570Z",
"namespace": {
"id": 72,
"name": "GitLab.org",
"path": "gitlab-org",
"kind": "group",
"full_path": "gitlab-org",
"parent_id": null
},
"repository_storage": "default"
}
...
}
议题和合并请求的模板
{{< details >}}
- Tier: 专业版,旗舰版
- Offering: JihuLab.com,极狐GitLab 私有化部署,极狐GitLab 专属
{{< /details >}}
使用极狐GitLab 专业版或旗舰版的用户还可以查看 issues_template
和 merge_requests_template
参数以管理议题和合并请求描述模板。
{
"id": 3,
"issues_template": null,
"merge_requests_template": null,
...
}
列出项目
列出项目。
列出所有项目
{{< history >}}
- 响应中的
_links.cluster_agents
属性在极狐GitLab 15.0 中引入。
{{< /history >}}
获取经过身份验证的用户在极狐GitLab 中所有可见项目的列表。在不进行身份验证的情况下访问时,仅返回具有 simple 字段的公共项目。
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
或用户未进行身份验证时,返回如下内容:
示例请求:
curl --request GET "https://gitlab.example.com/api/v4/projects"
示例响应:
[
{
"id": 4,
"description": null,
"name": "Diaspora Client",
"name_with_namespace": "Diaspora / Diaspora Client",
"path": "diaspora-client",
"path_with_namespace": "diaspora/diaspora-client",
"created_at": "2013-09-30T13:46:02Z",
"default_branch": "main",
"tag_list": [
"example",
"disapora client"
],
"topics": [
"example",
"disapora client"
],
"ssh_url_to_repo": "git@gitlab.example.com:diaspora/diaspora-client.git",
"http_url_to_repo": "https://gitlab.example.com/diaspora/diaspora-client.git",
"web_url": "https://gitlab.example.com/diaspora/diaspora-client",
"avatar_url": "https://gitlab.example.com/uploads/project/avatar/4/uploads/avatar.png",
"star_count": 0,
"last_activity_at": "2013-09-30T13:46:02Z",
"namespace": {
"id": 2,
"name": "Diaspora",
"path": "diaspora",
"kind": "group",
"full_path": "diaspora",
"parent_id": null,
"avatar_url": null,
"web_url": "https://gitlab.example.com/diaspora"
}
},
{
...
}
当用户进行身份验证且未设置 simple
时,此端点返回如下内容:
[
{
"id": 4,
"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
"description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
"name": "Diaspora Client",
"name_with_namespace": "Diaspora / Diaspora Client",
"path": "diaspora-client",
"path_with_namespace": "diaspora/diaspora-client",
"created_at": "2013-09-30T13:46:02Z",
"updated_at": "2013-09-30T13:46:02Z",
"default_branch": "main",
"tag_list": [ //deprecated, use `topics` instead
"example",
"disapora client"
],
"topics": [
"example",
"disapora client"
],
"ssh_url_to_repo": "git@gitlab.example.com:diaspora/diaspora-client.git",
"http_url_to_repo": "https://gitlab.example.com/diaspora/diaspora-client.git",
"web_url": "https://gitlab.example.com/diaspora/diaspora-client",
"readme_url": "https://gitlab.example.com/diaspora/diaspora-client/blob/main/README.md",
"avatar_url": "https://gitlab.example.com/uploads/project/avatar/4/uploads/avatar.png",
"forks_count": 0,
"star_count": 0,
"last_activity_at": "2022-06-24T17:11:26.841Z",
"namespace": {
"id": 3,
"name": "Diaspora",
"path": "diaspora",
"kind": "group",
"full_path": "diaspora",
"parent_id": null,
"avatar_url": "https://gitlab.example.com/uploads/project/avatar/6/uploads/avatar.png",
"web_url": "https://gitlab.example.com/diaspora"
},
"container_registry_image_prefix": "registry.gitlab.example.com/diaspora/diaspora-client",
"_links": {
"self": "https://gitlab.example.com/api/v4/projects/4",
"issues": "https://gitlab.example.com/api/v4/projects/4/issues",
"merge_requests": "https://gitlab.example.com/api/v4/projects/4/merge_requests",
"repo_branches": "https://gitlab.example.com/api/v4/projects/4/repository/branches",
"labels": "https://gitlab.example.com/api/v4/projects/4/labels",
"events": "https://gitlab.example.com/api/v4/projects/4/events",
"members": "https://gitlab.example.com/api/v4/projects/4/members",
"cluster_agents": "https://gitlab.example.com/api/v4/projects/4/cluster_agents"
},
"packages_enabled": true,
"empty_repo": false,
"archived": false,
"visibility": "public",
"resolve_outdated_diff_discussions": false,
"container_expiration_policy": {
"cadence": "1month",
"enabled": true,
"keep_n": 1,
"older_than": "14d",
"name_regex": "",
"name_regex_keep": ".*-main",
"next_run_at": "2022-06-25T17:11:26.865Z"
},
"issues_enabled": true,
"merge_requests_enabled": true,
"wiki_enabled": true,
"jobs_enabled": true,
"snippets_enabled": true,
"container_registry_enabled": true,
"service_desk_enabled": true,
"can_create_merge_request_in": true,
"issues_access_level": "enabled",
"repository_access_level": "enabled",
"merge_requests_access_level": "enabled",
"forking_access_level": "enabled",
"wiki_access_level": "enabled",
"builds_access_level": "enabled",
"snippets_access_level": "enabled",
"pages_access_level": "enabled",
"analytics_access_level": "enabled",
"container_registry_access_level": "enabled",
"security_and_compliance_access_level": "private",
"emails_disabled": null,
"emails_enabled": null,
"shared_runners_enabled": true,
"group_runners_enabled": true,
"lfs_enabled": true,
"creator_id": 1,
"import_url": null,
"import_type": null,
"import_status": "none",
"import_error": null,
"open_issues_count": 0,
"ci_default_git_depth": 20,
"ci_forward_deployment_enabled": true,
"ci_forward_deployment_rollback_allowed": true,
"ci_allow_fork_pipelines_to_run_in_parent_project": true,
"ci_id_token_sub_claim_components": ["project_path", "ref_type", "ref"],
"ci_job_token_scope_enabled": false,
"ci_separated_caches": true,
"ci_restrict_pipeline_cancellation_role": "developer",
"ci_pipeline_variables_minimum_override_role": "maintainer",
"ci_push_repository_for_job_token_allowed": false,
"public_jobs": true,
"build_timeout": 3600,
"auto_cancel_pending_pipelines": "enabled",
"ci_config_path": "",
"shared_with_groups": [],
"only_allow_merge_if_pipeline_succeeds": false,
"allow_merge_on_skipped_pipeline": null,
"allow_pipeline_trigger_approve_deployment": false,
"restrict_user_defined_variables": false,
"request_access_enabled": true,
"only_allow_merge_if_all_discussions_are_resolved": false,
"remove_source_branch_after_merge": true,
"printing_merge_request_link_enabled": true,
"merge_method": "merge",
"squash_option": "default_off",
"enforce_auth_checks_on_uploads": true,
"suggestion_commit_message": null,
"merge_commit_template": null,
"squash_commit_template": null,
"issue_branch_template": "gitlab/%{id}-%{title}",
"auto_devops_enabled": false,
"auto_devops_deploy_strategy": "continuous",
"autoclose_referenced_issues": true,
"keep_latest_artifact": true,
"runner_token_expiration_interval": null,
"external_authorization_classification_label": "",
"requirements_enabled": false,
"requirements_access_level": "enabled",
"security_and_compliance_enabled": false,
"secret_push_protection_enabled": false,
"compliance_frameworks": [],
"warn_about_potentially_unwanted_characters": true,
"permissions": {
"project_access": null,
"group_access": null
}
},
{
...
}
]
{{< alert type=”note” >}}
last_activity_at
是根据项目活动和项目事件更新的。updated_at
是每当项目记录在数据库中更改时更新的。
{{< /alert >}}
您可以通过自定义属性进行过滤:
GET /projects?custom_attributes[key]=value&custom_attributes[other_key]=other_value
示例请求:
curl --globoff --request GET "https://gitlab.example.com/api/v4/projects?custom_attributes[location]=Antarctica&custom_attributes[role]=Developer"
分页限制
您可以使用基于偏移量的分页访问最多 50,000 个项目。
使用键集分页检索超过此限制的项目。键集分页仅支持 order_by=id
。其他排序选项不可用。
列出用户的项目
获取给定用户拥有的可见项目的列表。在不进行身份验证的情况下访问时,仅返回公共项目。
先决条件:
- 要查看某些属性,您必须是管理员或具有项目的所有者角色。
{{< alert type=”note” >}}
仅返回用户(在 user_id
中指定)的命名空间中的项目。用户在任何群组或子群组中拥有的项目不会返回。如果配置文件设置为私有,则返回空列表。
{{< /alert >}}
此端点支持所选 order_by
选项的键集分页。
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
[
{
"id": 4,
"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
"description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
"default_branch": "main",
"visibility": "private",
"ssh_url_to_repo": "git@example.com:diaspora/diaspora-client.git",
"http_url_to_repo": "http://example.com/diaspora/diaspora-client.git",
"web_url": "http://example.com/diaspora/diaspora-client",
"readme_url": "http://example.com/diaspora/diaspora-client/blob/main/README.md",
"tag_list": [ //deprecated, use `topics` instead
"example",
"disapora client"
],
"topics": [
"example",
"disapora client"
],
"owner": {
"id": 3,
"name": "Diaspora",
"created_at": "2013-09-30T13:46:02Z"
},
"name": "Diaspora Client",
"name_with_namespace": "Diaspora / Diaspora Client",
"path": "diaspora-client",
"path_with_namespace": "diaspora/diaspora-client",
"issues_enabled": true,
"open_issues_count": 1,
"merge_requests_enabled": true,
"jobs_enabled": true,
"wiki_enabled": true,
"snippets_enabled": false,
"can_create_merge_request_in": true,
"resolve_outdated_diff_discussions": false,
"container_registry_enabled": false, // deprecated, use container_registry_access_level instead
"container_registry_access_level": "disabled",
"security_and_compliance_access_level": "disabled",
"created_at": "2013-09-30T13:46:02Z",
"updated_at": "2013-09-30T13:46:02Z",
"last_activity_at": "2013-09-30T13:46:02Z",
"creator_id": 3,
"import_url": null,
"import_type": null,
"import_status": "none",
"import_error": null,
"namespace": {
"id": 3,
"name": "Diaspora",
"path": "diaspora",
"kind": "group",
"full_path": "diaspora"
},
"import_status": "none",
"archived": false,
"avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png",
"shared_runners_enabled": true,
"group_runners_enabled": true,
"forks_count": 0,
"star_count": 0,
"runners_token": "b8547b1dc37721d05889db52fa2f02",
"ci_default_git_depth": 50,
"ci_forward_deployment_enabled": true,
"ci_forward_deployment_rollback_allowed": true,
"ci_allow_fork_pipelines_to_run_in_parent_project": true,
"ci_id_token_sub_claim_components": ["project_path", "ref_type", "ref"],
"ci_separated_caches": true,
"ci_restrict_pipeline_cancellation_role": "developer",
"ci_pipeline_variables_minimum_override_role": "maintainer",
"ci_push_repository_for_job_token_allowed": false,
"public_jobs": true,
"shared_with_groups": [],
"only_allow_merge_if_pipeline_succeeds": false,
"allow_merge_on_skipped_pipeline": false,
"allow_pipeline_trigger_approve_deployment": false,
"restrict_user_defined_variables": false,
"only_allow_merge_if_all_discussions_are_resolved": false,
"remove_source_branch_after_merge": false,
"request_access_enabled": false,
"merge_method": "merge",
"squash_option": "default_on",
"autoclose_referenced_issues": true,
"enforce_auth_checks_on_uploads": true,
"suggestion_commit_message": null,
"merge_commit_template": null,
"squash_commit_template": null,
"secret_push_protection_enabled": false,
"issue_branch_template": "gitlab/%{id}-%{title}",
"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.
"marked_for_deletion_on": "2020-04-03",
"statistics": {
"commit_count": 37,
"storage_size": 1038090,
"repository_size": 1038090,
"wiki_size" : 0,
"lfs_objects_size": 0,
"job_artifacts_size": 0,
"pipeline_artifacts_size": 0,
"packages_size": 0,
"snippets_size": 0,
"uploads_size": 0,
"container_registry_size": 0
},
"container_registry_image_prefix": "registry.example.com/diaspora/diaspora-client",
"_links": {
"self": "http://example.com/api/v4/projects",
"issues": "http://example.com/api/v4/projects/1/issues",
"merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
"repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
"labels": "http://example.com/api/v4/projects/1/labels",
"events": "http://example.com/api/v4/projects/1/events",
"members": "http://example.com/api/v4/projects/1/members",
"cluster_agents": "http://example.com/api/v4/projects/1/cluster_agents"
}
},
{
"id": 6,
"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
"description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
"default_branch": "main",
"visibility": "private",
"ssh_url_to_repo": "git@example.com:brightbox/puppet.git",
"http_url_to_repo": "http://example.com/brightbox/puppet.git",
"web_url": "http://example.com/brightbox/puppet",
"readme_url": "http://example.com/brightbox/puppet/blob/main/README.md",
"tag_list": [ //deprecated, use `topics` instead
"example",
"puppet"
],
"topics": [
"example",
"puppet"
],
"owner": {
"id": 4,
"name": "Brightbox",
"created_at": "2013-09-30T13:46:02Z"
},
"name": "Puppet",
"name_with_namespace": "Brightbox / Puppet",
"path": "puppet",
"path_with_namespace": "brightbox/puppet",
"issues_enabled": true,
"open_issues_count": 1,
"merge_requests_enabled": true,
"jobs_enabled": true,
"wiki_enabled": true,
"snippets_enabled": false,
"can_create_merge_request_in": true,
"resolve_outdated_diff_discussions": false,
"container_registry_enabled": false, // deprecated, use container_registry_access_level instead
"container_registry_access_level": "disabled",
"security_and_compliance_access_level": "disabled",
"created_at": "2013-09-30T13:46:02Z",
"updated_at": "2013-09-30T13:46:02Z",
"last_activity_at": "2013-09-30T13:46:02Z",
"creator_id": 3,
"import_url": null,
"import_type": null,
"import_status": "none",
"import_error": null,
"namespace": {
"id": 4,
"name": "Brightbox",
"path": "brightbox",
"kind": "group",
"full_path": "brightbox"
},
"import_status": "none",
"import_error": null,
"permissions": {
"project_access": {
"access_level": 10,
"notification_level": 3
},
"group_access": {
"access_level": 50,
"notification_level": 3
}
},
"archived": false,
"avatar_url": null,
"shared_runners_enabled": true,
"group_runners_enabled": true,
"forks_count": 0,
"star_count": 0,
"runners_token": "b8547b1dc37721d05889db52fa2f02",
"ci_default_git_depth": 0,
"ci_forward_deployment_enabled": true,
"ci_forward_deployment_rollback_allowed": true,
"ci_allow_fork_pipelines_to_run_in_parent_project": true,
"ci_id_token_sub_claim_components": ["project_path", "ref_type", "ref"],
"ci_separated_caches": true,
"ci_restrict_pipeline_cancellation_role": "developer",
"ci_pipeline_variables_minimum_override_role": "maintainer",
"ci_push_repository_for_job_token_allowed": false,
"public_jobs": true,
"shared_with_groups": [],
"only_allow_merge_if_pipeline_succeeds": false,
"allow_merge_on_skipped_pipeline": false,
"allow_pipeline_trigger_approve_deployment": false,
"restrict_user_defined_variables": false,
"only_allow_merge_if_all_discussions_are_resolved": false,
"remove_source_branch_after_merge": false,
"request_access_enabled": false,
"merge_method": "merge",
"squash_option": "default_on",
"auto_devops_enabled": true,
"auto_devops_deploy_strategy": "continuous",
"repository_storage": "default",
"approvals_before_merge": 0, // Deprecated. Use merge request approvals API instead.
"mirror": false,
"mirror_user_id": 45,
"mirror_trigger_builds": false,
"only_mirror_protected_branches": false,
"mirror_overwrites_diverged_branches": false,
"external_authorization_classification_label": null,
"packages_enabled": true,
"service_desk_enabled": false,
"service_desk_address": null,
"autoclose_referenced_issues": true,
"enforce_auth_checks_on_uploads": true,
"suggestion_commit_message": null,
"merge_commit_template": null,
"squash_commit_template": null,
"secret_push_protection_enabled": false,
"issue_branch_template": "gitlab/%{id}-%{title}",
"statistics": {
"commit_count": 12,
"storage_size": 2066080,
"repository_size": 2066080,
"wiki_size" : 0,
"lfs_objects_size": 0,
"job_artifacts_size": 0,
"pipeline_artifacts_size": 0,
"packages_size": 0,
"snippets_size": 0,
"uploads_size": 0,
"container_registry_size": 0
},
"container_registry_image_prefix": "registry.example.com/brightbox/puppet",
"_links": {
"self": "http://example.com/api/v4/projects",
"issues": "http://example.com/api/v4/projects/1/issues",
"merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
"repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
"labels": "http://example.com/api/v4/projects/1/labels",
"events": "http://example.com/api/v4/projects/1/events",
"members": "http://example.com/api/v4/projects/1/members",
"cluster_agents": "http://example.com/api/v4/projects/1/cluster_agents"
}
}
]
列出用户贡献过的项目
返回给定用户在过去一年内贡献过的可见项目列表。有关什么算作贡献的更多信息,请参见查看您贡献过的项目。
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 。 |
示例请求:
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/5/contributed_projects"
示例响应:
[
{
"id": 4,
"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
"description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
"default_branch": "main",
"visibility": "private",
"ssh_url_to_repo": "git@example.com:diaspora/diaspora-client.git",
"http_url_to_repo": "http://example.com/diaspora/diaspora-client.git",
"web_url": "http://example.com/diaspora/diaspora-client",
"readme_url": "http://example.com/diaspora/diaspora-client/blob/main/README.md",
"tag_list": [ //deprecated, use `topics` instead
"example",
"disapora client"
],
"topics": [
"example",
"disapora client"
],
"owner": {
"id": 3,
"name": "Diaspora",
"created_at": "2013-09-30T13:46:02Z"
},
"name": "Diaspora Client",
"name_with_namespace": "Diaspora / Diaspora Client",
"path": "diaspora-client",
"path_with_namespace": "diaspora/diaspora-client",
"issues_enabled": true,
"open_issues_count": 1,
"merge_requests_enabled": true,
"jobs_enabled": true,
"wiki_enabled": true,
"snippets_enabled": false,
"can_create_merge_request_in": true,
"resolve_outdated_diff_discussions": false,
"container_registry_enabled": false, // deprecated, use container_registry_access_level instead
"container_registry_access_level": "disabled",
"security_and_compliance_access_level": "disabled",
"created_at": "2013-09-30T13:46:02Z",
"updated_at": "2013-09-30T13:46:02Z",
"last_activity_at": "2013-09-30T13:46:02Z",
"creator_id": 3,
"namespace": {
"id": 3,
"name": "Diaspora",
"path": "diaspora",
"kind": "group",
"full_path": "diaspora"
},
"import_status": "none",
"archived": false,
"avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png",
"shared_runners_enabled": true,
"group_runners_enabled": true,
"forks_count": 0,
"star_count": 0,
"runners_token": "b8547b1dc37721d05889db52fa2f02",
"public_jobs": true,
"shared_with_groups": [],
"only_allow_merge_if_pipeline_succeeds": false,
"allow_merge_on_skipped_pipeline": false,
"allow_pipeline_trigger_approve_deployment": false,
"restrict_user_defined_variables": false,
"only_allow_merge_if_all_discussions_are_resolved": false,
"remove_source_branch_after_merge": false,
"request_access_enabled": false,
"merge_method": "merge",
"squash_option": "default_on",
"autoclose_referenced_issues": true,
"enforce_auth_checks_on_uploads": true,
"suggestion_commit_message": null,
"merge_commit_template": null,
"squash_commit_template": null,
"secret_push_protection_enabled": false,
"issue_branch_template": "gitlab/%{id}-%{title}",
"statistics": {
"commit_count": 37,
"storage_size": 1038090,
"repository_size": 1038090,
"lfs_objects_size": 0,
"job_artifacts_size": 0,
"pipeline_artifacts_size": 0,
"packages_size": 0,
"snippets_size": 0,
"uploads_size": 0,
"container_registry_size": 0
},
"container_registry_image_prefix": "registry.example.com/diaspora/diaspora-client",
"_links": {
"self": "http://example.com/api/v4/projects",
"issues": "http://example.com/api/v4/projects/1/issues",
"merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
"repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
"labels": "http://example.com/api/v4/projects/1/labels",
"events": "http://example.com/api/v4/projects/1/events",
"members": "http://example.com/api/v4/projects/1/members",
"cluster_agents": "http://example.com/api/v4/projects/1/cluster_agents"
}
},
{
"id": 6,
"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
"description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
"default_branch": "main",
"visibility": "private",
"ssh_url_to_repo": "git@example.com:brightbox/puppet.git",
"http_url_to_repo": "http://example.com/brightbox/puppet.git",
"web_url": "http://example.com/brightbox/puppet",
"readme_url": "http://example.com/brightbox/puppet/blob/main/README.md",
"tag_list": [ //deprecated, use `topics` instead
"example",
"puppet"
],
"topics": [
"example",
"puppet"
],
"owner": {
"id": 4,
"name": "Brightbox",
"created_at": "2013-09-30T13:46:02Z"
},
"name": "Puppet",
"name_with_namespace": "Brightbox / Puppet",
"path": "puppet",
"path_with_namespace": "brightbox/puppet",
"issues_enabled": true,
"open_issues_count": 1,
"merge_requests_enabled": true,
"jobs_enabled": true,
"wiki_enabled": true,
"snippets_enabled": false,
"can_create_merge_request_in": true,
"resolve_outdated_diff_discussions": false,
"container_registry_enabled": false, // deprecated, use container_registry_access_level instead
"container_registry_access_level": "disabled",
"security_and_compliance_access_level": "disabled",
"created_at": "2013-09-30T13:46:02Z",
"updated_at": "2013-09-30T13:46:02Z",
"last_activity_at": "2013-09-30T13:46:02Z",
"creator_id": 3,
"namespace": {
"id": 4,
"name": "Brightbox",
"path": "brightbox",
"kind": "group",
"full_path": "brightbox"
},
"import_status": "none",
"import_error": null,
"permissions": {
"project_access": {
"access_level": 10,
"notification_level": 3
},
"group_access": {
"access_level": 50,
"notification_level": 3
}
},
"archived": false,
"avatar_url": null,
"shared_runners_enabled": true,
"group_runners_enabled": true,
"forks_count": 0,
"star_count": 0,
"runners_token": "b8547b1dc37721d05889db52fa2f02",
"public_jobs": true,
"shared_with_groups": [],
"only_allow_merge_if_pipeline_succeeds": false,
"allow_merge_on_skipped_pipeline": false,
"allow_pipeline_trigger_approve_deployment": false,
"restrict_user_defined_variables": false,
"only_allow_merge_if_all_discussions_are_resolved": false,
"remove_source_branch_after_merge": false,
"request_access_enabled": false,
"merge_method": "merge",
"squash_option": "default_on",
"auto_devops_enabled": true,
"auto_devops_deploy_strategy": "continuous",
"repository_storage": "default",
"approvals_before_merge": 0, // Deprecated. Use merge request approvals API instead.
"mirror": false,
"mirror_user_id": 45,
"mirror_trigger_builds": false,
"only_mirror_protected_branches": false,
"mirror_overwrites_diverged_branches": false,
"external_authorization_classification_label": null,
"packages_enabled": true,
"service_desk_enabled": false,
"service_desk_address": null,
"autoclose_referenced_issues": true,
"enforce_auth_checks_on_uploads": true,
"suggestion_commit_message": null,
"merge_commit_template": null,
"squash_commit_template": null,
"secret_push_protection_enabled": false,
"issue_branch_template": "gitlab/%{id}-%{title}",
"statistics": {
"commit_count": 12,
"storage_size": 2066080,
"repository_size": 2066080,
"lfs_objects_size": 0,
"job_artifacts_size": 0,
"pipeline_artifacts_size": 0,
"packages_size": 0,
"snippets_size": 0,
"uploads_size": 0,
"container_registry_size": 0
},
"container_registry_image_prefix": "registry.example.com/brightbox/puppet",
"_links": {
"self": "http://example.com/api/v4/projects",
"issues": "http://example.com/api/v4/projects/1/issues",
"merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
"repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
"labels": "http://example.com/api/v4/projects/1/labels",
"events": "http://example.com/api/v4/projects/1/events",
"members": "http://example.com/api/v4/projects/1/members",
"cluster_agents": "http://example.com/api/v4/projects/1/cluster_agents"
}
}
]
按名称搜索项目
按名称搜索对已认证用户可访问的项目。如果在没有身份验证的情况下访问此端点,它会列出公开可访问的项目。
GET /projects
示例属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
search |
string | 是 | 项目名称中包含的字符串。 |
order_by |
string | 否 | 按 id 、name 、created_at 、star_count 或 last_activity_at 字段排序返回请求。 |
sort |
string | 否 | 按 asc 或 desc 顺序返回排序后的请求。 |
示例请求:
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects?search=test"
列出属性
列出项目的属性。
列出用户
获取项目的用户列表。
GET /projects/:id/users
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码的路径。 |
search |
string | 否 | 搜索特定用户。 |
skip_users |
integer array | 否 | 过滤掉具有指定 ID 的用户。 |
示例响应:
[
{
"id": 1,
"username": "john_smith",
"name": "John Smith",
"state": "active",
"avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
"web_url": "http://localhost:3000/john_smith"
},
{
"id": 2,
"username": "jack_smith",
"name": "Jack Smith",
"state": "blocked",
"avatar_url": "http://gravatar.com/../e32131cd8.jpeg",
"web_url": "http://localhost:3000/jack_smith"
}
]
列出群组
获取此项目的祖先群组列表。
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 。 |
示例响应:
[
{
"id": 1,
"name": "Foobar Group",
"avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg",
"web_url": "http://localhost:3000/groups/foo-bar",
"full_name": "Foobar Group",
"full_path": "foo-bar"
},
{
"id": 2,
"name": "Shared Group",
"avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/bar.jpg",
"web_url": "http://gitlab.example.com/groups/foo/bar",
"full_name": "Shared Group",
"full_path": "foo/shared"
}
]
列出可共享的群组
获取可以与项目共享的群组列表
GET /projects/:id/share_locations
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码的路径。 |
search |
string | 否 | 搜索特定群组。 |
示例响应:
[
{
"id": 22,
"web_url": "http://127.0.0.1:3000/groups/gitlab-org",
"name": "Gitlab Org",
"avatar_url": null,
"full_name": "Gitlab Org",
"full_path": "gitlab-org"
},
{
"id": 25,
"web_url": "http://127.0.0.1:3000/groups/gnuwget",
"name": "Gnuwget",
"avatar_url": null,
"full_name": "Gnuwget",
"full_path": "gnuwget"
}
]
列出项目的邀请群组
获取项目中的邀请群组列表。在没有身份验证的情况下访问时,仅返回公共邀请群组。此端点的速率限制为每分钟 60 次请求,按以下方式限制:
- 对于已认证用户的用户。
- 对于未认证用户的 IP 地址。
默认情况下,此请求一次返回 20 个结果,因为 API 结果是分页的。
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 | 否 | 在响应中包括自定义属性(仅限管理员) |
示例响应:
[
{
"id": 35,
"web_url": "https://gitlab.example.com/groups/twitter",
"name": "Twitter",
"avatar_url": null,
"full_name": "Twitter",
"full_path": "twitter"
}
]
列出使用的编程语言
获取项目中使用的编程语言列表及使用百分比。
GET /projects/:id/languages
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码的路径。 |
示例请求:
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/languages"
示例响应:
{
"Ruby": 66.69,
"JavaScript": 22.98,
"HTML": 7.91,
"CoffeeScript": 2.42
}
管理项目
管理项目,包括创建、删除和存档。
创建项目
{{< history >}}
- 在极狐 GitLab 16.0 中,
operations_access_level
已移除。 - 在极狐 GitLab 16.7 中,
model_registry_access_level
已引入。
{{< /history >}}
创建一个由已认证用户拥有的新项目。
如果您的 HTTP 仓库不是公开可访问的,请在 URL 中添加身份验证信息 https://username:password@gitlab.company.com/group/project.git
,其中 password
是一个启用了 api
范围的公共访问密钥。
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的可见性。 |
示例请求:
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
已引入。
{{< /history >}}
为用户创建项目。
先决条件:
- 您必须是管理员。
如果您的 HTTP 仓库不是公开可访问的,请在 URL 中添加身份验证信息。例如,https://username:password@gitlab.company.com/group/project.git
,其中 password
是一个启用了 api
范围的公共访问密钥。
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 中引入。
{{< /history >}}
更新现有项目。
如果您的 HTTP 仓库不是公开可访问的,请在 URL 中添加身份验证信息
https://username:password@gitlab.company.com/group/project.git
,
其中 password
是启用了 api
范围的公共访问密钥。
导入成员
从另一个项目导入成员。
如果导入成员在目标项目中的角色是:
- 维护者,那么源项目中具有所有者角色的成员将被导入为维护者角色。
- 所有者,那么源项目中具有所有者角色的成员将被导入为所有者角色。
POST /projects/:id/import_project_members/:project_id
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 目标项目接收成员的 ID 或 URL 编码路径。 |
project_id |
integer or string | 是 | 导入成员的源项目的 ID 或 URL 编码路径。 |
请求示例:
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 状态码):{ "status": "success" }
-
当导入一个或多个成员时出现任何错误 (
200
HTTP 状态码):{ "status": "error", "message": { "john_smith": "Some individual error message", "jane_smith": "Some individual error message" }, "total_members_count": 3 }
-
当出现系统错误时 (
404
和422
HTTP 状态码):
{ "message": "Import failed" }
归档项目
归档一个项目。
先决条件:
- 你必须是管理员或被分配为项目的所有者角色。
此端点是幂等的。归档已归档的项目不会改变项目。
POST /projects/:id/archive
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径。 |
请求示例:
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/archive"
响应示例:
{
"id": 3,
"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
"description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
"default_branch": "main",
"visibility": "private",
"ssh_url_to_repo": "git@example.com:diaspora/diaspora-project-site.git",
"http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
"web_url": "http://example.com/diaspora/diaspora-project-site",
"readme_url": "http://example.com/diaspora/diaspora-project-site/blob/main/README.md",
"tag_list": [ //已弃用, 使用 `topics` 替代
"example",
"disapora project"
],
"topics": [
"example",
"disapora project"
],
"owner": {
"id": 3,
"name": "Diaspora",
"created_at": "2013-09-30T13:46:02Z"
},
"name": "Diaspora Project Site",
"name_with_namespace": "Diaspora / Diaspora Project Site",
"path": "diaspora-project-site",
"path_with_namespace": "diaspora/diaspora-project-site",
"repository_object_format": "sha1",
"issues_enabled": true,
"open_issues_count": 1,
"merge_requests_enabled": true,
"jobs_enabled": true,
"wiki_enabled": true,
"snippets_enabled": false,
"can_create_merge_request_in": true,
"resolve_outdated_diff_discussions": false,
"container_registry_enabled": false, // 已弃用, 使用 container_registry_access_level 代替
"container_registry_access_level": "disabled",
"security_and_compliance_access_level": "disabled",
"created_at": "2013-09-30T13:46:02Z",
"updated_at": "2013-09-30T13:46:02Z",
"last_activity_at": "2013-09-30T13:46:02Z",
"creator_id": 3,
"namespace": {
"id": 3,
"name": "Diaspora",
"path": "diaspora",
"kind": "group",
"full_path": "diaspora"
},
"import_status": "none",
"import_error": null,
"permissions": {
"project_access": {
"access_level": 10,
"notification_level": 3
},
"group_access": {
"access_level": 50,
"notification_level": 3
}
},
"archived": true,
"avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png",
"license_url": "http://example.com/diaspora/diaspora-client/blob/main/LICENSE",
"license": {
"key": "lgpl-3.0",
"name": "GNU Lesser General Public License v3.0",
"nickname": "GNU LGPLv3",
"html_url": "http://choosealicense.com/licenses/lgpl-3.0/",
"source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt"
},
"shared_runners_enabled": true,
"group_runners_enabled": true,
"forks_count": 0,
"star_count": 0,
"runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b",
"ci_default_git_depth": 50,
"ci_forward_deployment_enabled": true,
"ci_forward_deployment_rollback_allowed": true,
"ci_allow_fork_pipelines_to_run_in_parent_project": true,
"ci_id_token_sub_claim_components": ["project_path", "ref_type", "ref"],
"ci_separated_caches": true,
"ci_restrict_pipeline_cancellation_role": "developer",
"ci_pipeline_variables_minimum_override_role": "maintainer",
"ci_push_repository_for_job_token_allowed": false,
"public_jobs": true,
"shared_with_groups": [],
"only_allow_merge_if_pipeline_succeeds": false,
"allow_merge_on_skipped_pipeline": false,
"allow_pipeline_trigger_approve_deployment": false,
"restrict_user_defined_variables": false,
"only_allow_merge_if_all_discussions_are_resolved": false,
"remove_source_branch_after_merge": false,
"request_access_enabled": false,
"merge_method": "merge",
"squash_option": "default_on",
"autoclose_referenced_issues": true,
"enforce_auth_checks_on_uploads": true,
"suggestion_commit_message": null,
"merge_commit_template": null,
"secret_push_protection_enabled": false,
"container_registry_image_prefix": "registry.example.com/diaspora/diaspora-project-site",
"_links": {
"self": "http://example.com/api/v4/projects",
"issues": "http://example.com/api/v4/projects/1/issues",
"merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
"repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
"labels": "http://example.com/api/v4/projects/1/labels",
"events": "http://example.com/api/v4/projects/1/events",
"members": "http://example.com/api/v4/projects/1/members",
"cluster_agents": "http://example.com/api/v4/projects/1/cluster_agents"
}
}
取消归档项目
取消归档一个项目。
先决条件:
- 你必须是管理员或被分配为项目的所有者角色。
此端点是幂等的。取消归档未归档的项目不会改变项目。
POST /projects/:id/unarchive
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径。 |
请求示例:
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/unarchive"
响应示例:
{
"id": 3,
"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
"description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
"default_branch": "main",
"visibility": "private",
"ssh_url_to_repo": "git@example.com:diaspora/diaspora-project-site.git",
"http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
"web_url": "http://example.com/diaspora/diaspora-project-site",
"readme_url": "http://example.com/diaspora/diaspora-project-site/blob/main/README.md",
"tag_list": [ //已弃用, 使用 `topics` 替代
"example",
"disapora project"
],
"topics": [
"example",
"disapora project"
],
"owner": {
"id": 3,
"name": "Diaspora",
"created_at": "2013-09-30T13:46:02Z"
},
"name": "Diaspora Project Site",
"name_with_namespace": "Diaspora / Diaspora Project Site",
"path": "diaspora-project-site",
"path_with_namespace": "diaspora/diaspora-project-site",
"repository_object_format": "sha1",
"issues_enabled": true,
"open_issues_count": 1,
"merge_requests_enabled": true,
"jobs_enabled": true,
"wiki_enabled": true,
"snippets_enabled": false,
"can_create_merge_request_in": true,
"resolve_outdated_diff_discussions": false,
"container_registry_enabled": false, // 已弃用, 使用 container_registry_access_level 代替
"container_registry_access_level": "disabled",
"security_and_compliance_access_level": "disabled",
"created_at": "2013-09-30T13:46:02Z",
"updated_at": "2013-09-30T13:46:02Z",
"last_activity_at": "2013-09-30T13:46:02Z",
"creator_id": 3,
"namespace": {
"id": 3,
"name": "Diaspora",
"path": "diaspora",
"kind": "group",
"full_path": "diaspora"
},
"import_status": "none",
"import_error": null,
"permissions": {
"project_access": {
"access_level": 10,
"notification_level": 3
},
"group_access": {
"access_level": 50,
"notification_level": 3
}
},
"archived": false,
"avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png",
"license_url": "http://example.com/diaspora/diaspora-client/blob/main/LICENSE",
"license": {
"key": "lgpl-3.0",
"name": "GNU Lesser General Public License v3.0",
"nickname": "GNU LGPLv3",
"html_url": "http://choosealicense.com/licenses/lgpl-3.0/",
"source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt"
},
"shared_runners_enabled": true,
"group_runners_enabled": true,
"forks_count": 0,
"star_count": 0,
"runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b",
"ci_default_git_depth": 50,
"ci_forward_deployment_enabled": true,
"ci_forward_deployment_rollback_allowed": true,
"ci_allow_fork_pipelines_to_run_in_parent_project": true,
"ci_id_token_sub_claim_components": ["project_path", "ref_type", "ref"],
"ci_separated_caches": true,
"ci_restrict_pipeline_cancellation_role": "developer",
"ci_pipeline_variables_minimum_override_role": "maintainer",
"ci_push_repository_for_job_token_allowed": false,
"public_jobs": true,
"shared_with_groups": [],
"only_allow_merge_if_pipeline_succeeds": false,
"allow_merge_on_skipped_pipeline": false,
"allow_pipeline_trigger_approve_deployment": false,
"restrict_user_defined_variables": false,
"only_allow_merge_if_all_discussions_are_resolved": false,
"remove_source_branch_after_merge": false,
"request_access_enabled": false,
"merge_method": "merge",
"squash_option": "default_on",
"autoclose_referenced_issues": true,
"enforce_auth_checks_on_uploads": true,
"suggestion_commit_message": null,
"merge_commit_template": null,
"container_registry_image_prefix": "registry.example.com/diaspora/diaspora-project-site",
"secret_push_protection_enabled": false,
"_links": {
"self": "http://example.com/api/v4/projects",
"issues": "http://example.com/api/v4/projects/1/issues",
"merge_requests": "http://example.com/api/v4/projects/1/merge_requests",
"repo_branches": "http://example.com/api/v4/projects/1/repository_branches",
"labels": "http://example.com/api/v4/projects/1/labels",
"events": "http://example.com/api/v4/projects/1/events",
"members": "http://example.com/api/v4/projects/1/members",
"cluster_agents": "http://example.com/api/v4/projects/1/cluster_agents"
}
}
删除项目
删除一个项目。此端点:
- 删除项目及其所有相关资源,包括议题和合并请求。
- 在专业版或旗舰版级别,启用了延迟项目删除。
- 从极狐GitLab 15.11 开始,在专业版或旗舰版级别,如果:
- 项目已标记为删除。
- 传递了
permanently_remove
和full_path
参数。
- 从极狐GitLab 16.0 开始,在专业版或旗舰版级别,默认启用延迟项目删除。删除将在默认删除延迟中指定的天数后发生。
{{< alert type=”warning” >}}
在 管理员 区域从删除保护设置中立即删除项目的选项在极狐GitLab 15.9 中被弃用,并在极狐GitLab 16.0 中移除。
{{< /alert >}}
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 中引入。仅限专业版和旗舰版。 |
恢复标记为删除的项目
{{< details >}}
- 级别:专业版,旗舰版
- 提供:JihuLab.com,极狐GitLab 私有化部署,极狐GitLab 专属
{{< /details >}}
恢复标记为删除的项目。
POST /projects/:id/restore
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径。 |
将项目转移到新命名空间
将项目转移到新命名空间。
有关项目转移的先决条件的信息,请参阅 将项目转移到其他命名空间。
PUT /projects/:id/transfer
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径。 |
namespace |
integer or string | 是 | 要转移到的命名空间的 ID 或路径。 |
请求示例:
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/transfer?namespace=14"
响应示例:
{
"id": 7,
"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
"description_html": "<p data-sourcepos=\"1:1-1:56\" dir=\"auto\">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
"name": "hello-world",
"name_with_namespace": "cute-cats / hello-world",
"path": "hello-world",
"path_with_namespace": "cute-cats/hello-world",
"created_at": "2020-10-15T16:25:22.415Z",
"updated_at": "2020-10-15T16:25:22.415Z",
"default_branch": "main",
"tag_list": [], //已弃用, 使用 `topics` 替代
"topics": [],
"ssh_url_to_repo": "git@gitlab.example.com:cute-cats/hello-world.git",
"http_url_to_repo": "https://gitlab.example.com/cute-cats/hello-world.git",
"web_url": "https://gitlab.example.com/cute-cats/hello-world",
"readme_url": "https://gitlab.example.com/cute-cats/hello-world/-/blob/main/README.md",
"avatar_url": null,
"forks_count": 0,
"star_count": 0,
"last_activity_at": "2020-10-15T16:25:22.415Z",
"namespace": {
"id": 18,
"name": "cute-cats",
"path": "cute-cats",
"kind": "group",
"full_path": "cute-cats",
"parent_id": null,
"avatar_url": null,
"web_url": "https://gitlab.example.com/groups/cute-cats"
},
"container_registry_image_prefix": "registry.example.com/cute-cats/hello-world",
"_links": {
"self": "https://gitlab.example.com/api/v4/projects/7",
"issues": "https://gitlab.example.com/api/v4/projects/7/issues",
"merge_requests": "https://gitlab.example.com/api/v4/projects/7/merge_requests",
"repo_branches": "https://gitlab.example.com/api/v4/projects/7/repository/branches",
"labels": "https://gitlab.example.com/api/v4/projects/7/labels",
"events": "https://gitlab.example.com/api/v4/projects/7/events",
"members": "https://gitlab.example.com/api/v4/projects/7/members"
},
"packages_enabled": true,
"empty_repo": false,
"archived": false,
"visibility": "private",
"resolve_outdated_diff_discussions": false,
"container_registry_enabled": true, // 已弃用, 使用 container_registry_access_level 代替
"container_registry_access_level": "enabled",
"container_expiration_policy": {
"cadence": "7d",
"enabled": false,
"keep_n": null,
"older_than": null,
"name_regex": null,
"name_regex_keep": null,
"next_run_at": "2020-10-22T16:25:22.746Z"
},
"issues_enabled": true,
"merge_requests_enabled": true,
"wiki_enabled": true,
"jobs_enabled": true,
"snippets_enabled": true,
"service_desk_enabled": false,
"service_desk_address": null,
"can_create_merge_request_in": true,
"issues_access_level": "enabled",
"repository_access_level": "enabled",
"merge_requests_access_level": "enabled",
"forking_access_level": "enabled",
"analytics_access_level": "enabled",
"wiki_access_level": "enabled",
"builds_access_level": "enabled",
"snippets_access_level": "enabled",
"pages_access_level": "enabled",
"security_and_compliance_access_level": "enabled",
"emails_disabled": null,
"emails_enabled": null,
"shared_runners_enabled": true,
"group_runners_enabled": true,
"lfs_enabled": true,
"creator_id": 2,
"import_status": "none",
"open_issues_count": 0,
"ci_default_git_depth": 50,
"public_jobs": true,
"build_timeout": 3600,
"auto_cancel_pending_pipelines": "enabled",
"ci_config_path": null,
"shared_with_groups": [],
"only_allow_merge_if_pipeline_succeeds": false,
"allow_merge_on_skipped_pipeline": null,
"allow_pipeline_trigger_approve_deployment": false,
"restrict_user_defined_variables": false,
"request_access_enabled": true,
"only_allow_merge_if_all_discussions_are_resolved": false,
"remove_source_branch_after_merge": true,
"printing_merge_request_link_enabled": true,
"merge_method": "merge",
"squash_option": "default_on",
"suggestion_commit_message": null,
"merge_commit_template": null,
"auto_devops_enabled": true,
"auto_devops_deploy_strategy": "continuous",
"autoclose_referenced_issues": true,
"approvals_before_merge": 0, // 已弃用. 请改用合并请求审批 API。
"mirror": false,
"compliance_frameworks": [],
"warn_about_potentially_unwanted_characters": true,
"secret_push_protection_enabled": false
}
列出可用于项目转移的群组
{{< history >}}
- 在极狐GitLab 15.4 中引入。
{{< /history >}}
检索用户可以将项目转移到的群组列表。
GET /projects/:id/transfer_locations
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径。 |
search |
string | 否 | 要搜索的群组名称。 |
请求示例:
curl --request GET "https://gitlab.example.com/api/v4/projects/1/transfer_locations"
响应示例:
[
{
"id": 27,
"web_url": "https://gitlab.example.com/groups/gitlab",
"name": "GitLab",
"avatar_url": null,
"full_name": "GitLab",
"full_path": "GitLab"
},
{
"id": 31,
"web_url": "https://gitlab.example.com/groups/foobar",
"name": "FooBar",
"avatar_url": null,
"full_name": "FooBar",
"full_path": "FooBar"
}
]
上传项目头像
上传头像到指定项目。
PUT /projects/:id
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
avatar |
string | 是 | 要上传的文件。 |
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径。 |
要从文件系统上传头像,请使用 --form
参数。这会导致 cURL 使用 Content-Type: multipart/form-data
标头发布数据。file=
参数必须指向文件系统上的图像文件,并以 @
开头。例如:
请求示例:
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
--form "avatar=@dk.png" "https://gitlab.example.com/api/v4/projects/5"
响应示例:
{
"avatar_url": "https://gitlab.example.com/uploads/-/system/project/avatar/2/dk.png"
}
下载项目头像
{{< history >}}
- 在极狐GitLab 16.9 中引入。
{{< /history >}}
下载项目头像。如果项目是公开访问的,可以在没有身份验证的情况下访问此端点。
GET /projects/:id/avatar
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径。 |
请求示例:
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/avatar"
移除项目头像
{{< history >}}
- 在极狐GitLab 15.4 中引入。
{{< /history >}}
要移除项目头像,请对 avatar
属性使用空值。
请求示例:
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
--data "avatar=" "https://gitlab.example.com/api/v4/projects/5"
共享项目
将项目与群组共享。
与群组共享项目
将项目与群组共享。
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
且无内容。
DELETE /projects/:id/share/:group_id
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
group_id |
integer | 是 | 群组的 ID。 |
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径。 |
请求示例:
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/share/17"
启动项目的维护任务
启动项目的维护任务。
POST /projects/:id/housekeeping
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径。 |
task |
string | 否 |
prune 触发手动删除无法到达的对象或 eager 触发积极的维护任务。 |
实时安全扫描
{{< details >}}
- 级别:旗舰版
- 提供:JihuLab.com
- 状态:实验
{{< /details >}}
{{< history >}}
- 在极狐GitLab 17.6 中引入。此功能是一个实验。
{{< /history >}}
返回单个文件的实时 SAST 扫描结果。
POST /projects/:id/security_scans/sast/scan
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径。 |
请求示例:
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--header "Content-Type: application/json" \
--data '{
"file_path":"src/main.c",
"content":"#include<string.h>\nint main(int argc, char **argv) {\n char buff[128];\n strcpy(buff, argv[1]);\n return 0;\n}\n"
}' \
--url "https://gitlab.example.com/api/v4/projects/:id/security_scans/sast/scan"
响应示例:
{
"vulnerabilities": [
{
"name": "Insecure string processing function (strcpy)",
"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",
"severity": "High",
"location": {
"file": "src/main.c",
"start_line": 5,
"end_line": 5,
"start_column": 3,
"end_column": 23
}
}
]
}
下载 Git 仓库快照
只有管理员用户才能访问此端点。
下载项目(或维基,如果请求)Git 仓库的快照。此快照始终以未压缩的 tar) 格式。
如果仓库损坏到 git clone
不起作用的程度,快照可能允许检索部分数据。
GET /projects/:id/snapshot
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径。 |
wiki |
boolean | 否 | 是否下载维基,而不是项目仓库。 |
获取仓库存储路径
如果未使用 Gitaly 集群,则获取指定项目的仓库存储路径。如果使用 Gitaly 集群,请参见 Praefect 生成的副本路径。
仅管理员可用。
GET /projects/:id/storage
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径。 |
[
{
"project_id": 1,
"disk_path": "@hashed/6b/86/6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b",
"created_at": "2012-10-12T17:04:47Z",
"repository_storage": "default"
}
]
秘密推送保护状态
{{< details >}}
- 级别:旗舰版
{{< /details >}}
{{< history >}}
- 在极狐GitLab 17.3 中引入。
{{< /history >}}
如果您至少拥有开发者角色,以下请求也可能返回 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
响应示例:
{
"id": 1,
"project_id": 3,
"secret_push_protection_enabled": true,
...
}