diff options
Diffstat (limited to 'doc/api/groups.md')
| -rw-r--r-- | doc/api/groups.md | 66 |
1 files changed, 30 insertions, 36 deletions
diff --git a/doc/api/groups.md b/doc/api/groups.md index 8b4850fa6de..6d295b50a01 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -1,11 +1,15 @@ --- -stage: Manage -group: Organization +stage: Data Stores +group: Tenant Scale info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Groups API **(FREE)** +Interact with [groups](../user/group/index.md) by using the REST API. + +The fields returned in responses vary based on the [permissions](../user/permissions.md) of the authenticated user. + ## List groups Get a list of visible groups for the authenticated user. When accessed without @@ -27,7 +31,7 @@ Parameters: | `search` | string | no | Return the list of authorized groups matching the search criteria | | `order_by` | string | no | Order groups by `name`, `path`, `id`, or `similarity` (if searching, [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332889) in GitLab 14.1). Default is `name` | | `sort` | string | no | Order groups in `asc` or `desc` order. Default is `asc` | -| `statistics` | boolean | no | Include group statistics (administrators only) | +| `statistics` | boolean | no | Include group statistics (administrators only).<br>*Note:* The REST API response does not provide the full `RootStorageStatistics` data that is shown in the UI. To match the data in the UI, use GraphQL instead of REST. For more information, see the [Group GraphQL reference](../api/graphql/reference/index.md#group).| | `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (administrators only) | | `owned` | boolean | no | Limit to groups explicitly owned by the current user | | `min_access_level` | integer | no | Limit to groups where current user has at least this [role (`access_level`)](members.md#roles) | @@ -110,11 +114,14 @@ GET /groups?statistics=true "packages_size": 0, "snippets_size": 50, "uploads_size": 0 - } + }, + "wiki_access_level": "private" } ] ``` +Users of [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see the `wiki_access_level` attribute. + You can search for groups by name or path, see below. You can filter by [custom attributes](custom_attributes.md) with: @@ -184,6 +191,8 @@ GET /groups/:id/subgroups ] ``` +Users of [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see the `wiki_access_level` attribute. + ## List a group's descendant groups > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217115) in GitLab 13.5 @@ -267,6 +276,8 @@ GET /groups/:id/descendant_groups ] ``` +Users of [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see the `wiki_access_level` attribute. + ## List a group's projects Get a list of projects in this group. When accessed without authentication, only public projects are returned. @@ -514,11 +525,6 @@ To get the details of all projects within a group, use either the [list a group' curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/4" ``` -NOTE: -There is [a known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/345200) that can -prevent `runners_token` from being returned when the call has the `with_projects=false` -parameter. - This endpoint returns: - All projects and shared projects in GitLab 12.5 and earlier. @@ -695,10 +701,15 @@ Example response: The `prevent_sharing_groups_outside_hierarchy` attribute is present only on top-level groups. -Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see -the `shared_runners_minutes_limit` and `extra_shared_runners_minutes_limit` parameters: +Users of [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see the attributes: -Additional response parameters: +- `shared_runners_minutes_limit` +- `extra_shared_runners_minutes_limit` +- `marked_for_deletion_on` +- `membership_lock` +- `wiki_access_level` + +Additional response attributes: ```json { @@ -706,30 +717,9 @@ Additional response parameters: "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.", "shared_runners_minutes_limit": 133, "extra_shared_runners_minutes_limit": 133, - ... -} -``` - -Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see -the `marked_for_deletion_on` attribute: - -```json -{ - "id": 4, - "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.", "marked_for_deletion_on": "2020-04-03", - ... -} -``` - -Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see -the `membership_lock` attribute: - -```json -{ - "id": 4, - "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.", "membership_lock": false, + "wiki_access_level": "disabled", ... } ``` @@ -832,6 +822,7 @@ Parameters: | `membership_lock` **(PREMIUM)** | boolean | no | Users cannot be added to projects in this group. | | `extra_shared_runners_minutes_limit` **(PREMIUM SELF)** | integer | no | Can be set by administrators only. Additional CI/CD minutes for this group. | | `shared_runners_minutes_limit` **(PREMIUM SELF)** | integer | no | Can be set by administrators only. Maximum number of monthly CI/CD minutes for this group. Can be `nil` (default; inherit system default), `0` (unlimited), or `> 0`. | +| `wiki_access_level` **(PREMIUM)** | string | no | The wiki access level. Can be `disabled`, `private`, or `enabled`. | ### Options for `default_branch_protection` @@ -996,6 +987,7 @@ PUT /groups/:id | `unique_project_download_limit_alertlist` **(ULTIMATE)** | array of integers | no | List of user IDs that are emailed when the unique project download limit is exceeded. Available only on top-level groups. Default: `[]`, Maximum: 100 user IDs. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110201) in GitLab 15.9. | | `auto_ban_user_on_excessive_projects_download` **(ULTIMATE)** | boolean | no | When enabled, users are automatically banned from the group when they download more than the maximum number of unique projects specified by `unique_project_download_limit` and `unique_project_download_limit_interval_in_seconds`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/94159) in GitLab 15.4. | | `ip_restriction_ranges` **(PREMIUM)** | string | no | Comma-separated list of IP addresses or subnet masks to restrict group access. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/351493) in GitLab 15.4. | +| `wiki_access_level` **(PREMIUM)** | string | no | The wiki access level. Can be `disabled`, `private`, or `enabled`. | NOTE: The `projects` and `shared_projects` attributes in the response are deprecated and [scheduled for removal in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). @@ -1078,6 +1070,8 @@ Example response: The `prevent_sharing_groups_outside_hierarchy` attribute is present in the response only for top-level groups. +Users of [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see the `wiki_access_level` attribute. + ### Disable the results limit **(FREE SELF)** The 100 results limit can break integrations developed using GitLab 12.4 and earlier. @@ -1142,7 +1136,7 @@ Only available to group owners and administrators. This endpoint: -- On Premium and higher tiers, marks the group for deletion. The deletion happens 7 days later by default, but you can change the retention period in the [instance settings](../user/admin_area/settings/visibility_and_access_controls.md#deletion-protection). +- On Premium and Ultimate tiers, marks the group for deletion. The deletion happens 7 days later by default, but you can change the retention period in the [instance settings](../user/admin_area/settings/visibility_and_access_controls.md#deletion-protection). - On Free tier, removes the group immediately and queues a background job to delete all projects in the group. - Deletes a subgroup immediately if the subgroup is marked for deletion (GitLab 15.4 and later). The endpoint does not immediately delete top-level groups. @@ -1740,7 +1734,7 @@ GET /groups/:id/push_rule } ``` -Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see +Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see the `commit_committer_check` and `reject_unsigned_commits` parameters: ```json |