Project forks API
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
You can manage project forks 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.
POST /projects/:id/fork| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | The ID or URL-encoded path of the project. |
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 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.
GET /projects/:id/forksSupported attributes:
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | The ID or URL-encoded path of the project. |
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). |
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 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 in GitLab 15.10. |
visibility | string | No | Limit by visibility public, internal, or private. |
with_custom_attributes | boolean | No | Include custom attributes 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:
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/forks"Example responses:
[
{
"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.
POST /projects/:id/fork/:forked_from_idSupported 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. |
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.
DELETE /projects/:id/forkSupported attributes:
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | The ID or URL-encoded path of the project. |
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support