- Project visibility level
- Project merge method
- List all projects
- List user projects
- List projects starred by a user
- Get single project
- Get project users
- List a project’s groups
- Get project events
- Create project
- Create project for user
- Edit project
- Fork project
- List forks of a project
- Star a project
- Unstar a project
- List starrers of a project
- Languages
- Archive a project
- Unarchive a project
- Delete project
- Restore project marked for deletion
- Upload a file
- Upload a project avatar
- Share project with group
- Delete a shared project link within a group
- Import project members
- Hooks
- Fork relationship
- Search for projects by name
- Start the Housekeeping task for a project
- Push rules
- Transfer a project to a new namespace
- Branches
- Project import/export
- Project members
- Project vulnerabilities
- Configure pull mirroring for a project
- Start the pull mirroring process for a Project
- Project badges
- Download snapshot of a Git repository
- Get the path to repository storage
Projects API
Interact with projects using the REST API.
Project visibility level
A project in GitLab can be private, internal, or public.
The visibility level is determined by the visibility field in the project.
Values for the project visibility level are:
-
private: project access must be granted explicitly for each user. -
internal: the project can be cloned by any signed-in user except external users. -
public: the project can be accessed without any authentication.
For more, read Project visibility.
Project merge method
There are three options for merge_method to choose from:
-
merge: a merge commit is created for every merge, and merging is allowed if there are no conflicts. -
rebase_merge: a merge commit is created for every merge, but merging is only allowed if fast-forward merge is possible. This way you could make sure that if this merge request would build, after merging to target branch it would also build. -
ff: no merge commits are created and all merges are fast-forwarded, which means that merging is only allowed if the branch could be fast-forwarded.
List all projects
Get a list of all visible projects across GitLab for the authenticated user. When accessed without authentication, only public projects with simple fields are returned.
GET /projects
This endpoint supports keyset pagination
for selected order_by options.
When simple=true or the user is unauthenticated this returns something like:
[
{
"id": 4,
"description": null,
"default_branch": "master",
"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/master/README.md",
"tag_list": [ //deprecated, use `topics` instead
"example",
"disapora client"
],
"topics": [
"example",
"disapora client"
],
"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",
"last_activity_at": "2013-09-30T13:46:02Z",
"forks_count": 0,
"avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png",
"star_count": 0
},
{
"id": 6,
"description": null,
"default_branch": "master",
...
When the user is authenticated and simple is not set this returns something like:
[
{
"id": 4,
"description": null,
"default_branch": "master",
"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/master/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",
"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,
"forks_count": 0,
"star_count": 0,
"runners_token": "b8547b1dc37721d05889db52fa2f02",
"ci_default_git_depth": 50,
"ci_forward_deployment_enabled": true,
"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,
"suggestion_commit_message": null,
"merge_commit_template": null,
"squash_commit_template": null,
"marked_for_deletion_at": "2020-04-03", // Deprecated and will be removed in API v5 in favor of marked_for_deletion_on
"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_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"
}
},
{
"id": 6,
"description": null,
"default_branch": "master",
"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/master/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",
"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,
"forks_count": 0,
"star_count": 0,
"runners_token": "b8547b1dc37721d05889db52fa2f02",
"ci_default_git_depth": 0,
"ci_forward_deployment_enabled": true,
"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",
"auto_devops_enabled": true,
"auto_devops_deploy_strategy": "continuous",
"repository_storage": "default",
"approvals_before_merge": 0,
"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,
"merge_commit_template": null,
"squash_commit_template": null,
"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_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"
}
}
]
tag_list attribute has been deprecated
and is removed in API v5 in favor of the topics attribute.Users of
can also see the You can filter by custom attributes with:
In GitLab 13.0 and later, offset-based pagination
is .
Keyset pagination is required to retrieve
projects beyond this limit.
Keyset pagination supports only Get a list of visible projects owned by the given user. When accessed without
authentication, only public projects are returned.
This endpoint supports keyset pagination
for selected approvals_before_merge parameter:
[
{
"id": 4,
"description": null,
"approvals_before_merge": 0,
...
}
]
GET /projects?custom_attributes[key]=value&custom_attributes[other_key]=other_value
Pagination limits
order_by=id. Other sorting options aren’t available.
List user projects
user_id) namespace are returned. Projects owned by the user in any group or subgroups are not returned. An empty list is returned if a profile is set to private.order_by options.
GET /users/:user_id/projects
| Attribute | Type | Required | Description |
|---|---|---|---|
user_id
| string | Yes | The ID or username of the user. |
archived
| boolean | No | Limit by archived status. |
id_after
| integer | No | Limit results to projects with IDs greater than the specified ID. |
id_before
| integer | No | Limit results to projects with IDs less than the specified ID. |
membership
| boolean | No | Limit by projects that the current user is a member of. |
min_access_level
| integer | No | Limit by current user minimal access level. |
order_by
| string | No | Return projects ordered by id, name, path, created_at, updated_at, 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. This is a no-op without authentication as then 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. Only available to Reporter or higher level role members. |
visibility
| string | No | Limit by visibility public, internal, or private.
|
with_custom_attributes
| boolean | No | Include custom attributes in response. (administrator only) |
with_issues_enabled
| boolean | No | Limit by enabled issues feature. |
with_merge_requests_enabled
| boolean | No | Limit by enabled merge requests feature. |
with_programming_language
| string | No | Limit by projects which use the given programming language. |
[
{
"id": 4,
"description": null,
"default_branch": "master",
"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/master/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",
"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,
"forks_count": 0,
"star_count": 0,
"runners_token": "b8547b1dc37721d05889db52fa2f02",
"ci_default_git_depth": 50,
"ci_forward_deployment_enabled": true,
"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,
"suggestion_commit_message": null,
"merge_commit_template": null,
"squash_commit_template": null,
"marked_for_deletion_at": "2020-04-03", // Deprecated and will be removed in API v5 in favor of marked_for_deletion_on
"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_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"
}
},
{
"id": 6,
"description": null,
"default_branch": "master",
"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/master/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",
"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,
"forks_count": 0,
"star_count": 0,
"runners_token": "b8547b1dc37721d05889db52fa2f02",
"ci_default_git_depth": 0,
"ci_forward_deployment_enabled": true,
"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",
"auto_devops_enabled": true,
"auto_devops_deploy_strategy": "continuous",
"repository_storage": "default",
"approvals_before_merge": 0,
"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,
"merge_commit_template": null,
"squash_commit_template": null,
"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_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"
}
}
]
List projects starred by a user
Get a list of visible projects starred by the given user. When accessed without authentication, only public projects are returned.
GET /users/:user_id/starred_projects
| Attribute | Type | Required | Description |
|---|---|---|---|
user_id
| string | Yes | The ID or username of the user. |
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 access level. |
order_by
| string | No | Return projects ordered by id, name, path, created_at, updated_at, 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. This is a no-op without authentication as then 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. Only available to Reporter or higher level role members. |
visibility
| string | No | Limit by visibility public, internal, or private.
|
with_custom_attributes
| boolean | No | Include custom attributes in response. (administrator only) |
with_issues_enabled
| boolean | No | Limit by enabled issues feature. |
with_merge_requests_enabled
| boolean | No | Limit by enabled merge requests feature. |
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/5/starred_projects"
Example response:
[
{
"id": 4,
"description": null,
"default_branch": "master",
"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/master/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",
"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,
"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,
"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,
"suggestion_commit_message": null,
"merge_commit_template": null,
"squash_commit_template": null,
"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_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"
}
},
{
"id": 6,
"description": null,
"default_branch": "master",
"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/master/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",
"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,
"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,
"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,
"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,
"merge_commit_template": null,
"squash_commit_template": null,
"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_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"
}
}
]
Get single project
Get a specific project. This endpoint can be accessed without authentication if the project is publicly accessible.
GET /projects/:id
| Attribute | Type | Required | Description |
|---|---|---|---|
id
| integer or string | Yes | The ID or URL-encoded path of the project. |
license
| boolean | No | Include project license data. |
statistics
| boolean | No | Include project statistics. Only available to Reporter or higher level role members. |
with_custom_attributes
| boolean | No | Include custom attributes in response. (administrators only) |
{
"id": 3,
"description": null,
"default_branch": "master",
"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/master/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",
"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_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/master/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,
"forks_count": 0,
"star_count": 0,
"runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b",
"ci_default_git_depth": 50,
"ci_forward_deployment_enabled": true,
"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,
"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,
"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,
"merge_commit_template": null,
"squash_commit_template": null,
"marked_for_deletion_at": "2020-04-03", // Deprecated and will be removed in API v5 in favor of marked_for_deletion_on
"marked_for_deletion_on": "2020-04-03",
"compliance_frameworks": [ "sox" ],
"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_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"
}
}
tag_list attribute has been deprecated
and is removed in API v5 in favor of the topics attribute.Users of
can also see the If the project is a fork, the
Users of
can also see the Get the users list of a project.
Get a list of ancestor groups for this project.
Refer to the Events API documentation.
Creates a new project owned by the authenticated user.
If your HTTP repository isn’t publicly accessible, add authentication information
to the URL Creates a new project owned by the specified user. Available only for administrators.
If your HTTP repository isn’t publicly accessible, add authentication information
to the URL Updates an existing project.
If your HTTP repository isn’t publicly accessible, add authentication information
to the URL For example, to toggle the setting for
shared runners on a GitLab.com project:
Supported attributes:
Forks a project into the user namespace of the authenticated user or the one provided.
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 List the projects accessible to the calling user that have an established,
forked relationship with the specified project
Example responses:
Stars a given project. Returns status code Example response:
Unstars a given project. Returns status code Example response:
List the users who starred the specified project.
Example responses:
Get languages used in a project with percentage value.
Example response:
Archives the project if the user is either an administrator or the owner of this
project. This action is idempotent, thus archiving an already archived project
does not change the project.
Example response:
Unarchives the project if the user is either an administrator or the owner of
this project. This action is idempotent, thus unarchiving a non-archived project
doesn’t change the project.
Example response:
This endpoint:
Restores project marked for deletion.
Uploads a file to the specified project to be used in an issue or merge request
description, or a comment. GitLab versions 14.0 and later
enforce this limit.
To upload a file from your file system, use the Returned object:
The returned
GitLab 13.11 added enforcement of the maximum attachment size limit behind the In Omnibus installations:
Enter the Rails console:
Disable the feature flag:
In installations from source:
Enter the Rails console:
Disable the feature flag:
Uploads an avatar to the specified project.
To upload an avatar from your file system, use the Example request:
Returned object:
Allow to share project with group.
Unshare the project from the group. Returns Import members from another project.
Returns:
Also called Project Hooks and Webhooks. These are different for System Hooks
that are system-wide.
Get a list of project hooks.
Get a specific hook for a project.
Adds a hook to a specified project.
Edits a hook for a specified project.
Removes a hook from a project. This is an idempotent method and can be called
multiple times. Either the hook is available or not.
Note the JSON response differs if the hook is available or not. If the project
hook is available before it’s returned in the JSON response or an empty response
is returned.
Allows modification of the forked relationship between existing projects.
Available only for project owners and administrators.
Search for projects by name which are accessible to the authenticated user. This
endpoint can be accessed without authentication if the project is publicly
accessible.
Get the push rules of a
project.
Users of
can also see the Adds a push rule to a specified project.
Edits a push rule for a specified project.
Removes a push rule from a project. This is an idempotent method and can be
called multiple times. Either the push rule is available or not.
See the Project documentation
for prerequisites to transfer a project.
Example request:
Example response:
Read more in the Branches documentation.
Read more in the Project import/export documentation.
Read more in the Project members documentation.
Read more in the Project vulnerabilities documentation.
Moved to GitLab Premium in 13.9.
Configure pull mirroring while creating a new project
or updating an existing project using the API
if the remote repository is publicly accessible
or via Read more in the Project Badges documentation.
This endpoint may only be accessed by an administrative user.
Download a snapshot of the project (or wiki, if requested) Git repository. This
snapshot is always in uncompressed
format.
If a repository is corrupted to the point where
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,
.
For problems setting up or using this feature (depending on your GitLab
subscription).approvals_before_merge parameter:
{
"id": 3,
"description": null,
"approvals_before_merge": 0,
...
}
forked_from_project field appears in the response.
For this field, if the upstream project is private, a valid token for authentication must be provided.
The field mr_default_target_self appears as well. If this value is false, then all merge requests
will target the upstream project by default.
{
"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":"master",
"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/master/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
}
}
...
}
Templates for issues and merge requests
issues_template and merge_requests_template parameters for managing
issue and merge request description templates.
{
"id": 3,
"issues_template": null,
"merge_requests_template": null,
...
}
Get project users
GET /projects/:id/users
Attribute
Type
Required
Description
id
integer or string
Yes
The ID or URL-encoded path of the project.
search
string
No
Search for specific users.
skip_users
integer array
No
Filter out users with the specified IDs.
[
{
"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"
}
]
List a project’s groups
GET /projects/:id/groups
Attribute
Type
Required
Description
id
integer or string
Yes
The ID or URL-encoded path of the project.
search
string
No
Search for specific groups.
shared_min_access_level
integer
No
Limit to shared groups with at least this access level.
shared_visible_only
boolean
No
Limit to shared groups user has access to.
skip_groups
array of integers
No
Skip the group IDs passed.
with_shared
boolean
No
Include projects shared with this group. Default is 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 project events
Create project
https://username:password@gitlab.company.com/group/project.git,
where password is a public access key with the api scope enabled.
POST /projects
Attribute
Type
Required
Description
name
string
Yes (if path isn’t provided)
The name of the new project. Equals path if not provided.
path
string
Yes (if name isn’t provided)
Repository name for new project. Generated based on name if not provided (generated as lowercase with dashes). Starting with GitLab 14.9, path must not start or end with a special character and must not contain consecutive special characters.
allow_merge_on_skipped_pipeline
boolean
No
Set whether or not merge requests can be merged with skipped jobs.
analytics_access_level
string
No
One of disabled, private or enabled
approvals_before_merge
integer
No
How many approvers should approve merge requests by default. To configure approval rules, see Merge request approvals API.
auto_cancel_pending_pipelines
string
No
Auto-cancel pending pipelines. This isn’t a boolean, but enabled/disabled.
auto_devops_deploy_strategy
string
No
Auto Deploy strategy ( continuous, manual or timed_incremental).
auto_devops_enabled
boolean
No
Enable Auto DevOps for this project.
autoclose_referenced_issues
boolean
No
Set whether auto-closing referenced issues on default branch.
avatar
mixed
No
Image file for avatar of the project.
build_coverage_regex
string
No
Test coverage parsing.
build_git_strategy
string
No
The Git strategy. Defaults to fetch.
build_timeout
integer
No
The maximum amount of time, in seconds, that a job can run.
builds_access_level
string
No
One of disabled, private, or enabled.
ci_config_path
string
No
The path to CI configuration file.
container_expiration_policy_attributes
hash
No
Update the image cleanup policy for this project. Accepts: cadence (string), keep_n (integer), older_than (string), name_regex (string), name_regex_delete (string), name_regex_keep (string), enabled (boolean). See the Container Registry documentation for more information on cadence, keep_n and older_than values.
container_registry_access_level
string
No
Set visibility of container registry, for this project, to one of disabled, private or enabled.
container_registry_enabled
boolean
No
(Deprecated) Enable container registry for this project. Use container_registry_access_level instead.
default_branch
string
No
The default branch name. Requires initialize_with_readme to be true.
description
string
No
Short project description.
emails_disabled
boolean
No
Disable email notifications.
external_authorization_classification_label
string
No
The classification label for the project.
forking_access_level
string
No
One of disabled, private, or enabled.
group_with_project_templates_id
integer
No
For group-level custom templates, specifies ID of group from which all the custom project templates are sourced. Leave empty for instance-level templates. Requires use_custom_template to be true.
import_url
string
No
URL to import repository from.
initialize_with_readme
boolean
No
false by default.
issues_access_level
string
No
One of disabled, private, or enabled.
issues_enabled
boolean
No
(Deprecated) Enable issues for this project. Use issues_access_level instead.
jobs_enabled
boolean
No
(Deprecated) Enable jobs for this project. Use builds_access_level instead.
lfs_enabled
boolean
No
Enable LFS.
merge_method
string
No
Set the merge method used.
merge_pipelines_enabled
boolean
No
Enable or disable merge pipelines.
merge_requests_access_level
string
No
One of disabled, private, or enabled.
merge_requests_enabled
boolean
No
(Deprecated) Enable merge requests for this project. Use merge_requests_access_level instead.
merge_trains_enabled
boolean
No
Enable or disable merge trains.
mirror_trigger_builds
boolean
No
Pull mirroring triggers builds.
mirror
boolean
No
Enables pull mirroring in a project.
namespace_id
integer
No
Namespace for the new project (defaults to the current user’s namespace).
only_allow_merge_if_all_discussions_are_resolved
boolean
No
Set whether merge requests can only be merged when all the discussions are resolved.
only_allow_merge_if_pipeline_succeeds
boolean
No
Set whether merge requests can only be merged with successful pipelines. This setting is named Pipelines must succeed in the project settings.
operations_access_level
string
No
One of disabled, private, or enabled.
packages_enabled
boolean
No
Enable or disable packages repository feature.
pages_access_level
string
No
One of disabled, private, enabled, or public.
printing_merge_request_link_enabled
boolean
No
Show link to create/view merge request when pushing from the command line.
public_builds
boolean
No
If true, jobs can be viewed by non-project members.
remove_source_branch_after_merge
boolean
No
Enable Delete source branch option by default for all new merge requests.
repository_access_level
string
No
One of disabled, private, or enabled.
repository_storage
string
No
Which storage shard the repository is on. (administrator only)
request_access_enabled
boolean
No
Allow users to request member access.
requirements_access_level
string
No
One of disabled, private or enabled
resolve_outdated_diff_discussions
boolean
No
Automatically resolve merge request diffs discussions on lines changed with a push.
security_and_compliance_access_level
string
No
(GitLab 14.9 and later) Security and compliance access level. One of disabled, private, or enabled.
shared_runners_enabled
boolean
No
Enable shared runners for this project.
snippets_access_level
string
No
One of disabled, private, or enabled.
snippets_enabled
boolean
No
(Deprecated) Enable snippets for this project. Use snippets_access_level instead.
squash_option
string
No
One of never, always, default_on, or default_off.
tag_list
array
No
(
template_name
string
No
When used without use_custom_template, name of a built-in project template. When used with use_custom_template, name of a custom project template.
template_project_id
integer
No
When used with use_custom_template, project ID of a custom project template. This is preferable to using template_name since template_name may be ambiguous.
topics
array
No
The list of topics for a project; put array of topics, that should be finally assigned to a project. (
use_custom_template
boolean
No
Use either custom instance or group (with group_with_project_templates_id) project template.
visibility
string
No
See project visibility level.
wiki_access_level
string
No
One of disabled, private, or enabled.
wiki_enabled
boolean
No
(Deprecated) Enable wiki for this project. Use wiki_access_level instead.
Create project for user
https://username:password@gitlab.company.com/group/project.git,
where password is a public access key with the api scope enabled.
POST /projects/user/:user_id
Edit project
https://username:password@gitlab.company.com/group/project.git,
where password is a public access key with the api scope enabled.
PUT /projects/:id
curl --request PUT --header "PRIVATE-TOKEN: <your-token>" \
--url 'https://gitlab.com/api/v4/projects/<your-project-ID>' \
--data "shared_runners_enabled=true" # to turn off: "shared_runners_enabled=false"
Fork project
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.
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 will be 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
GET /projects/:id/forks
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 access level.
order_by
string
No
Return projects ordered by id, name, path, created_at, updated_at, 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. This is a no-op without authentication as then 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. Only available to Reporter or higher level role members.
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.
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/forks"
[
{
"id": 3,
"description": null,
"default_branch": "master",
"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/master/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",
"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",
"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,
"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,
"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"
}
}
]
Star a project
304 if the project is already
starred.
POST /projects/:id/star
Attribute
Type
Required
Description
id
integer or string
Yes
The ID or URL-encoded path of the project.
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/star"
{
"id": 3,
"description": null,
"default_branch": "master",
"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/master/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",
"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",
"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",
"license_url": "http://example.com/diaspora/diaspora-client/blob/master/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,
"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,
"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"
}
}
Unstar a project
304 if the project is not starred.
POST /projects/:id/unstar
Attribute
Type
Required
Description
id
integer or string
Yes
The ID or URL-encoded path of the project.
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/unstar"
{
"id": 3,
"description": null,
"default_branch": "master",
"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/master/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",
"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",
"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",
"license_url": "http://example.com/diaspora/diaspora-client/blob/master/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,
"forks_count": 0,
"star_count": 0,
"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,
"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"
}
}
List starrers of a project
GET /projects/:id/starrers
Attribute
Type
Required
Description
id
integer or string
Yes
The ID or URL-encoded path of the project.
search
string
No
Search for specific users.
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/starrers"
[
{
"starred_since": "2019-01-28T14:47:30.642Z",
"user": {
"id": 1,
"username": "jane_smith",
"name": "Jane Smith",
"state": "active",
"avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
"web_url": "http://localhost:3000/jane_smith"
}
},
{
"starred_since": "2018-01-02T11:40:26.570Z",
"user": {
"id": 2,
"username": "janine_smith",
"name": "Janine Smith",
"state": "blocked",
"avatar_url": "http://gravatar.com/../e32131cd8.jpeg",
"web_url": "http://localhost:3000/janine_smith"
}
}
]
Languages
GET /projects/:id/languages
Attribute
Type
Required
Description
id
integer or string
Yes
The ID or URL-encoded path of the project.
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
}
Archive a project
POST /projects/:id/archive
Attribute
Type
Required
Description
id
integer or string
Yes
The ID or URL-encoded path of the project.
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/archive"
{
"id": 3,
"description": null,
"default_branch": "master",
"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/master/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",
"created_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/master/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,
"forks_count": 0,
"star_count": 0,
"runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b",
"ci_default_git_depth": 50,
"ci_forward_deployment_enabled": true,
"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,
"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"
}
}
Unarchive a project
POST /projects/:id/unarchive
Attribute
Type
Required
Description
id
integer or string
Yes
The ID or URL-encoded path of the project.
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/unarchive"
{
"id": 3,
"description": null,
"default_branch": "master",
"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/master/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",
"created_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/master/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,
"forks_count": 0,
"star_count": 0,
"runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b",
"ci_default_git_depth": 50,
"ci_forward_deployment_enabled": true,
"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,
"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"
}
}
Delete project
DELETE /projects/:id
Attribute
Type
Required
Description
id
integer or string
Yes
The ID or URL-encoded path of the project.
Restore project marked for deletion
POST /projects/:id/restore
Attribute
Type
Required
Description
id
integer or string
Yes
The ID or URL-encoded path of the project.
Upload a file
POST /projects/:id/uploads
Attribute
Type
Required
Description
file
string
Yes
The file to be uploaded.
id
integer or string
Yes
The ID or URL-encoded path of the project.
--form argument. This causes
cURL to post data using the header Content-Type: multipart/form-data. The
file= parameter must point to a file on your file system and be preceded by
@. For example:
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--form "file=@dk.png" "https://gitlab.example.com/api/v4/projects/5/uploads"
{
"alt": "dk",
"url": "/uploads/66dbcd21ec5d24ed6ea225176098d52b/dk.png",
"full_path": "/namespace1/project1/uploads/66dbcd21ec5d24ed6ea225176098d52b/dk.png",
"markdown": ""
}
url is relative to the project path. The returned full_path is
the absolute path to the file. In Markdown contexts, the link is expanded when
the format in markdown is used.
Max attachment size enforcement
enforce_max_attachment_size_upload_api feature flag. GitLab 14.0 enables this by default.
To disable this enforcement:
sudo gitlab-rails console
Feature.disable(:enforce_max_attachment_size_upload_api)
cd /home/git/gitlab
sudo -u git -H bundle exec rails console -e production
Feature.disable(:enforce_max_attachment_size_upload_api)
Upload a project avatar
PUT /projects/:id
Attribute
Type
Required
Description
avatar
string
Yes
The file to be uploaded.
id
integer or string
Yes
The ID or URL-encoded path of the project.
--form argument. This causes
cURL to post data using the header Content-Type: multipart/form-data. The
file= parameter must point to an image file on your file system and be
preceded by @. For example:
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"
}
Share project with group
POST /projects/:id/share
Attribute
Type
Required
Description
group_access
integer
Yes
The access level to grant the group.
group_id
integer
Yes
The ID of the group to share with.
id
integer or string
Yes
The ID or URL-encoded path of the project.
expires_at
string
No
Share expiration date in ISO 8601 format: 2016-09-26
Delete a shared project link within a group
204 and no content on success.
DELETE /projects/:id/share/:group_id
Attribute
Type
Required
Description
group_id
integer
Yes
The ID of the group.
id
integer or string
Yes
The ID or URL-encoded path of the project.
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/share/17"
Import project members
POST /projects/:id/import_project_members/:project_id
Attribute
Type
Required
Description
id
integer or string
Yes
The ID or URL-encoded path of the target project to receive the members.
project_id
integer or string
Yes
The ID or URL-encoded path of the source project to import the members from.
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/import_project_members/32"
200 OK on success.
404 Project Not Found if the target or source project does not exist or cannot be accessed by the requester.
422 Unprocessable Entity if the import of project members does not complete successfully.
Hooks
List project hooks
GET /projects/:id/hooks
Attribute
Type
Required
Description
id
integer or string
Yes
The ID or URL-encoded path of the project.
Get project hook
GET /projects/:id/hooks/:hook_id
Attribute
Type
Required
Description
hook_id
integer
Yes
The ID of a project hook.
id
integer or string
Yes
The ID or URL-encoded path of the project.
{
"id": 1,
"url": "http://example.com/hook",
"project_id": 3,
"push_events": true,
"push_events_branch_filter": "",
"issues_events": true,
"confidential_issues_events": true,
"merge_requests_events": true,
"tag_push_events": true,
"note_events": true,
"confidential_note_events": true,
"job_events": true,
"pipeline_events": true,
"wiki_page_events": true,
"deployment_events": true,
"releases_events": true,
"enable_ssl_verification": true,
"created_at": "2012-10-12T17:04:47Z"
}
Add project hook
POST /projects/:id/hooks
Attribute
Type
Required
Description
id
integer or string
Yes
The ID or URL-encoded path of the project.
url
string
Yes
The hook URL.
confidential_issues_events
boolean
No
Trigger hook on confidential issues events.
confidential_note_events
boolean
No
Trigger hook on confidential note events.
deployment_events
boolean
No
Trigger hook on deployment events.
enable_ssl_verification
boolean
No
Do SSL verification when triggering the hook.
issues_events
boolean
No
Trigger hook on issues events.
job_events
boolean
No
Trigger hook on job events.
merge_requests_events
boolean
No
Trigger hook on merge requests events.
note_events
boolean
No
Trigger hook on note events.
pipeline_events
boolean
No
Trigger hook on pipeline events.
push_events_branch_filter
string
No
Trigger hook on push events for matching branches only.
push_events
boolean
No
Trigger hook on push events.
releases_events
boolean
No
Trigger hook on release events.
tag_push_events
boolean
No
Trigger hook on tag push events.
token
string
No
Secret token to validate received payloads; this isn’t returned in the response.
wiki_page_events
boolean
No
Trigger hook on wiki events.
Edit project hook
PUT /projects/:id/hooks/:hook_id
Attribute
Type
Required
Description
hook_id
integer
Yes
The ID of the project hook.
id
integer or string
Yes
The ID or URL-encoded path of the project.
url
string
Yes
The hook URL.
confidential_issues_events
boolean
No
Trigger hook on confidential issues events.
confidential_note_events
boolean
No
Trigger hook on confidential note events.
deployment_events
boolean
No
Trigger hook on deployment events.
enable_ssl_verification
boolean
No
Do SSL verification when triggering the hook.
issues_events
boolean
No
Trigger hook on issues events.
job_events
boolean
No
Trigger hook on job events.
merge_requests_events
boolean
No
Trigger hook on merge requests events.
note_events
boolean
No
Trigger hook on note events.
pipeline_events
boolean
No
Trigger hook on pipeline events.
push_events_branch_filter
string
No
Trigger hook on push events for matching branches only.
push_events
boolean
No
Trigger hook on push events.
releases_events
boolean
No
Trigger hook on release events.
tag_push_events
boolean
No
Trigger hook on tag push events.
token
string
No
Secret token to validate received payloads; this isn’t returned in the response.
wiki_page_events
boolean
No
Trigger hook on wiki page events.
Delete project hook
DELETE /projects/:id/hooks/:hook_id
Attribute
Type
Required
Description
hook_id
integer
Yes
The ID of the project hook.
id
integer or string
Yes
The ID or URL-encoded path of the project.
Fork relationship
Create a forked from/to relation between existing projects
POST /projects/:id/fork/:forked_from_id
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 an existing forked from relationship
DELETE /projects/:id/fork
Attribute
Type
Required
Description
id
integer or string
Yes
The ID or URL-encoded path of the project.
Search for projects by name
GET /projects
Attribute
Type
Required
Description
search
string
Yes
A string contained in the project name.
order_by
string
No
Return requests ordered by id, name, created_at or last_activity_at fields.
sort
string
No
Return requests sorted in asc or desc order.
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects?search=test"
Start the Housekeeping task for a project
POST /projects/:id/housekeeping
Attribute
Type
Required
Description
id
integer or string
Yes
The ID or URL-encoded path of the project.
Push rules
Get project push rules
GET /projects/:id/push_rule
Attribute
Type
Required
Description
id
integer or string
Yes
The ID or URL-encoded path of the project
{
"id": 1,
"project_id": 3,
"commit_message_regex": "Fixes \\d+\\..*",
"commit_message_negative_regex": "ssh\\:\\/\\/",
"branch_name_regex": "",
"deny_delete_tag": false,
"created_at": "2012-10-12T17:04:47Z",
"member_check": false,
"prevent_secrets": false,
"author_email_regex": "",
"file_name_regex": "",
"max_file_size": 5,
"commit_committer_check": false,
"reject_unsigned_commits": false
}
commit_committer_check and reject_unsigned_commits
parameters:
{
"id": 1,
"project_id": 3,
"commit_committer_check": false,
"reject_unsigned_commits": false
...
}
Add project push rule
POST /projects/:id/push_rule
Attribute
Type
Required
Description
id
integer or string
Yes
The ID or URL-encoded path of the project.
author_email_regex
string
No
All commit author emails must match this, for example @my-company.com$.
branch_name_regex
string
No
All branch names must match this, for example (feature|hotfix)\/*.
commit_committer_check
boolean
No
Users can only push commits to this repository if the committer email is one of their own verified emails.
commit_message_negative_regex
string
No
No commit message is allowed to match this, for example ssh\:\/\/.
commit_message_regex
string
No
All commit messages must match this, for example Fixed \d+\..*.
deny_delete_tag
boolean
No
Deny deleting a tag.
file_name_regex
string
No
All committed filenames must not match this, for example (jar|exe)$.
max_file_size
integer
No
Maximum file size (MB).
member_check
boolean
No
Restrict commits by author (email) to existing GitLab users.
prevent_secrets
boolean
No
GitLab rejects any files that are likely to contain secrets.
reject_unsigned_commits
boolean
No
Reject commit when it’s not signed through GPG.
Edit project push rule
PUT /projects/:id/push_rule
Attribute
Type
Required
Description
id
integer or string
Yes
The ID or URL-encoded path of the project.
author_email_regex
string
No
All commit author emails must match this, for example @my-company.com$.
branch_name_regex
string
No
All branch names must match this, for example (feature|hotfix)\/*.
commit_committer_check
boolean
No
Users can only push commits to this repository if the committer email is one of their own verified emails.
commit_message_negative_regex
string
No
No commit message is allowed to match this, for example ssh\:\/\/.
commit_message_regex
string
No
All commit messages must match this, for example Fixed \d+\..*.
deny_delete_tag
boolean
No
Deny deleting a tag.
file_name_regex
string
No
All committed filenames must not match this, for example (jar|exe)$.
max_file_size
integer
No
Maximum file size (MB).
member_check
boolean
No
Restrict commits by author (email) to existing GitLab users.
prevent_secrets
boolean
No
GitLab rejects any files that are likely to contain secrets.
reject_unsigned_commits
boolean
No
Reject commits when they are not GPG signed.
Delete project push rule
DELETE /projects/:id/push_rule
Attribute
Type
Required
Description
id
integer or string
Yes
The ID or URL-encoded path of the project.
Transfer a project to a new namespace
PUT /projects/:id/transfer
Attribute
Type
Required
Description
id
integer or string
Yes
The ID or URL-encoded path of the project.
namespace
integer or string
Yes
The ID or path of the namespace to transfer to project to.
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/transfer?namespace=14"
{
"id": 7,
"description": "",
"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",
"default_branch": "master",
"tag_list": [], //deprecated, use `topics` instead
"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/master/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, // deprecated, use container_registry_access_level instead
"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,
"shared_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",
"build_coverage_regex": null,
"ci_config_path": null,
"shared_with_groups": [],
"only_allow_merge_if_pipeline_succeeds": false,
"allow_merge_on_skipped_pipeline": null,
"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,
"mirror": false,
"compliance_frameworks": []
}
Branches
Project import/export
Project members
Project vulnerabilities
Configure pull mirroring for a project
username:token authentication.
In case your HTTP repository is not publicly accessible,
you can add the authentication information to the URL:
https://username:token@gitlab.company.com/group/project.git,
where token is a personal access token
with the API scope enabled.
Attribute
Type
Required
Description
import_url
string
Yes
URL of remote repository being mirrored (with user:token if needed).
mirror
boolean
Yes
Enables pull mirroring on project when set to true.
mirror_trigger_builds
boolean
No
Trigger pipelines for mirror updates when set to true.
only_mirror_protected_branches
boolean
No
Limits mirroring to only protected branches when set to true.
Start the pull mirroring process for a Project
POST /projects/:id/mirror/pull
Attribute
Type
Required
Description
id
integer or string
Yes
The ID or URL-encoded path of the project.
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/mirror/pull"
Project badges
Download snapshot of a Git repository
git clone doesn’t work, the
snapshot may allow some of the data to be retrieved.
GET /projects/:id/snapshot
Attribute
Type
Required
Description
id
integer or string
Yes
The ID or URL-encoded path of the project.
wiki
boolean
No
Whether to download the wiki, rather than project, repository.
Get the path to repository storage
Attribute
Type
Required
Description
id
integer or string
Yes
ID or URL-encoded path of the project.
[
{
"project_id": 1,
"disk_path": "@hashed/6b/86/6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b",
"created_at": "2012-10-12T17:04:47Z",
"repository_storage": "default"
}
]
Help & feedback
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.
to help shape new features.
Feature availability and product trials
to see all GitLab tiers and features, or to upgrade.
with access to all features for 30 days.
Get Help