diff options
Diffstat (limited to 'doc/api/groups.md')
| -rw-r--r-- | doc/api/groups.md | 159 |
1 files changed, 147 insertions, 12 deletions
diff --git a/doc/api/groups.md b/doc/api/groups.md index 34c01766d06..bc7bff2964b 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -109,7 +109,7 @@ GET /groups?custom_attributes[key]=value&custom_attributes[other_key]=other_valu ## List a group's subgroups -> [Introduced][ce-15142] in GitLab 10.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15142) in GitLab 10.3. Get a list of visible direct subgroups in this group. When accessed without authentication, only public groups are returned. @@ -241,9 +241,142 @@ Example response: ``` NOTE: **Note:** - To distinguish between a project in the group and a project shared to the group, the `namespace` attribute can be used. When a project has been shared to the group, its `namespace` will be different from the group the request is being made for. +## List a group's shared projects + +Get a list of projects shared to this group. When accessed without authentication, only public shared projects are returned. + +By default, this request returns 20 results at a time because the API results [are paginated](README.md#pagination). + +```plaintext +GET /groups/:id/projects/shared +``` + +Parameters: + +| Attribute | Type | Required | Description | +| ----------------------------- | -------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `archived` | boolean | no | Limit by archived status | +| `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 | +| `simple` | boolean | no | Return only the ID, URL, name, and path of each project | +| `starred` | boolean | no | Limit by projects starred by the current user | +| `with_issues_enabled` | boolean | no | Limit by projects with issues feature enabled. Default is `false` | +| `with_merge_requests_enabled` | boolean | no | Limit by projects with merge requests feature enabled. Default is `false` | +| `min_access_level` | integer | no | Limit to projects where current user has at least this [access level](members.md) | +| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | + +Example response: + +```json +[ + { + "id":8, + "description":"Shared project for Html5 Boilerplate", + "name":"Html5 Boilerplate", + "name_with_namespace":"H5bp / Html5 Boilerplate", + "path":"html5-boilerplate", + "path_with_namespace":"h5bp/html5-boilerplate", + "created_at":"2020-04-27T06:13:22.642Z", + "default_branch":"master", + "tag_list":[ + + ], + "ssh_url_to_repo":"ssh://git@gitlab.com/h5bp/html5-boilerplate.git", + "http_url_to_repo":"http://gitlab.com/h5bp/html5-boilerplate.git", + "web_url":"http://gitlab.com/h5bp/html5-boilerplate", + "readme_url":"http://gitlab.com/h5bp/html5-boilerplate/-/blob/master/README.md", + "avatar_url":null, + "star_count":0, + "forks_count":4, + "last_activity_at":"2020-04-27T06:13:22.642Z", + "namespace":{ + "id":28, + "name":"H5bp", + "path":"h5bp", + "kind":"group", + "full_path":"h5bp", + "parent_id":null, + "avatar_url":null, + "web_url":"http://gitlab.com/groups/h5bp" + }, + "_links":{ + "self":"http://gitlab.com/api/v4/projects/8", + "issues":"http://gitlab.com/api/v4/projects/8/issues", + "merge_requests":"http://gitlab.com/api/v4/projects/8/merge_requests", + "repo_branches":"http://gitlab.com/api/v4/projects/8/repository/branches", + "labels":"http://gitlab.com/api/v4/projects/8/labels", + "events":"http://gitlab.com/api/v4/projects/8/events", + "members":"http://gitlab.com/api/v4/projects/8/members" + }, + "empty_repo":false, + "archived":false, + "visibility":"public", + "resolve_outdated_diff_discussions":false, + "container_registry_enabled":true, + "container_expiration_policy":{ + "cadence":"7d", + "enabled":true, + "keep_n":null, + "older_than":null, + "name_regex":null, + "name_regex_keep":null, + "next_run_at":"2020-05-04T06:13:22.654Z" + }, + "issues_enabled":true, + "merge_requests_enabled":true, + "wiki_enabled":true, + "jobs_enabled":true, + "snippets_enabled":true, + "can_create_merge_request_in":true, + "issues_access_level":"enabled", + "repository_access_level":"enabled", + "merge_requests_access_level":"enabled", + "forking_access_level":"enabled", + "wiki_access_level":"enabled", + "builds_access_level":"enabled", + "snippets_access_level":"enabled", + "pages_access_level":"enabled", + "emails_disabled":null, + "shared_runners_enabled":true, + "lfs_enabled":true, + "creator_id":1, + "import_status":"failed", + "open_issues_count":10, + "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":[ + { + "group_id":24, + "group_name":"Commit451", + "group_full_path":"Commit451", + "group_access_level":30, + "expires_at":null + } + ], + "only_allow_merge_if_pipeline_succeeds":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", + "suggestion_commit_message":null, + "auto_devops_enabled":true, + "auto_devops_deploy_strategy":"continuous", + "autoclose_referenced_issues":true, + "repository_storage":"default" + } +] +``` + ## Details of a group Get all details of a group. This endpoint can be accessed without authentication @@ -259,7 +392,11 @@ Parameters: | ------------------------ | -------------- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user. | | `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only). | -| `with_projects` | boolean | no | Include details from projects that belong to the specified group (defaults to `true`). (Deprecated, [will be removed in 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). To get the details of all projects within a group, use the [list a group's projects endpoint](#list-a-groups-projects).) | +| `with_projects` | boolean | no | Include details from projects that belong to the specified group (defaults to `true`). (Deprecated, [will be removed in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). To get the details of all projects within a group, use the [list a group's projects endpoint](#list-a-groups-projects).) | + +NOTE: **Note:** +The `projects` and `shared_projects` attributes in the response are deprecated and will be [removed in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). +To get the details of all projects within a group, use either the [list a group's projects](#list-a-groups-projects) or the [list a group's shared projects](#list-a-groups-shared-projects) endpoint. ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/4 @@ -290,7 +427,7 @@ Example response: "file_template_project_id": 1, "parent_id": null, "created_at": "2020-01-15T12:36:29.590Z", - "projects": [ + "projects": [ // Deprecated and will be removed in API v5 { "id": 7, "description": "Voluptas veniam qui et beatae voluptas doloremque explicabo facilis.", @@ -368,7 +505,7 @@ Example response: "request_access_enabled": false } ], - "shared_projects": [ + "shared_projects": [ // Deprecated and will be removed in API v5 { "id": 8, "description": "Velit eveniet provident fugiat saepe eligendi autem.", @@ -571,6 +708,10 @@ PUT /groups/:id | `shared_runners_minutes_limit` | integer | no | **(STARTER ONLY)** Pipeline minutes quota for this group. | | `extra_shared_runners_minutes_limit` | integer | no | **(STARTER ONLY)** Extra pipeline minutes quota for this group. | +NOTE: **Note:** +The `projects` and `shared_projects` attributes in the response are deprecated and will be [removed in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). +To get the details of all projects within a group, use either the [list a group's projects](#list-a-groups-projects) or the [list a group's shared projects](#list-a-groups-shared-projects) endpoint. + ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5?name=Experimental" ``` @@ -582,10 +723,6 @@ This endpoint returns: and later. To get the details of all projects within a group, use the [list a group's projects endpoint](#list-a-groups-projects) instead. -NOTE: **Note:** - -The `projects` and `shared_projects` attributes [will be deprecated in GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). To get the details of all projects within a group, use the [list a group's projects endpoint](#list-a-groups-projects) instead. - Example response: ```json @@ -603,7 +740,7 @@ Example response: "file_template_project_id": 1, "parent_id": null, "created_at": "2020-01-15T12:36:29.590Z", - "projects": [ + "projects": [ // Deprecated and will be removed in API v5 { "id": 9, "description": "foo", @@ -944,8 +1081,6 @@ And to switch pages add: /groups?per_page=100&page=2 ``` -[ce-15142]: https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15142 - ## Group badges Read more in the [Group Badges](group_badges.md) documentation. |