diff options
Diffstat (limited to 'doc/user/group')
19 files changed, 311 insertions, 78 deletions
diff --git a/doc/user/group/epics/epic_boards.md b/doc/user/group/epics/epic_boards.md index 1bc1e4d703b..d184030718a 100644 --- a/doc/user/group/epics/epic_boards.md +++ b/doc/user/group/epics/epic_boards.md @@ -9,10 +9,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5067) in GitLab 13.10. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/290039) in GitLab 14.1. -INFO: -Try epic boards and more with a -[free 30-day trial of GitLab Ultimate](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-epics-boards-docs). - Epic boards build on the existing [epic tracking functionality](index.md) and [labels](../../project/labels.md). Your epics appear as cards in vertical lists, organized by their assigned labels. diff --git a/doc/user/group/epics/img/epics_search_v13_11.png b/doc/user/group/epics/img/epics_search_v13_11.png Binary files differdeleted file mode 100644 index c11aca96a99..00000000000 --- a/doc/user/group/epics/img/epics_search_v13_11.png +++ /dev/null diff --git a/doc/user/group/epics/img/epics_search_v14_7.png b/doc/user/group/epics/img/epics_search_v14_7.png Binary files differnew file mode 100644 index 00000000000..baed532c736 --- /dev/null +++ b/doc/user/group/epics/img/epics_search_v14_7.png diff --git a/doc/user/group/epics/img/epics_sort.png b/doc/user/group/epics/img/epics_sort.png Binary files differdeleted file mode 100644 index b23c65fd0ef..00000000000 --- a/doc/user/group/epics/img/epics_sort.png +++ /dev/null diff --git a/doc/user/group/epics/img/epics_sort_14_7.png b/doc/user/group/epics/img/epics_sort_14_7.png Binary files differnew file mode 100644 index 00000000000..df84dccd06c --- /dev/null +++ b/doc/user/group/epics/img/epics_sort_14_7.png diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index 3889398e2f8..d6f87a026b8 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -8,10 +8,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > Single-level epics were [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) from GitLab Ultimate to GitLab Premium in 12.8. -INFO: -Check out [multi-level child epics](manage_epics.md#multi-level-child-epics) with a -[free 30-day trial of GitLab Ultimate](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-epics-docs). - When [issues](../../project/issues/index.md) share a theme across projects and milestones, you can manage them by using epics. diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index f5b1a2a6ee6..caca10a05a2 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -163,6 +163,8 @@ than 1000. The cached value is rounded to thousands or millions and updated ever > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) from GitLab Ultimate to GitLab Premium in 12.8. > - Searching by the user's reaction emoji [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325630) in GitLab 13.11. > - Sorting by epic titles [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331625) in GitLab 14.1. +> - Searching by milestone and confidentiality [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/268372) in GitLab 14.2 [with a flag](../../../administration/feature_flags.md) named `vue_epics_list`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/276189) in GitLab 14.7. You can search for an epic from the list of epics using filtered search bar based on following parameters: @@ -170,9 +172,11 @@ parameters: - Title or description - Author name / username - Labels +- Milestones +- Confidentiality - Reaction emoji - + To search: @@ -184,8 +188,6 @@ To search: You can also sort epics list by: -- Created date -- Last updated - Start date - Due date - Title @@ -194,7 +196,7 @@ Each option contains a button that can toggle the order between **Ascending** an The sort option and order is saved and used wherever you browse epics, including the [Roadmap](../roadmap/index.md). - + ## Change activity sort order diff --git a/doc/user/group/img/group_code_coverage_analytics_v13_9.png b/doc/user/group/img/group_code_coverage_analytics_v13_9.png Binary files differdeleted file mode 100644 index 8cd71396381..00000000000 --- a/doc/user/group/img/group_code_coverage_analytics_v13_9.png +++ /dev/null diff --git a/doc/user/group/index.md b/doc/user/group/index.md index db6ed02f405..8aa9b8e799d 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -1,7 +1,7 @@ --- type: reference, howto stage: Manage -group: Access +group: Authentication & Authorization 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 --- @@ -100,6 +100,14 @@ You can give a user access to all projects in a group. 1. Fill in the fields. - The role applies to all projects in the group. [Learn more about permissions](../permissions.md). - On the **Access expiration date**, the user can no longer access projects in the group. +1. Select **Invite**. + +Members that are not automatically added are displayed on the **Invited** tab. +Users can be on this tab because they: + +- Have not yet accepted the invitation. +- Are waiting for [approval from an administrator](../admin_area/moderate_users.md). +- [Exceed the group user cap](#user-cap-for-groups). ## Request access to a group @@ -123,7 +131,7 @@ your group. 1. Select **Your Groups**. 1. Find the group and select it. 1. From the left menu, select **Settings > General**. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Clear the **Allow users to request access** checkbox. 1. Select **Save changes**. @@ -219,7 +227,7 @@ To change this setting for a specific group: 1. Select **Your Groups**. 1. Find the group and select it. 1. From the left menu, select **Settings > General**. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Select the desired option in the **Default branch protection** dropdown list. 1. Select **Save changes**. @@ -250,7 +258,7 @@ To change this setting for a specific group: 1. Select **Your Groups**. 1. Find the group and select it. 1. From the left menu, select **Settings > General**. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Select the desired option in the **Allowed to create projects** dropdown list. 1. Select **Save changes**. @@ -489,7 +497,7 @@ If you select this setting in the **Animals** group: To prevent sharing outside of the group's hierarchy: 1. Go to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Select **Prevent members from sending invitations to groups outside of `<group_name>` and its subgroups**. 1. Select **Save changes**. @@ -501,13 +509,81 @@ a project with another group](../project/members/share_project_with_groups.md) t To prevent a project from being shared with other groups: 1. Go to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Select **Prevent sharing a project within `<group_name>` with other groups**. 1. Select **Save changes**. This setting applies to all subgroups unless overridden by a group owner. Groups already added to a project lose access when the setting is enabled. +## User cap for groups + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330027) in GitLab 14.7. + +FLAG: +On self-managed GitLab, this feature is not available. On GitLab.com, this feature is available for some groups. +This feature is not ready for production use. + +When the number of billable members reaches the user cap, new users can't be added to the group +without being approved by the group owner. + +Groups with the user cap feature enabled have [group sharing](#share-a-group-with-another-group) +disabled for the group and its subgroups. + +### Specify a user cap for a group + +Prerequisite: + +- You must be assigned the [Owner role](../permissions.md#group-members-permissions) for the group. + +To specify a user cap: + +1. On the top bar, select **Menu > Groups** and find your group. + You can set a cap on the top-level group only. +1. On the left sidebar, select **Settings > General**. +1. Expand **Permissions and group features**. +1. In the **User cap** box, enter the desired number of users. +1. Select **Save changes**. + +If you already have more users in the group than the user cap value, users +are not removed. However, you can't add more without approval. + +Increasing the user cap does not approve pending members. + +### Remove the user cap for a group + +You can remove the user cap, so there is no limit on the number of members you can add to a group. + +Prerequisite: + +- You must be assigned the [Owner role](../permissions.md#group-members-permissions) for the group. + +To remove the user cap: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand **Permissions and group features**. +1. In the **User cap** box, delete the value. +1. Select **Save changes**. + +Decreasing the user cap does not approve pending members. + +### Approve pending members for a group + +When the number of billable users reaches the user cap, any new member is put in a pending state +and must be approved. + +Prerequisite: + +- You must be assigned the [Owner role](../permissions.md#group-members-permissions) for the group. + +To approve members that are pending because they've exceeded the user cap: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > Usage Quotas**. +1. On the **Seats** tab, under the alert, select **View pending approvals**. +1. For each member you want to approve, select **Approve**. + ## Prevent members from being added to projects in a group **(PREMIUM)** As a group owner, you can prevent any new project membership for all @@ -523,7 +599,7 @@ The setting does not cascade. Projects in subgroups observe the subgroup configu To prevent members from being added to projects in a group: 1. Go to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Under **Member lock**, select **Prevent adding new members to project membership within this group**. 1. Select **Save changes**. @@ -535,9 +611,9 @@ API requests to add a new user to a project are not possible. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/287940) in GitLab 14.2. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/336520) in GitLab 14.5. -You can export a list of members in a group as a CSV. +You can export a list of members in a group or subgroup as a CSV. -1. Go to your project and select **Project information > Members**. +1. Go to your group or subgroup and select either **Group information > Members** or **Subgroup information > Members**. 1. Select **Export as CSV**. 1. Once the CSV file has been generated, it is emailed as an attachment to the user that requested it. @@ -574,7 +650,7 @@ You should consider these security implications before configuring IP address re To restrict group access by IP address: 1. Go to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. In the **Allow access to the following IP addresses** field, enter IP address ranges in CIDR notation. 1. Select **Save changes**. @@ -591,13 +667,15 @@ You can prevent users with email addresses in specific domains from being added To restrict group access by domain: 1. Go to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. In the **Restrict membership by email** field, enter the domain names. 1. Select **Save changes**.  -Any time you attempt to add a new user, they are compared against this list. +Any time you attempt to add a new user, the user's [primary email](../profile/index.md#change-your-primary-email) is compared against this list. +Only users with a [primary email](../profile/index.md#change-your-primary-email) that matches any of the configured email domain restrictions +can be added to the group. Some domains cannot be restricted. These are the most popular public email domains, such as: @@ -645,7 +723,7 @@ You can disable all email notifications related to the group, which includes its To disable email notifications: 1. Go to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Select **Disable email notifications**. 1. Select **Save changes**. @@ -663,7 +741,7 @@ This is particularly helpful for groups with a large number of users. To disable group mentions: 1. Go to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Select **Disable group mentions**. 1. Select **Save changes**. @@ -688,7 +766,7 @@ the default setting. To enable delayed deletion of projects in a group: 1. Go to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Check **Enable delayed project deletion**. 1. Optional. To prevent subgroups from changing this setting, select **Enforce for all subgroups**. 1. Select **Save changes**. @@ -713,7 +791,7 @@ If even one is set to `true`, then the group does not allow outside forks. To prevent projects from being forked outside the group: 1. Go to the top-level group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Check **Prevent project forking outside current group**. 1. Select **Save changes**. @@ -774,7 +852,7 @@ To view the merge request approval rules for a group: - [Webhooks](../project/integrations/webhooks.md). - [Kubernetes cluster integration](clusters/index.md). - [Audit Events](../../administration/audit_events.md#group-events). -- [Pipelines quota](../admin_area/settings/continuous_integration.md): Keep track of the pipeline quota for the group. +- [CI/CD minutes quota](../../ci/pipelines/cicd_minutes.md): Keep track of the CI/CD minute quota for the group. - [Integrations](../admin_area/settings/project_integration_management.md). - [Transfer a project into a group](../project/settings/index.md#transferring-an-existing-project-into-another-namespace). - [Share a project with a group](../project/members/share_project_with_groups.md): Give all group members access to the project at once. diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index ac5df6b052f..62337dabcc0 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -5,15 +5,18 @@ group: Project Management 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 --- -# Issue Analytics **(PREMIUM)** +# Issue analytics for groups **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7478) in GitLab 11.5. -Issue Analytics is a bar graph which illustrates the number of issues created each month. +Issue analytics is a bar graph which illustrates the number of issues created each month. The default time span is 13 months, which includes the current month, and the 12 months prior. -To access the chart, navigate to your group sidebar and select **{chart}** **Analytics > Issue Analytics**. +To access the chart: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Analytics > Issue Analytics**. Hover over each bar to see the total number of issues. diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index c6cd763355b..2487ab188e8 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -5,11 +5,15 @@ group: Testing 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 --- -# Repositories Analytics **(PREMIUM)** +# Repositories analytics for groups **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215104) in GitLab 13.4. - +Repositories analytics for groups provides information about test coverage for all projects in a group. An +[issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/273527) to also extend support for all projects in +subgroups. + +It is similar to [repository analytics for projects](../../analytics/repository_analytics.md). ## Current group code coverage diff --git a/doc/user/group/saml_sso/group_managed_accounts.md b/doc/user/group/saml_sso/group_managed_accounts.md index d62b569a795..06e666f4d24 100644 --- a/doc/user/group/saml_sso/group_managed_accounts.md +++ b/doc/user/group/saml_sso/group_managed_accounts.md @@ -1,7 +1,7 @@ --- type: reference, howto stage: Manage -group: Access +group: Authentication & Authorization 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 --- @@ -113,7 +113,7 @@ on the lifetime of personal access tokens apply. To set a limit on how long personal access tokens are valid for users in a group managed account: 1. Navigate to the **Settings > General** page in your group's sidebar. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Fill in the **Maximum allowable lifetime for personal access tokens (days)** field. 1. Click **Save changes**. diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 7443be250bb..20ff4a201f5 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -1,7 +1,7 @@ --- type: reference, howto stage: Manage -group: Access +group: Authentication & Authorization 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 --- @@ -14,10 +14,6 @@ This page describes SAML for groups. For instance-wide SAML on self-managed GitL SAML on GitLab.com allows users to sign in through their SAML identity provider. If the user is not already a member, the sign-in process automatically adds the user to the appropriate group. -INFO: -Use your own SAML authentication to log in to [GitLab.com](http://gitlab.com/). -[Try GitLab Ultimate free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-saml-sso-docs). - User synchronization of SAML SSO groups is supported through [SCIM](scim_setup.md). SCIM supports adding and removing users from the GitLab group automatically. For example, if you remove a user from the SCIM app, SCIM removes that same user from the GitLab group. @@ -72,10 +68,10 @@ To create users with the correct information for improved [user access and manag the user's details must be passed to GitLab as attributes in the SAML assertion. At a minimum, the user's email address must be specified as an attribute named `email` or `mail`. -GitLab.com supports the following attributes: +You can configure the following attributes with GitLab.com Group SAML: - `username` or `nickname`. We recommend you configure only one of these. -- The [attributes also available](../../../integration/saml.md#assertions) to self-managed GitLab instances. +- The [attributes available](../../../integration/saml.md#assertions) to self-managed GitLab instances. ### Metadata configuration @@ -110,6 +106,7 @@ The certificate [fingerprint algorithm](../../../integration/saml.md#notes-on-co > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/292811) in GitLab 13.8, with an updated timeout experience. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/211962) in GitLab 13.8 with allowing group owners to not go through SSO. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/9152) in GitLab 13.11 with enforcing open SSO session to use Git if this setting is switched on. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/339888) in GitLab 14.7 to not enforce SSO checks for Git activity originating from CI/CD jobs. With this option enabled, users (except users with the Owner role) must access GitLab using your group GitLab single sign-on URL to access group resources. Users added manually as members can't access group resources. @@ -127,6 +124,7 @@ SSO has the following effects when enabled: even if the project is forked. - For Git activity over SSH and HTTPS, users must have at least one active session signed-in through SSO before they can push to or pull from a GitLab repository. +- Git activity originating from CI/CD jobs do not have the SSO check enforced. - Credentials that are not tied to regular users (for example, access tokens and deploy keys) do not have the SSO check enforced. - Users must be signed-in through SSO before they can pull images using the [Dependency Proxy](../../packages/dependency_proxy/index.md). <!-- Add bullet for API activity when https://gitlab.com/gitlab-org/gitlab/-/issues/9152 is complete --> @@ -137,8 +135,6 @@ When SSO is enforced, users are not immediately revoked. If the user: - Has an active session, they can continue accessing the group for up to 24 hours until the identity provider session times out. -When SCIM updates, the user's access is immediately revoked. - ## Providers The SAML standard means that you can use a wide range of identity providers with GitLab. Your identity provider might have relevant documentation. It can be generic SAML documentation or specifically targeted for GitLab. @@ -167,10 +163,11 @@ objectID mapping and the [SCIM documentation should be followed](scim_setup.md#a | Identity provider single sign-on URL | Login URL | | Certificate fingerprint | Thumbprint | -We recommend: +The recommended attributes and claims settings are: - **Unique User Identifier (Name identifier)** set to `user.objectID`. - **nameid-format** set to persistent. +- Additional claims set to [supported attributes](#user-attributes). If using [Group Sync](#group-sync), customize the name of the group claim to match the required attribute. @@ -304,7 +301,14 @@ If a user is already a member of the group, linking the SAML identity does not c ### Blocking access -Please refer to [Blocking access via SCIM](scim_setup.md#blocking-access). +To rescind a user's access to the group when only SAML SSO is configured, either: + +- Remove (in order) the user from: + 1. The user data store on the identity provider or the list of users on the specific app. + 1. The GitLab.com group. +- Use Group Sync at the top-level of your group to [automatically remove the user](#automatic-member-removal). + +To rescind a user's access to the group when also using SCIM, refer to [Blocking access](scim_setup.md#blocking-access). ### Unlinking accounts @@ -349,6 +353,10 @@ Ensure your SAML identity provider sends an attribute statement named `Groups` o </saml:AttributeStatement> ``` +WARNING: +Setting up Group Sync can disconnect users from SAML IDP if there is any mismatch in the configuration. Ensure the +`Groups` attribute is included in the SAML response, and the **SAML Group Name** matches the `AttributeValue` attribute. + Other attribute names such as `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups` are not accepted as a source of groups. See the [SAML troubleshooting page](../../../administration/troubleshooting/group_saml_scim.md) diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 2651bcb9e12..d7d663f4115 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -1,7 +1,7 @@ --- type: howto, reference stage: Manage -group: Access +group: Authentication & Authorization 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 --- @@ -184,8 +184,7 @@ For role information, please see the [Group SAML page](index.md#user-access-and- ### Blocking access To rescind access to the top-level group, all sub-groups, and projects, remove or deactivate the user -on the identity provider. SCIM providers generally update GitLab with the changes on demand, which -is minutes at most. The user's membership is revoked and they immediately lose access. +on the identity provider. After the identity provider performs a sync, based on its configured schedule, the user's membership is revoked and they lose access. NOTE: Deprovisioning does not delete the GitLab user account. diff --git a/doc/user/group/settings/group_access_tokens.md b/doc/user/group/settings/group_access_tokens.md new file mode 100644 index 00000000000..816edb629f5 --- /dev/null +++ b/doc/user/group/settings/group_access_tokens.md @@ -0,0 +1,147 @@ +--- +stage: Manage +group: Authentication & Authorization +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" +type: reference, howto +--- + +# Group access tokens + +With group access tokens, you can use a single token to: + +- Perform actions for groups. +- Manage the projects within the group. + +You can use a group access token to authenticate: + +- With the [GitLab API](../../../api/index.md#personalprojectgroup-access-tokens). +- In [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/330718) and later, authenticate with Git over HTTPS. + +After you configure a group access token, you don't need a password when you authenticate. +Instead, you can enter any non-blank value. + +Group access tokens are similar to [project access tokens](../../project/settings/project_access_tokens.md) +and [personal access tokens](../../profile/personal_access_tokens.md), except they are +associated with a group rather than a project or user. + +You can use group access tokens: + +- On GitLab SaaS if you have the Premium license tier or higher. Group access tokens are not available with a [trial license](https://about.gitlab.com/free-trial/). +- On self-managed instances of GitLab, with any license tier. If you have the Free tier: + - Review your security and compliance policies around + [user self-enrollment](../../admin_area/settings/sign_up_restrictions.md#disable-new-sign-ups). + - Consider [disabling group access tokens](#enable-or-disable-group-access-token-creation) to + lower potential abuse. + +Group access tokens inherit the [default prefix setting](../../admin_area/settings/account_and_limit_settings.md#personal-access-token-prefix) +configured for personal access tokens. + +## Create a group access token using UI + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214045) in GitLab 14.7. + +To create a group access token: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > Access Tokens**. +1. Enter a name. +1. Optional. Enter an expiry date for the token. The token will expire on that date at midnight UTC. +1. Select a role for the token. +1. Select the [desired scopes](#scopes-for-a-group-access-token). +1. Select **Create group access token**. + +A group access token is displayed. Save the group access token somewhere safe. After you leave or refresh the page, you can't view it again. + +## Create a group access token using Rails console + +GitLab 14.6 and earlier doesn't support creating group access tokens using the UI +or API. However, administrators can use a workaround: + +1. Run the following commands in a [Rails console](../../../administration/operations/rails_console.md): + + ```ruby + # Set the GitLab administration user to use. If user ID 1 is not available or is not an administrator, use 'admin = User.admins.first' instead to select an administrator. + admin = User.find(1) + + # Set the group group you want to create a token for. For example, group with ID 109. + group = Group.find(109) + + # Create the group bot user. For further group access tokens, the username should be group_#{group.id}_bot#{bot_count}. For example, group_109_bot2 and email address group_109_bot2@example.com. + bot = Users::CreateService.new(admin, { name: 'group_token', username: "group_#{group.id}_bot", email: "group_#{group.id}_bot@example.com", user_type: :project_bot }).execute + + # Confirm the group bot. + bot.confirm + + # Add the bot to the group with the required role. + group.add_user(bot, :maintainer) + + # Give the bot a personal access token. + token = bot.personal_access_tokens.create(scopes:[:api, :write_repository], name: 'group_token') + + # Get the token value. + gtoken = token.token + ``` + +1. Test if the generated group access token works: + + 1. Use the group access token in the `PRIVATE-TOKEN` header with GitLab REST APIs. For example: + + - [Create an epic](../../../api/epics.md#new-epic) in the group. + - [Create a project pipeline](../../../api/pipelines.md#create-a-new-pipeline) in one of the group's projects. + - [Create an issue](../../../api/issues.md#new-issue) in one of the group's projects. + + 1. Use the group token to [clone a group's project](../../../gitlab-basics/start-using-git.md#clone-with-https) + using HTTPS. + +## Revoke a group access token using the UI + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214045) in GitLab 14.7. + +To revoke a group access token: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > Access Tokens**. +1. Next to the group access token to revoke, select **Revoke**. + +## Revoke a group access token using Rails console + +GitLab 14.6 and earlier doesn't support revoking group access tokens using the UI +or API. However, administrators can use a workaround. + +To revoke a group access token, run the following command in a [Rails console](../../../administration/operations/rails_console.md): + +```ruby +bot = User.find_by(username: 'group_109_bot') # the owner of the token you want to revoke +token = bot.personal_access_tokens.last # the token you want to revoke +token.revoke! +``` + +## Scopes for a group access token + +The scope determines the actions you can perform when you authenticate with a group access token. + +| Scope | Description | +|:-------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `api` | Grants complete read and write access to the scoped group and related project API, including the [Package Registry](../../packages/package_registry/index.md). | +| `read_api` | Grants read access to the scoped group and related project API, including the [Package Registry](../../packages/package_registry/index.md). | +| `read_registry` | Allows read access (pull) to the [Container Registry](../../packages/container_registry/index.md) images if any project within a group is private and authorization is required. | +| `write_registry` | Allows write access (push) to the [Container Registry](../../packages/container_registry/index.md). | +| `read_repository` | Allows read access (pull) to all repositories within a group. | +| `write_repository` | Allows read and write access (pull and push) to all repositories within a group. | + +## Enable or disable group access token creation + +To enable or disable group access token creation for all sub-groups in a top-level group: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand **Permissions and group features**. +1. Under **Permissions**, turn on or off **Allow project and group access token creation**. + +Even when creation is disabled, you can still use and revoke existing group access tokens. + +## Bot users + +Each time you create a group access token, a bot user is created and added to the group. +These bot users are similar to [project bot users](../../project/settings/project_access_tokens.md#project-bot-users), but are added to groups instead of projects. For more information, see +[Project bot users](../../project/settings/project_access_tokens.md#project-bot-users). diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index acce296da93..ef984a76a7d 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization 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 type: reference, howto, concepts --- @@ -101,7 +101,7 @@ You can change this setting: - As group owner: 1. Select the group. 1. On the left sidebar, select **Settings > General**. - 1. Expand **Permissions, LFS, 2FA**. + 1. Expand **Permissions and group features**. - As an administrator: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Groups**. diff --git a/doc/user/group/value_stream_analytics/img/vsa_stage_table_v13_12.png b/doc/user/group/value_stream_analytics/img/vsa_stage_table_v13_12.png Binary files differdeleted file mode 100644 index 24d485306be..00000000000 --- a/doc/user/group/value_stream_analytics/img/vsa_stage_table_v13_12.png +++ /dev/null diff --git a/doc/user/group/value_stream_analytics/img/vsa_stage_table_v14_7.png b/doc/user/group/value_stream_analytics/img/vsa_stage_table_v14_7.png Binary files differnew file mode 100644 index 00000000000..c9074cbb5ea --- /dev/null +++ b/doc/user/group/value_stream_analytics/img/vsa_stage_table_v14_7.png diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index b91e258b04a..4663cfc8bfd 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -5,34 +5,35 @@ group: Optimize 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 --- -# Value Stream Analytics **(PREMIUM)** +# Value stream analytics for groups **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196455) in GitLab 12.9 for groups. -Value Stream Analytics measures the time spent to go from an +Value stream analytics measures the time spent to go from an [idea to production](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab) -(also known as cycle time) for each of your projects or groups. Value Stream Analytics displays the median time +(also known as cycle time) for each of your projects or groups. Value stream analytics displays the median time spent in each stage defined in the process. -Value Stream Analytics can help you quickly determine the velocity of a given +Value stream analytics can help you quickly determine the velocity of a given group. It points to bottlenecks in the development process, enabling management to uncover, triage, and identify the root cause of slowdowns in the software development life cycle. -For information on how to contribute to the development of Value Stream Analytics, see our [contributor documentation](../../../development/value_stream_analytics.md). +For information on how to contribute to the development of value stream analytics, see our [contributor documentation](../../../development/value_stream_analytics.md). -To view group-level Value Stream Analytics: +To view value stream analytics for groups: 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Value stream**. -Value Stream Analytics at the group level includes data for the selected group and its subgroups. +Value stream analytics at the group level includes data for the selected group and its subgroups. NOTE: -[Project-level Value Stream Analytics](../../analytics/value_stream_analytics.md) is also available. +[Value stream analytics for projects](../../analytics/value_stream_analytics.md) is also available. ## Default stages -The stages tracked by Value Stream Analytics by default represent the [GitLab flow](../../../topics/gitlab_flow.md). These stages can be customized in Group Level Value Stream Analytics. +The stages tracked by value stream analytics by default represent the [GitLab flow](../../../topics/gitlab_flow.md). +These stages can be customized in value stream analytics for groups. - **Issue** (Tracker) - Time to schedule an issue (by milestone or by adding it to an issue board) @@ -100,8 +101,7 @@ sole discretion of GitLab Inc. ## How metrics are measured -> DORA API-based deployment metrics for group-level Value Stream Analytics were -> [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/337256) from GitLab Ultimate to GitLab Premium in 14.3. +> DORA API-based deployment metrics for value stream analytics for groups were [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/337256) from GitLab Ultimate to GitLab Premium in 14.3. The "Time" metrics near the top of the page are measured as follows: @@ -134,11 +134,11 @@ You can learn more about these metrics in our [analytics definitions](../../anal ## How the stages are measured -Value Stream Analytics measures each stage from its start event to its end event. +Value stream analytics measures each stage from its start event to its end event. For example, a stage might start when one label is added to an issue, and end when another label is added. -Value Stream Analytics excludes work in progress, meaning it ignores any items that have not reached the end event. +Value stream analytics excludes work in progress, meaning it ignores any items that have not reached the end event. -Each stage of Value Stream Analytics is further described in the table below. +Each stage of value stream analytics is further described in the table below. | **Stage** | **Description** | | --------- | --------------- | @@ -162,7 +162,7 @@ How this works, behind the scenes: and so on. To sum up, anything that doesn't follow [GitLab flow](../../../topics/gitlab_flow.md) is not tracked and the -Value Stream Analytics dashboard does not present any data for: +value stream analytics dashboard does not present any data for: - Merge requests that do not close an issue. - Issues not labeled with a label present in the issue board or for issues not assigned a milestone. @@ -170,7 +170,7 @@ Value Stream Analytics dashboard does not present any data for: ## How the production environment is identified -Value Stream Analytics identifies production environments by looking for project +Value stream analytics identifies production environments by looking for project [environments](../../../ci/yaml/index.md#environment) with a name matching any of these patterns: - `prod` or `prod/*` @@ -228,7 +228,7 @@ A few notes: tested). - The example above was just **one cycle** of the seven stages. Add multiple cycles, calculate their median time and the result is what the dashboard of - Value Stream Analytics is showing. + value stream analytics is showing. ## Custom value streams @@ -236,7 +236,7 @@ A few notes: The default stages are designed to work straight out of the box, but they might not be suitable for all teams. Different teams use different approaches to building software, so some teams might want -to customize their Value Stream Analytics. +to customize their value stream analytics. GitLab allows users to create multiple value streams, hide default stages and create custom stages that align better to their development workflow. @@ -272,7 +272,7 @@ Hovering over a stage item displays a popover with the following information: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321438) in GitLab 13.11. - + The stream overview provides access to key metrics and charts summarizing all the stages in the value stream based on selected filters. @@ -288,7 +288,7 @@ Shown metrics and charts includes: > Sorting the stage table [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301082) in GitLab 13.12. - + The stage table shows a list of related workflow items for the selected stage. This can include: @@ -378,7 +378,7 @@ In this example, we'd like to measure times for deployment from a staging enviro - When the code is deployed to staging, the `workflow::staging` label is added to the merge request. - When the code is deployed to production, the `workflow::production` label is added to the merge request. - + ### Editing a value stream @@ -443,14 +443,14 @@ select up to a total of 15 labels. ## Permissions -To access Group-level Value Stream Analytics, users must have at least the Reporter role. +To access value stream analytics for groups, users must have at least the Reporter role. You can [read more about permissions](../../permissions.md) in general. ## More resources -Learn more about Value Stream Analytics in the following resources: +Learn more about value stream analytics in the following resources: -- [Value Stream Analytics feature page](https://about.gitlab.com/stages-devops-lifecycle/value-stream-analytics/). -- [Value Stream Analytics feature preview](https://about.gitlab.com/blog/2016/09/16/feature-preview-introducing-cycle-analytics/). -- [Value Stream Analytics feature highlight](https://about.gitlab.com/blog/2016/09/21/cycle-analytics-feature-highlight/). +- [Value stream analytics feature page](https://about.gitlab.com/stages-devops-lifecycle/value-stream-analytics/). +- [Value stream analytics feature preview](https://about.gitlab.com/blog/2016/09/16/feature-preview-introducing-cycle-analytics/). +- [Value stream analytics feature highlight](https://about.gitlab.com/blog/2016/09/21/cycle-analytics-feature-highlight/). |
