diff options
Diffstat (limited to 'doc/api/projects.md')
| -rw-r--r-- | doc/api/projects.md | 136 |
1 files changed, 71 insertions, 65 deletions
diff --git a/doc/api/projects.md b/doc/api/projects.md index e9ef03a0c0c..686f3dba35d 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -4,23 +4,23 @@ ### Project visibility level Project in GitLab has be either private, internal or public. -You can determine it by `visibility_level` field in project. +You can determine it by `visibility` field in project. Constants for project visibility levels are next: -* Private. `visibility_level` is `0`. +* `private`: Project access must be granted explicitly for each user. -* Internal. `visibility_level` is `10`. +* `internal`: The project can be cloned by any logged in user. -* Public. `visibility_level` is `20`. +* `public`: The project can be cloned without any authentication. ## List projects -Get a list of projects for which the authenticated user is a member. +Get a list of visible projects for authenticated user. When being accessed without authentication, all public projects are returned. ``` GET /projects @@ -34,9 +34,10 @@ Parameters: | `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | | `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` | | `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` | -| `search` | string | no | Return list of authorized projects matching the search criteria | +| `search` | string | no | Return list of projects matching the search criteria | | `simple` | boolean | no | Return only the ID, URL, name, and path of each project | | `owned` | boolean | no | Limit by projects owned by the current user | +| `membership` | boolean | no | Limit by projects that the current user is a member of | | `starred` | boolean | no | Limit by projects starred by the current user | ```json @@ -45,8 +46,7 @@ Parameters: "id": 4, "description": null, "default_branch": "master", - "public": false, - "visibility_level": 0, + "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", @@ -66,7 +66,7 @@ Parameters: "issues_enabled": true, "open_issues_count": 1, "merge_requests_enabled": true, - "builds_enabled": true, + "jobs_enabled": true, "wiki_enabled": true, "snippets_enabled": false, "container_registry_enabled": false, @@ -86,9 +86,9 @@ Parameters: "forks_count": 0, "star_count": 0, "runners_token": "b8547b1dc37721d05889db52fa2f02", - "public_builds": true, + "public_jobs": true, "shared_with_groups": [], - "only_allow_merge_if_build_succeeds": false, + "only_allow_merge_if_pipeline_succeeds": false, "only_allow_merge_if_all_discussions_are_resolved": false, "request_access_enabled": false }, @@ -96,8 +96,7 @@ Parameters: "id": 6, "description": null, "default_branch": "master", - "public": false, - "visibility_level": 0, + "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", @@ -117,7 +116,7 @@ Parameters: "issues_enabled": true, "open_issues_count": 1, "merge_requests_enabled": true, - "builds_enabled": true, + "jobs_enabled": true, "wiki_enabled": true, "snippets_enabled": false, "container_registry_enabled": false, @@ -147,9 +146,9 @@ Parameters: "forks_count": 0, "star_count": 0, "runners_token": "b8547b1dc37721d05889db52fa2f02", - "public_builds": true, + "public_jobs": true, "shared_with_groups": [], - "only_allow_merge_if_build_succeeds": false, + "only_allow_merge_if_pipeline_succeeds": false, "only_allow_merge_if_all_discussions_are_resolved": false, "request_access_enabled": false } @@ -177,8 +176,7 @@ Parameters: "id": 3, "description": null, "default_branch": "master", - "public": false, - "visibility_level": 0, + "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", @@ -198,7 +196,7 @@ Parameters: "issues_enabled": true, "open_issues_count": 1, "merge_requests_enabled": true, - "builds_enabled": true, + "jobs_enabled": true, "wiki_enabled": true, "snippets_enabled": false, "container_registry_enabled": false, @@ -228,7 +226,7 @@ Parameters: "forks_count": 0, "star_count": 0, "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b", - "public_builds": true, + "public_jobs": true, "shared_with_groups": [ { "group_id": 4, @@ -241,7 +239,7 @@ Parameters: "group_access_level": 10 } ], - "only_allow_merge_if_build_succeeds": false, + "only_allow_merge_if_pipeline_succeeds": false, "only_allow_merge_if_all_discussions_are_resolved": false, "request_access_enabled": false } @@ -407,8 +405,6 @@ Parameters: }, "created_at": "2015-12-04T10:33:56.698Z", "system": false, - "upvote": false, - "downvote": false, "noteable_id": 377, "noteable_type": "Issue" }, @@ -437,21 +433,21 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `name` | string | yes | The name of the new project | -| `path` | string | no | Custom repository name for new project. By default generated based on name | +| `name` | string | yes if path is not provided | The name of the new project. Equals path if not provided. | +| `path` | string | yes if name is not provided | Repository name for new project. Generated based on name if not provided (generated lowercased with dashes). | | `namespace_id` | integer | no | Namespace for the new project (defaults to the current user's namespace) | | `description` | string | no | Short project description | | `issues_enabled` | boolean | no | Enable issues for this project | | `merge_requests_enabled` | boolean | no | Enable merge requests for this project | -| `builds_enabled` | boolean | no | Enable builds for this project | +| `jobs_enabled` | boolean | no | Enable jobs for this project | | `wiki_enabled` | boolean | no | Enable wiki for this project | | `snippets_enabled` | boolean | no | Enable snippets for this project | | `container_registry_enabled` | boolean | no | Enable container registry for this project | | `shared_runners_enabled` | boolean | no | Enable shared runners for this project | -| `visibility_level` | integer | no | See [project visibility level](#project-visibility-level) | +| `visibility` | String | no | See [project visibility level](#project-visibility-level) | | `import_url` | string | no | URL to import repository from | -| `public_builds` | boolean | no | If `true`, builds can be viewed by non-project-members | -| `only_allow_merge_if_build_succeeds` | boolean | no | Set whether merge requests can only be merged with successful builds | +| `public_jobs` | boolean | no | If `true`, jobs can be viewed by non-project-members | +| `only_allow_merge_if_pipeline_succeeds` | boolean | no | Set whether merge requests can only be merged with successful jobs | | `only_allow_merge_if_all_discussions_are_resolved` | boolean | no | Set whether merge requests can only be merged when all the discussions are resolved | | `lfs_enabled` | boolean | no | Enable LFS | | `request_access_enabled` | boolean | no | Allow users to request member access | @@ -476,15 +472,15 @@ Parameters: | `description` | string | no | Short project description | | `issues_enabled` | boolean | no | Enable issues for this project | | `merge_requests_enabled` | boolean | no | Enable merge requests for this project | -| `builds_enabled` | boolean | no | Enable builds for this project | +| `jobs_enabled` | boolean | no | Enable jobs for this project | | `wiki_enabled` | boolean | no | Enable wiki for this project | | `snippets_enabled` | boolean | no | Enable snippets for this project | | `container_registry_enabled` | boolean | no | Enable container registry for this project | | `shared_runners_enabled` | boolean | no | Enable shared runners for this project | -| `visibility_level` | integer | no | See [project visibility level](#project-visibility-level) | +| `visibility` | string | no | See [project visibility level](#project-visibility-level) | | `import_url` | string | no | URL to import repository from | -| `public_builds` | boolean | no | If `true`, builds can be viewed by non-project-members | -| `only_allow_merge_if_build_succeeds` | boolean | no | Set whether merge requests can only be merged with successful builds | +| `public_jobs` | boolean | no | If `true`, jobs can be viewed by non-project-members | +| `only_allow_merge_if_pipeline_succeeds` | boolean | no | Set whether merge requests can only be merged with successful jobs | | `only_allow_merge_if_all_discussions_are_resolved` | boolean | no | Set whether merge requests can only be merged when all the discussions are resolved | | `lfs_enabled` | boolean | no | Enable LFS | | `request_access_enabled` | boolean | no | Allow users to request member access | @@ -508,15 +504,15 @@ Parameters: | `description` | string | no | Short project description | | `issues_enabled` | boolean | no | Enable issues for this project | | `merge_requests_enabled` | boolean | no | Enable merge requests for this project | -| `builds_enabled` | boolean | no | Enable builds for this project | +| `jobs_enabled` | boolean | no | Enable jobs for this project | | `wiki_enabled` | boolean | no | Enable wiki for this project | | `snippets_enabled` | boolean | no | Enable snippets for this project | | `container_registry_enabled` | boolean | no | Enable container registry for this project | | `shared_runners_enabled` | boolean | no | Enable shared runners for this project | -| `visibility_level` | integer | no | See [project visibility level](#project-visibility-level) | +| `visibility` | string | no | See [project visibility level](#project-visibility-level) | | `import_url` | string | no | URL to import repository from | -| `public_builds` | boolean | no | If `true`, builds can be viewed by non-project-members | -| `only_allow_merge_if_build_succeeds` | boolean | no | Set whether merge requests can only be merged with successful builds | +| `public_jobs` | boolean | no | If `true`, jobs can be viewed by non-project-members | +| `only_allow_merge_if_pipeline_succeeds` | boolean | no | Set whether merge requests can only be merged with successful jobs | | `only_allow_merge_if_all_discussions_are_resolved` | boolean | no | Set whether merge requests can only be merged when all the discussions are resolved | | `lfs_enabled` | boolean | no | Enable LFS | | `request_access_enabled` | boolean | no | Allow users to request member access | @@ -551,7 +547,7 @@ Parameters: | `id` | integer/string | yes | The ID or NAMESPACE/PROJECT_NAME of the project | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/star" +curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/star" ``` Example response: @@ -561,8 +557,7 @@ Example response: "id": 3, "description": null, "default_branch": "master", - "public": false, - "visibility_level": 10, + "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", @@ -577,7 +572,7 @@ Example response: "issues_enabled": true, "open_issues_count": 1, "merge_requests_enabled": true, - "builds_enabled": true, + "jobs_enabled": true, "wiki_enabled": true, "snippets_enabled": false, "container_registry_enabled": false, @@ -596,9 +591,9 @@ Example response: "shared_runners_enabled": true, "forks_count": 0, "star_count": 1, - "public_builds": true, + "public_jobs": true, "shared_with_groups": [], - "only_allow_merge_if_build_succeeds": false, + "only_allow_merge_if_pipeline_succeeds": false, "only_allow_merge_if_all_discussions_are_resolved": false, "request_access_enabled": false } @@ -617,7 +612,7 @@ POST /projects/:id/unstar | `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/unstar" +curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/unstar" ``` Example response: @@ -627,8 +622,7 @@ Example response: "id": 3, "description": null, "default_branch": "master", - "public": false, - "visibility_level": 10, + "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", @@ -643,7 +637,7 @@ Example response: "issues_enabled": true, "open_issues_count": 1, "merge_requests_enabled": true, - "builds_enabled": true, + "jobs_enabled": true, "wiki_enabled": true, "snippets_enabled": false, "container_registry_enabled": false, @@ -662,9 +656,9 @@ Example response: "shared_runners_enabled": true, "forks_count": 0, "star_count": 0, - "public_builds": true, + "public_jobs": true, "shared_with_groups": [], - "only_allow_merge_if_build_succeeds": false, + "only_allow_merge_if_pipeline_succeeds": false, "only_allow_merge_if_all_discussions_are_resolved": false, "request_access_enabled": false } @@ -684,7 +678,7 @@ POST /projects/:id/archive | `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/archive" +curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/archive" ``` Example response: @@ -694,8 +688,7 @@ Example response: "id": 3, "description": null, "default_branch": "master", - "public": false, - "visibility_level": 0, + "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", @@ -715,7 +708,7 @@ Example response: "issues_enabled": true, "open_issues_count": 1, "merge_requests_enabled": true, - "builds_enabled": true, + "jobs_enabled": true, "wiki_enabled": true, "snippets_enabled": false, "container_registry_enabled": false, @@ -745,9 +738,9 @@ Example response: "forks_count": 0, "star_count": 0, "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b", - "public_builds": true, + "public_jobs": true, "shared_with_groups": [], - "only_allow_merge_if_build_succeeds": false, + "only_allow_merge_if_pipeline_succeeds": false, "only_allow_merge_if_all_discussions_are_resolved": false, "request_access_enabled": false } @@ -767,7 +760,7 @@ POST /projects/:id/unarchive | `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/unarchive" +curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/unarchive" ``` Example response: @@ -777,8 +770,7 @@ Example response: "id": 3, "description": null, "default_branch": "master", - "public": false, - "visibility_level": 0, + "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", @@ -798,7 +790,7 @@ Example response: "issues_enabled": true, "open_issues_count": 1, "merge_requests_enabled": true, - "builds_enabled": true, + "jobs_enabled": true, "wiki_enabled": true, "snippets_enabled": false, "container_registry_enabled": false, @@ -828,9 +820,9 @@ Example response: "forks_count": 0, "star_count": 0, "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b", - "public_builds": true, + "public_jobs": true, "shared_with_groups": [], - "only_allow_merge_if_build_succeeds": false, + "only_allow_merge_if_pipeline_succeeds": false, "only_allow_merge_if_all_discussions_are_resolved": false, "request_access_enabled": false } @@ -916,7 +908,7 @@ Parameters: | `group_id` | integer | yes | The ID of the group | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/share/17 +curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/share/17 ``` ## Hooks @@ -963,7 +955,7 @@ Parameters: "merge_requests_events": true, "tag_push_events": true, "note_events": true, - "build_events": true, + "job_events": true, "pipeline_events": true, "wiki_page_events": true, "enable_ssl_verification": true, @@ -990,7 +982,7 @@ Parameters: | `merge_requests_events` | boolean | no | Trigger hook on merge requests events | | `tag_push_events` | boolean | no | Trigger hook on tag push events | | `note_events` | boolean | no | Trigger hook on note events | -| `build_events` | boolean | no | Trigger hook on build events | +| `job_events` | boolean | no | Trigger hook on job events | | `pipeline_events` | boolean | no | Trigger hook on pipeline events | | `wiki_events` | boolean | no | Trigger hook on wiki events | | `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook | @@ -1016,7 +1008,7 @@ Parameters: | `merge_requests_events` | boolean | no | Trigger hook on merge requests events | | `tag_push_events` | boolean | no | Trigger hook on tag push events | | `note_events` | boolean | no | Trigger hook on note events | -| `build_events` | boolean | no | Trigger hook on build events | +| `job_events` | boolean | no | Trigger hook on job events | | `pipeline_events` | boolean | no | Trigger hook on pipeline events | | `wiki_events` | boolean | no | Trigger hook on wiki events | | `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook | @@ -1195,3 +1187,17 @@ Parameters: | `query` | 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 | + +## Start the Housekeeping task for a Project + +>**Note:** This feature was introduced in GitLab 9.0 + +``` +POST /projects/:id/housekeeping +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | |