diff options
Diffstat (limited to 'doc/api/groups.md')
| -rw-r--r-- | doc/api/groups.md | 64 |
1 files changed, 32 insertions, 32 deletions
diff --git a/doc/api/groups.md b/doc/api/groups.md index 0a584795d21..b4d36b568b8 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Groups API @@ -338,8 +338,8 @@ 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. +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` differs from the group the request is being made for. ## List a group's shared projects @@ -479,7 +479,7 @@ Example response: ## Details of a group Get all details of a group. This endpoint can be accessed without authentication -if the group is publicly accessible. In case the user that requests is admin of the group, it will return the `runners_token` for the group too. +if the group is publicly accessible. In case the user that requests is admin of the group, it returns the `runners_token` for the group too. ```plaintext GET /groups/:id @@ -491,10 +491,10 @@ 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 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).) | +| `with_projects` | boolean | no | Include details from projects that belong to the specified group (defaults to `true`). (Deprecated, [scheduled for removal 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). +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). 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 @@ -670,7 +670,7 @@ Example response: } ``` -Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit` and `extra_shared_runners_minutes_limit` parameters: Additional response parameters: @@ -685,7 +685,7 @@ Additional response parameters: } ``` -Users on GitLab [Silver, Premium, or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Silver, Premium, or higher](https://about.gitlab.com/pricing/) also see the `marked_for_deletion_on` attribute: ```json @@ -697,7 +697,7 @@ the `marked_for_deletion_on` attribute: } ``` -When adding the parameter `with_projects=false`, projects will not be returned. +When adding the parameter `with_projects=false`, projects aren't returned. ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/4?with_projects=false" @@ -790,7 +790,7 @@ The `shared_runners_setting` attribute determines whether shared runners are ena ## New Subgroup -This is similar to creating a [New group](#new-group). You'll need the `parent_id` from the [List groups](#list-groups) call. You can then enter the desired: +This is similar to creating a [New group](#new-group). You need the `parent_id` from the [List groups](#list-groups) call. You can then enter the desired: - `subgroup_path` - `subgroup_name` @@ -853,8 +853,8 @@ PUT /groups/:id | `extra_shared_runners_minutes_limit` | integer | no | **(STARTER ONLY)** Extra pipeline minutes quota for this group (purchased in addition to the minutes included in the plan). | | `prevent_forking_outside_group` | boolean | no | **(PREMIUM)** When enabled, users can **not** fork projects from this group to external namespaces -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). +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). 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 @@ -948,7 +948,7 @@ Only available to group owners and administrators. This endpoint either: - Removes group, and queues a background job to delete all projects in the group as well. -- Since [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [Premium or Silver](https://about.gitlab.com/pricing/) or higher tiers, marks a group for deletion. The deletion will happen 7 days later by default, but this can be changed in the [instance settings](../user/admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). +- Since [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [Premium or Silver](https://about.gitlab.com/pricing/) or higher tiers, marks a group for deletion. The deletion happens 7 days later by default, but this can be changed in the [instance settings](../user/admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). ```plaintext DELETE /groups/:id @@ -960,7 +960,7 @@ Parameters: | --------------- | -------------- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | -The response will be `202 Accepted` if the user has authorization. +The response is `202 Accepted` if the user has authorization. ## Restore group marked for deletion **(PREMIUM)** @@ -1074,7 +1074,7 @@ POST /groups/:id/hooks | `deployment_events` | boolean | no | Trigger hook on deployment events | | `releases_events` | boolean | no | Trigger hook on release events | | `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook | -| `token` | string | no | Secret token to validate received payloads; this will not be returned in the response | +| `token` | string | no | Secret token to validate received payloads; not returned in the response | ### Edit group hook @@ -1102,7 +1102,7 @@ PUT /groups/:id/hooks/:hook_id | `deployment_events` | boolean | no | Trigger hook on deployment events | | `releases_events` | boolean | no | Trigger hook on release events | | `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook | -| `token` | string | no | Secret token to validate received payloads; this will not be returned in the response | +| `token` | string | no | Secret token to validate received payloads; not returned in the response | ### Delete group hook @@ -1170,12 +1170,12 @@ POST /groups/:id/ldap_group_links | `group_access` | integer | yes | Minimum [access level](members.md#valid-access-levels) for members of the LDAP group | | `provider` | string | yes | LDAP provider for the LDAP group link | -NOTE: **Note:** +NOTE: To define the LDAP group link, provide either a `cn` or a `filter`, but not both. ### Delete LDAP group link **(STARTER ONLY)** -Deletes an LDAP group link. Deprecated. Will be removed in a future release. +Deletes an LDAP group link. Deprecated. Scheduled for removal in a future release. ```plaintext DELETE /groups/:id/ldap_group_links/:cn @@ -1186,7 +1186,7 @@ DELETE /groups/:id/ldap_group_links/:cn | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | | `cn` | string | yes | The CN of an LDAP group | -Deletes an LDAP group link for a specific LDAP provider. Deprecated. Will be removed in a future release. +Deletes an LDAP group link for a specific LDAP provider. Deprecated. Scheduled for removal in a future release. ```plaintext DELETE /groups/:id/ldap_group_links/:provider/:cn @@ -1213,7 +1213,7 @@ DELETE /groups/:id/ldap_group_links | `filter` | string | no | The LDAP filter for the group | | `provider` | string | yes | LDAP provider for the LDAP group link | -NOTE: **Note:** +NOTE: To delete the LDAP group link, provide either a `cn` or a `filter`, but not both. ## Namespaces in groups @@ -1306,7 +1306,7 @@ GET /groups/:id/push_rule } ``` -Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) will also see +Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) also see the `commit_committer_check` and `reject_unsigned_commits` parameters: ```json @@ -1334,15 +1334,15 @@ POST /groups/:id/push_rule | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | | `deny_delete_tag` **(STARTER)** | boolean | no | Deny deleting a tag | | `member_check` **(STARTER)** | boolean | no | Allows only GitLab users to author commits | -| `prevent_secrets` **(STARTER)** | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) will be rejected | +| `prevent_secrets` **(STARTER)** | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) are rejected | | `commit_message_regex` **(STARTER)** | string | no | All commit messages must match the regular expression provided in this attribute, e.g. `Fixed \d+\..*` | -| `commit_message_negative_regex` **(STARTER)** | string | no | Commit messages matching the regular expression provided in this attribute will not be allowed, e.g. `ssh\:\/\/` | +| `commit_message_negative_regex` **(STARTER)** | string | no | Commit messages matching the regular expression provided in this attribute aren't allowed, e.g. `ssh\:\/\/` | | `branch_name_regex` **(STARTER)** | string | no | All branch names must match the regular expression provided in this attribute, e.g. `(feature|hotfix)\/*` | | `author_email_regex` **(STARTER)** | string | no | All commit author emails must match the regular expression provided in this attribute, e.g. `@my-company.com$` | -| `file_name_regex` **(STARTER)** | string | no | Filenames matching the regular expression provided in this attribute will **not** be allowed, e.g. `(jar|exe)$` | +| `file_name_regex` **(STARTER)** | string | no | Filenames matching the regular expression provided in this attribute are **not** allowed, e.g. `(jar|exe)$` | | `max_file_size` **(STARTER)** | integer | no | Maximum file size (MB) allowed | -| `commit_committer_check` **(PREMIUM)** | boolean | no | Only commits pushed using verified emails will be allowed | -| `reject_unsigned_commits` **(PREMIUM)** | boolean | no | Only commits signed through GPG will be allowed | +| `commit_committer_check` **(PREMIUM)** | boolean | no | Only commits pushed using verified emails are allowed | +| `reject_unsigned_commits` **(PREMIUM)** | boolean | no | Only commits signed through GPG are allowed | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/19/push_rule" @@ -1381,15 +1381,15 @@ PUT /groups/:id/push_rule | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | | `deny_delete_tag` **(STARTER)** | boolean | no | Deny deleting a tag | | `member_check` **(STARTER)** | boolean | no | Restricts commits to be authored by existing GitLab users only | -| `prevent_secrets` **(STARTER)** | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) will be rejected | +| `prevent_secrets` **(STARTER)** | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) are rejected | | `commit_message_regex` **(STARTER)** | string | no | All commit messages must match the regular expression provided in this attribute, e.g. `Fixed \d+\..*` | -| `commit_message_negative_regex` **(STARTER)** | string | no | Commit messages matching the regular expression provided in this attribute will not be allowed, e.g. `ssh\:\/\/` | +| `commit_message_negative_regex` **(STARTER)** | string | no | Commit messages matching the regular expression provided in this attribute aren't allowed, e.g. `ssh\:\/\/` | | `branch_name_regex` **(STARTER)** | string | no | All branch names must match the regular expression provided in this attribute, e.g. `(feature|hotfix)\/*` | | `author_email_regex` **(STARTER)** | string | no | All commit author emails must match the regular expression provided in this attribute, e.g. `@my-company.com$` | -| `file_name_regex` **(STARTER)** | string | no | Filenames matching the regular expression provided in this attribute will **not** be allowed, e.g. `(jar|exe)$` | +| `file_name_regex` **(STARTER)** | string | no | Filenames matching the regular expression provided in this attribute are **not** allowed, e.g. `(jar|exe)$` | | `max_file_size` **(STARTER)** | integer | no | Maximum file size (MB) allowed | -| `commit_committer_check` **(PREMIUM)** | boolean | no | Only commits pushed using verified emails will be allowed | -| `reject_unsigned_commits` **(PREMIUM)** | boolean | no | Only commits signed through GPG will be allowed | +| `commit_committer_check` **(PREMIUM)** | boolean | no | Only commits pushed using verified emails are allowed | +| `reject_unsigned_commits` **(PREMIUM)** | boolean | no | Only commits signed through GPG are allowed | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/19/push_rule" |