Skip to content
代码片段 群组 项目
未验证 提交 529f6176 编辑于 作者: Marcel Amirault's avatar Marcel Amirault 提交者： GitLab
浏览文件

Merge branch 'eread/split-off-project-forks-api-documentation' into 'master' 

Split off project forks API documentation

See merge request https://gitlab.com/gitlab-org/gitlab/-/merge_requests/167861



Merged-by: default avatarMarcel Amirault <mamirault@gitlab.com>
Approved-by: default avatarMarcel Amirault <mamirault@gitlab.com>
Co-authored-by: default avatarEvan Read <eread@gitlab.com>
上级 22322d97 d914d3ca
No related branches found
No related tags found
无相关合并请求
隐藏空白变更内容
行内 左右并排
doc/api/project_forks.md 0 → 100644
+ 200
− 0
浏览文件 @ 529f6176
---
stage: Data Stores
group: Tenant Scale
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
---
# Project forks API
DETAILS:
**Tier:** Free, Premium, Ultimate
**Offering:** GitLab.com, Self-managed, GitLab Dedicated
You can manage [project forks](../user/project/repository/forking_workflow.md) by using the REST API.
## Fork a project
Fork a project into your personal namespace or the namespace provided.
Prerequisites:
- You must be authenticated.
The forking operation for a project is asynchronous and is completed in a
background job. The request returns immediately. To determine whether the
fork of the project has completed, query the `import_status` for the new project.
```plaintext
POST /projects/:id/fork
```
| Attribute | Type | Required | Description |
|:-------------------------|:------------------|:---------|:------------|
| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `branches` | string | No | Branches to fork (empty for all branches). |
| `description` | string | No | The description assigned to the resultant project after forking. |
| `mr_default_target_self` | boolean | No | For forked projects, target merge requests to this project. If `false`, the target is the upstream project. |
| `name` | string | No | The name assigned to the resultant project after forking. |
| `namespace_id` | integer | No | The ID of the namespace that the project is forked to. |
| `namespace_path` | string | No | The path of the namespace that the project is forked to. |
| `namespace` | integer or string | No | _(Deprecated)_ The ID or path of the namespace that the project is forked to. |
| `path` | string | No | The path assigned to the resultant project after forking. |
| `visibility` | string | No | The [visibility level](projects.md#project-visibility-level) assigned to the resultant project after forking. |
## List forks of a project
List the projects accessible to you that have an established forked relationship with the specified project.
```plaintext
GET /projects/:id/forks
```
Supported attributes:
| Attribute | Type | Required | Description |
|:------------------------------|:------------------|:---------|:------------|
| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `archived` | boolean | No | Limit by archived status. |
| `membership` | boolean | No | Limit by projects that the current user is a member of. |
| `min_access_level` | integer | No | Limit by current user minimal [role (`access_level`)](members.md#roles). |
| `order_by` | string | No | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, `star_count`, or `last_activity_at` fields. Default is `created_at`. |
| `owned` | boolean | No | Limit by projects explicitly owned by the current user. |
| `search` | string | No | Return list of projects matching the search criteria. |
| `simple` | boolean | No | Return only limited fields for each project. Without authentication, this operation is a no-op; only simple fields are returned. |
| `sort` | string | No | Return projects sorted in `asc` or `desc` order. Default is `desc`. |
| `starred` | boolean | No | Limit by projects starred by the current user. |
| `statistics` | boolean | No | Include project statistics. Available only to users with at least the Reporter role. |
| `updated_after` | datetime | No | Limit results to projects last updated after the specified time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393979) in GitLab 15.10. |
| `updated_before` | datetime | No | Limit results to projects last updated before the specified time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393979) in GitLab 15.10. |
| `visibility` | string | No | Limit by visibility `public`, `internal`, or `private`. |
| `with_custom_attributes` | boolean | No | Include [custom attributes](custom_attributes.md) in response. _(administrators only)_ |
| `with_issues_enabled` | boolean | No | Limit by enabled issues feature. |
| `with_merge_requests_enabled` | boolean | No | Limit by enabled merge requests feature. |
Example request:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/forks"
```
Example responses:
```json
[
{
"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": "internal",
"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"
],
"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, // 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": true,
"avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png",
"shared_runners_enabled": true,
"group_runners_enabled": true,
"forks_count": 0,
"star_count": 1,
"public_jobs": true,
"shared_with_groups": [],
"only_allow_merge_if_pipeline_succeeds": false,
"allow_merge_on_skipped_pipeline": 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",
"_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"
}
}
]
```
## Create a fork relationship between projects
Create a fork relationship between projects.
Prerequisites:
- You must be an administrator or be assigned the Owner role on the project.
```plaintext
POST /projects/:id/fork/:forked_from_id
```
Supported attributes:
| Attribute | Type | Required | Description |
|:-----------------|:------------------|:---------|:------------|
| `forked_from_id` | ID | Yes | The ID of the project that was forked from. |
| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
## Delete a fork relationship between projects
Delete a fork relationship between projects.
Prerequisites:
- You must be an administrator or be assigned the Owner role on the project.
```plaintext
DELETE /projects/:id/fork
```
Supported attributes:
| Attribute | Type | Required | Description |
|:----------|:------------------|:---------|:------------|
| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
doc/api/projects.md
+ 0
− 187
浏览文件 @ 529f6176
...@@ -1882,193 +1882,6 @@ Supported project visibility attributes: ...@@ -1882,193 +1882,6 @@ Supported project visibility attributes:
| `snippets_access_level` | string | No | Set visibility of [snippets](../user/snippets.md#change-default-visibility-of-snippets). | | `snippets_access_level` | string | No | Set visibility of [snippets](../user/snippets.md#change-default-visibility-of-snippets). |
| `wiki_access_level` | string | No | Set visibility of [wiki](../user/project/wiki/index.md#enable-or-disable-a-project-wiki). | | `wiki_access_level` | string | No | Set visibility of [wiki](../user/project/wiki/index.md#enable-or-disable-a-project-wiki). |
## Fork a project
Fork a project into your personal namespace or the namespace provided.
Prerequisites:
- You must be authenticated.
The forking operation for a project is asynchronous and is completed in a
background job. The request returns immediately. To determine whether the
fork of the project has completed, query the `import_status` for the new project.
```plaintext
POST /projects/:id/fork
```
| Attribute | Type | Required | Description |
|:-------------------------|:------------------|:---------|:------------|
| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `branches` | string | No | Branches to fork (empty for all branches). |
| `description` | string | No | The description assigned to the resultant project after forking. |
| `mr_default_target_self` | boolean | No | For forked projects, target merge requests to this project. If `false`, the target is the upstream project. |
| `name` | string | No | The name assigned to the resultant project after forking. |
| `namespace_id` | integer | No | The ID of the namespace that the project is forked to. |
| `namespace_path` | string | No | The path of the namespace that the project is forked to. |
| `namespace` | integer or string | No | _(Deprecated)_ The ID or path of the namespace that the project is forked to. |
| `path` | string | No | The path assigned to the resultant project after forking. |
| `visibility` | string | No | The [visibility level](#project-visibility-level) assigned to the resultant project after forking. |
## List forks of a project
List the projects accessible to you that have an established forked relationship with the specified project.
```plaintext
GET /projects/:id/forks
```
Supported attributes:
| Attribute | Type | Required | Description |
|:------------------------------|:------------------|:---------|:------------|
| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
| `archived` | boolean | No | Limit by archived status. |
| `membership` | boolean | No | Limit by projects that the current user is a member of. |
| `min_access_level` | integer | No | Limit by current user minimal [role (`access_level`)](members.md#roles). |
| `order_by` | string | No | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, `star_count`, or `last_activity_at` fields. Default is `created_at`. |
| `owned` | boolean | No | Limit by projects explicitly owned by the current user. |
| `search` | string | No | Return list of projects matching the search criteria. |
| `simple` | boolean | No | Return only limited fields for each project. Without authentication, this operation is a no-op; only simple fields are returned. |
| `sort` | string | No | Return projects sorted in `asc` or `desc` order. Default is `desc`. |
| `starred` | boolean | No | Limit by projects starred by the current user. |
| `statistics` | boolean | No | Include project statistics. Available only to users with at least the Reporter role. |
| `updated_after` | datetime | No | Limit results to projects last updated after the specified time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393979) in GitLab 15.10. |
| `updated_before` | datetime | No | Limit results to projects last updated before the specified time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393979) in GitLab 15.10. |
| `visibility` | string | No | Limit by visibility `public`, `internal`, or `private`. |
| `with_custom_attributes` | boolean | No | Include [custom attributes](custom_attributes.md) in response. _(administrators only)_ |
| `with_issues_enabled` | boolean | No | Limit by enabled issues feature. |
| `with_merge_requests_enabled` | boolean | No | Limit by enabled merge requests feature. |
Example request:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/forks"
```
Example responses:
```json
[
{
"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": "internal",
"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"
],
"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, // 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": true,
"avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png",
"shared_runners_enabled": true,
"group_runners_enabled": true,
"forks_count": 0,
"star_count": 1,
"public_jobs": true,
"shared_with_groups": [],
"only_allow_merge_if_pipeline_succeeds": false,
"allow_merge_on_skipped_pipeline": 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",
"_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"
}
}
]
```
## Create a fork relationship between projects
Create a fork relationship between projects.
Prerequisites:
- You must be an administrator or be assigned the Owner role on the project.
```plaintext
POST /projects/:id/fork/:forked_from_id
```
Supported attributes:
| Attribute | Type | Required | Description |
|:-----------------|:------------------|:---------|:------------|
| `forked_from_id` | ID | Yes | The ID of the project that was forked from. |
| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
## Delete a fork relationship between projects
Delete a fork relationship between projects.
Prerequisites:
- You must be an administrator or be assigned the Owner role on the project.
```plaintext
DELETE /projects/:id/fork
```
Supported attributes:
| Attribute | Type | Required | Description |
|:----------|:------------------|:---------|:------------|
| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-paths). |
## Star a project ## Star a project
Star a project. Star a project.
......
doc/user/project/repository/forking_workflow.md
+ 1
− 1
浏览文件 @ 529f6176
...@@ -200,7 +200,7 @@ Prerequisites: ...@@ -200,7 +200,7 @@ Prerequisites:
WARNING: WARNING:
If you remove a fork relationship, you can't send merge requests to the source. If you remove a fork relationship, you can't send merge requests to the source.
If anyone has forked your project, their fork also loses the relationship. If anyone has forked your project, their fork also loses the relationship.
To restore the fork relationship, [use the API](../../../api/projects.md#create-a-fork-relationship-between-projects). To restore the fork relationship, [use the API](../../../api/project_forks.md#create-a-fork-relationship-between-projects).
To remove a fork relationship: To remove a fork relationship:
......
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或