diff options
Diffstat (limited to 'doc/user/group')
46 files changed, 733 insertions, 231 deletions
diff --git a/doc/user/group/bulk_editing/index.md b/doc/user/group/bulk_editing/index.md index ec1e81bac2d..8db9c7fd76c 100644 --- a/doc/user/group/bulk_editing/index.md +++ b/doc/user/group/bulk_editing/index.md @@ -1,19 +1,19 @@ --- stage: Plan 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/#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 --- # Bulk editing issues, epics, and merge requests at the group level **(PREMIUM)** -NOTE: **Note:** +NOTE: Bulk editing issues and merge requests is also available at the **project level**. For more details, see [Bulk editing issues and merge requests at the project level](../../project/bulk_editing.md). If you want to update attributes across multiple issues, epics, or merge requests in a group, you can do it by bulk editing them, that is, editing them together. -NOTE: **Note:** +NOTE: Only the items visible on the current page are selected for bulk editing (up to 20).  @@ -22,7 +22,7 @@ Only the items visible on the current page are selected for bulk editing (up to > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7249) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1. -NOTE: **Note:** +NOTE: You need a permission level of [Reporter or higher](../../permissions.md) to manage issues. When bulk editing issues in a group, you can edit the following attributes: @@ -46,7 +46,7 @@ To update multiple project issues at the same time: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7250) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. -NOTE: **Note:** +NOTE: You need a permission level of [Reporter or higher](../../permissions.md) to manage epics. When bulk editing epics in a group, you can edit their labels. @@ -63,7 +63,7 @@ To update multiple epics at the same time: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12719) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. -NOTE: **Note:** +NOTE: You need a permission level of [Developer or higher](../../permissions.md) to manage merge requests. When bulk editing merge requests in a group, you can edit the following attributes: diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 1a62d67e468..ea7629d1f10 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -2,7 +2,7 @@ type: reference stage: Configure group: Configure -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 --- # Group-level Kubernetes clusters @@ -58,11 +58,11 @@ differentiate the new cluster from your other clusters. > - Became [optional](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26565) in GitLab 11.11. You can choose to allow GitLab to manage your cluster for you. If GitLab manages -your cluster, resources for your projects will be automatically created. See the +your cluster, resources for your projects are automatically created. See the [Access controls](../../project/clusters/add_remove_clusters.md#access-controls) section for details on which resources GitLab creates for you. -For clusters not managed by GitLab, project-specific resources won't be created +For clusters not managed by GitLab, project-specific resources aren't created automatically. If you're using [Auto DevOps](../../../topics/autodevops/index.md) for deployments with a cluster not managed by GitLab, you must ensure: @@ -97,7 +97,7 @@ To clear the cache: Domains at the cluster level permit support for multiple domains per [multiple Kubernetes clusters](#multiple-kubernetes-clusters) When specifying a domain, -this will be automatically set as an environment variable (`KUBE_INGRESS_BASE_DOMAIN`) during +this is automatically set as an environment variable (`KUBE_INGRESS_BASE_DOMAIN`) during the [Auto DevOps](../../../topics/autodevops/index.md) stages. The domain should have a wildcard DNS configured to the Ingress IP address. diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index cf55a1f688b..0dbd7af1214 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -1,8 +1,8 @@ --- type: reference stage: Manage -group: Value Stream 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/#designated-technical-writers +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/#assignments --- # Contribution Analytics **(STARTER)** diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index bbff82811bf..a59b1f2e9b2 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -2,7 +2,7 @@ type: reference stage: Manage group: Import -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 --- # Custom group-level project templates **(PREMIUM)** @@ -20,7 +20,7 @@ To use a custom project template for a new project you need to: 1. Edit your group's settings to look to your 'templates' subgroup for templates: 1. In the left-hand menu, click **{settings}** **Settings > General**. - NOTE: **Note:** + NOTE: If you don't have access to the group's settings, you may not have sufficient privileges (for example, you may need developer or higher permissions). 1. Scroll to **Custom project templates** and click **Expand**. If no **Custom project templates** section displays, make sure you've created a subgroup, and added a project (repository) to it. @@ -56,7 +56,7 @@ gitlab.com/acmeco/ Users can configure a GitLab group that serves as template source under a group's **Settings > General > Custom project templates**. -NOTE: **Note:** +NOTE: GitLab administrators can [set project templates for an entire GitLab instance](../admin_area/custom_project_templates.md). @@ -66,11 +66,11 @@ available to every signed-in user, if all enabled [project features](../project/ However, private projects will be available only if the user is a member of the project. -NOTE: **Note:** +NOTE: Only direct subgroups can be set as the template source. Projects of nested subgroups of a selected template source cannot be used. Repository and database information that are copied over to each new project are -identical to the data exported with [GitLab's Project Import/Export](../project/settings/import_export.md). +identical to the data exported with the [GitLab Project Import/Export](../project/settings/import_export.md). <!-- ## Troubleshooting diff --git a/doc/user/group/dependency_proxy/index.md b/doc/user/group/dependency_proxy/index.md index f735ec0214f..c4feed24132 100644 --- a/doc/user/group/dependency_proxy/index.md +++ b/doc/user/group/dependency_proxy/index.md @@ -3,3 +3,6 @@ redirect_to: '../../packages/dependency_proxy/index.md' --- This document was moved to [another location](../../packages/dependency_proxy/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/group/epics/img/new_epic_form_v13.2.png b/doc/user/group/epics/img/new_epic_form_v13.2.png Binary files differdeleted file mode 100644 index ac1450ae111..00000000000 --- a/doc/user/group/epics/img/new_epic_form_v13.2.png +++ /dev/null diff --git a/doc/user/group/epics/img/new_epic_from_groups_v13.2.png b/doc/user/group/epics/img/new_epic_from_groups_v13.2.png Binary files differdeleted file mode 100644 index bb75605af60..00000000000 --- a/doc/user/group/epics/img/new_epic_from_groups_v13.2.png +++ /dev/null diff --git a/doc/user/group/epics/img/new_epic_from_groups_v13.7.png b/doc/user/group/epics/img/new_epic_from_groups_v13.7.png Binary files differnew file mode 100644 index 00000000000..3607d5c7a3f --- /dev/null +++ b/doc/user/group/epics/img/new_epic_from_groups_v13.7.png diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index e98c4b416fe..c76b07481b2 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Plan group: Product Planning -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 --- # Epics **(PREMIUM)** @@ -10,20 +10,24 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.2. > - Single-level Epics [were moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to [GitLab Premium](https://about.gitlab.com/pricing/) in 12.8. -Epics let you manage your portfolio of projects more efficiently by tracking groups of issues that -share a theme across projects and milestones. +Epics let you manage your portfolio of projects more efficiently by tracking groups of [issues](../../project/issues/index.md) +that share a theme across projects and milestones. An epic's page contains the following tabs: -- **Epics and Issues**: epics and issues added to this epic. Child epics, and their issues, are - shown in a tree view. - - Click the chevron (**>**) next to a parent epic to reveal the child epics and issues. - - Hover over the total counts to see a breakdown of open and closed items. +- **Issues**: issues added to this epic. +- **Epics and Issues**: epics and issues added to this epic. + Appears instead of the **Issues** tab if you have access to [multi-level epics](#multi-level-child-epics). + Child epics and their issues are shown in a tree view. - NOTE: **Note:** - The number provided here includes all epics associated with this project. The number includes epics for which users may not yet have permission. + - To reveal the child epics and issues, select the chevron (**>**) next to a parent epic. + - To see a breakdown of open and closed items, hover over the total counts. -- **Roadmap**: a roadmap view of child epics which have start and due dates. + The number provided here includes all epics associated with this project. The number includes + epics for which users may not yet have permission. + +- [**Roadmap**](#roadmap-in-epics): a roadmap view of child epics which have start and due dates. + Appears if you have access to [multi-level epics](#multi-level-child-epics).  @@ -75,14 +79,10 @@ to: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199184) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. > - The health status of a closed issue [is hidden](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3 or later. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/213567) in GitLab 13.7. Report or respond to the health of issues and epics by setting a red, amber, or green [health status](../../project/issues/index.md#health-status), which then appears on your Epic tree. -### Disable Issue health status in Epic tree - -This feature comes with a feature flag enabled by default. For steps to disable it, see -[Disable issue health status](../../project/issues/index.md#disable-issue-health-status). - ## Multi-level child epics **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8333) in GitLab Ultimate 11.7. @@ -92,7 +92,7 @@ New child epics appear at the top of the list of epics in the **Epics and Issues When you add an epic that's already linked to a parent epic, the link to its current parent is removed. -An epic can have multiple child epics up to the maximum depth of five. +An epic can have multiple child epics up to the maximum depth of seven. See [Manage multi-level child epics](manage_epics.md#manage-multi-level-child-epics) for steps to create, move, reorder, or delete child epics. @@ -101,35 +101,18 @@ steps to create, move, reorder, or delete child epics. To set a **Start date** and **Due date** for an epic, select one of the following: -- **Fixed**: Enter a fixed value. -- **From milestones**: Inherit a dynamic value from the milestones that are assigned to the epic's issues. - Note that GitLab 12.5 replaced this option with **Inherited**. -- **Inherited**: Inherit a dynamic value from the epic's issues, child epics, and milestones ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7332) in GitLab 12.5 to replace **From milestones**). - -### From milestones - -> [Replaced](https://gitlab.com/gitlab-org/gitlab/-/issues/7332) in GitLab 12.5 by **Inherited**. - -If you select **From milestones** for the start date, GitLab automatically sets the date to be earliest -start date across all milestones that are assigned to the issues that belong to the epic. -If you select **From milestones** for the due date, GitLab sets the date to be the latest due date across -all milestones that are assigned to those issues. - -These are dynamic dates which are recalculated if any of the following occur: - -- Milestones are re-assigned to the issues. -- Milestone dates change. -- Issues are added or removed from the epic. +- **Fixed**: enter a fixed value. +- **Inherited**: inherit a dynamic value from the epic's issues, child epics, and milestones. ### Inherited > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7332) in GitLab 12.5 to replace **From milestones**. -If you select: +If you select **Inherited**: -- **Inherited** for the start date, GitLab will scan all child epics and issues assigned to the epic, - and will set the start date to match the earliest found start date or milestone. -- **Inherited** for the due date, GitLab will set the due date to match the latest due date or +- For the **start date**: GitLab scans all child epics and issues assigned to the epic, + and sets the start date to match the earliest found start date or milestone. +- For the **due date**: GitLab sets the due date to match the latest due date or milestone found among its child epics and issues. These are dynamic dates and recalculated if any of the following occur: @@ -143,7 +126,7 @@ Because the epic's dates can inherit dates from its children, the start date and If the start date of a child epic on the lowest level changes, that becomes the earliest possible start date for its parent epic. The parent epic's start date then reflects this change and propagates upwards to the top epic. -## Roadmap in epics +## Roadmap in epics **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7327) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.10. diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index 5895b611bb3..9cc7a35bc32 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -2,7 +2,7 @@ type: howto stage: Plan group: Product Planning -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 --- <!-- When adding a new h2 section here, remember to mention it in index.md#manage-epics --> @@ -14,42 +14,28 @@ to them. ## Create an epic -A paginated list of epics is available in each group from where you can create -a new epic. The list of epics includes also epics from all subgroups of the -selected group. From your group page: +> - The New Epic form [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211533) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. +> - In [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/229621) and later, the New Epic button on the Epics list opens the New Epic form. -### Create an epic from the epic list +To create an epic in the group you're in: -To create an epic from the epic list, in a group: +1. Get to the New Epic form: + - From the **Epics** list in your group, select the **New Epic** button. + - From an epic in your group, select the **New Epic** button. + - From anywhere, in the top menu, select **New...** (**{plus-square}**) **> New epic**. -1. Go to **{epic}** **Epics**. -1. Select **New epic**. -1. Enter a descriptive title. -1. Select **Create epic**. +  -### Access the New Epic form +1. Fill in these fields: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211533) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. + - Title + - Description + - [Confidentiality checkbox](#make-an-epic-confidential) + - Labels + - Start date + - Due date -There are two ways to get to the New Epic form and create an epic in the group you're in: - -- From an epic in your group, select **New Epic**. -- From anywhere, in the top menu, select **plus** (**{plus-square}**) **> New epic**. - -  - -### Elements of the New Epic form - -When you're creating a new epic, these are the fields you can fill in: - -- Title -- Description -- Confidentiality checkbox -- Labels -- Start date -- Due date - - +1. Select **Create epic**. You are taken to view the newly created epic. ## Edit an epic @@ -79,7 +65,7 @@ You can edit multiple epics at once. To learn how to do it, visit ## Delete an epic -NOTE: **Note:** +NOTE: To delete an epic, you need to be an [Owner](../../permissions.md#group-members-permissions) of a group/subgroup. When editing the description of an epic, select the **Delete** button to delete the epic. @@ -130,7 +116,7 @@ that of Issues and Merge Requests) based on following parameters:  To search, go to the list of epics and select the field **Search or filter results**. -It will display a dropdown menu, from which you can add an author. You can also enter plain +It displays a dropdown menu, from which you can add an author. You can also enter plain text to search by epic title or description. When done, press <kbd>Enter</kbd> on your keyboard to filter the list. @@ -155,7 +141,7 @@ The sort option and order is saved and used wherever you browse epics, including If you're working on items that contain private information, you can make an epic confidential. -NOTE: **Note:** +NOTE: A confidential epic can only contain confidential issues and confidential child epics. To make an epic confidential: @@ -211,7 +197,7 @@ To create an issue from an epic: ### Remove an issue from an epic You can remove issues from an epic when you're on the epic's details page. -After you remove an issue from an epic, the issue will no longer be associated with this epic. +After you remove an issue from an epic, the issue is no longer associated with this epic. To remove an issue from an epic: @@ -253,8 +239,8 @@ To move an issue to another epic: If you have the necessary [permissions](../../permissions.md) to close an issue and create an epic in the immediate parent group, you can promote an issue to an epic with the `/promote` [quick action](../../project/quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). -Only issues from projects that are in groups can be promoted. When attempting to promote a confidential -issue, a warning will display. Promoting a confidential issue to an epic will make all information +Only issues from projects that are in groups can be promoted. When you attempt to promote a confidential +issue, a warning is displayed. Promoting a confidential issue to an epic makes all information related to the issue public as epics are public to group members. When the quick action is executed: @@ -262,7 +248,7 @@ When the quick action is executed: - An epic is created in the same group as the project of the issue. - Subscribers of the issue are notified that the epic was created. -The following issue metadata will be copied to the epic: +The following issue metadata is copied to the epic: - Title, description, activity/comment thread. - Upvotes/downvotes. @@ -277,7 +263,7 @@ You can create a spreadsheet template to manage a pattern of consistently repeat <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an introduction to epic templates, see [GitLab Epics and Epic Template Tip](https://www.youtube.com/watch?v=D74xKFNw8vg). -For more on epic templates, see [Epic Templates - Repeatable sets of issues](https://about.gitlab.com/handbook/marketing/product-marketing/getting-started/104/). +For more on epic templates, see [Epic Templates - Repeatable sets of issues](https://about.gitlab.com/handbook/marketing/strategic-marketing/getting-started/104/). ## Manage multi-level child epics **(ULTIMATE)** diff --git a/doc/user/group/img/add_new_members_v13_6.png b/doc/user/group/img/add_new_members_v13_6.png Binary files differdeleted file mode 100644 index 4255eeb72c7..00000000000 --- a/doc/user/group/img/add_new_members_v13_6.png +++ /dev/null diff --git a/doc/user/group/img/add_new_members_v13_7.png b/doc/user/group/img/add_new_members_v13_7.png Binary files differnew file mode 100644 index 00000000000..7e06bdf8fd1 --- /dev/null +++ b/doc/user/group/img/add_new_members_v13_7.png diff --git a/doc/user/group/img/group_code_coverage_analytics_v13_7.png b/doc/user/group/img/group_code_coverage_analytics_v13_7.png Binary files differnew file mode 100644 index 00000000000..769953b1355 --- /dev/null +++ b/doc/user/group/img/group_code_coverage_analytics_v13_7.png diff --git a/doc/user/group/img/group_members_filter_2fa_disabled_13_7.png b/doc/user/group/img/group_members_filter_2fa_disabled_13_7.png Binary files differnew file mode 100644 index 00000000000..8336103bad1 --- /dev/null +++ b/doc/user/group/img/group_members_filter_2fa_disabled_13_7.png diff --git a/doc/user/group/img/group_members_filter_2fa_enabled_13_7.png b/doc/user/group/img/group_members_filter_2fa_enabled_13_7.png Binary files differnew file mode 100644 index 00000000000..eb27906b583 --- /dev/null +++ b/doc/user/group/img/group_members_filter_2fa_enabled_13_7.png diff --git a/doc/user/group/img/group_members_filter_direct_13_7.png b/doc/user/group/img/group_members_filter_direct_13_7.png Binary files differnew file mode 100644 index 00000000000..c1b2d996e59 --- /dev/null +++ b/doc/user/group/img/group_members_filter_direct_13_7.png diff --git a/doc/user/group/img/group_members_filter_inherited_13_7.png b/doc/user/group/img/group_members_filter_inherited_13_7.png Binary files differnew file mode 100644 index 00000000000..f75990f9da8 --- /dev/null +++ b/doc/user/group/img/group_members_filter_inherited_13_7.png diff --git a/doc/user/group/img/group_members_search_13_7.png b/doc/user/group/img/group_members_search_13_7.png Binary files differnew file mode 100644 index 00000000000..21f36fc75f8 --- /dev/null +++ b/doc/user/group/img/group_members_search_13_7.png diff --git a/doc/user/group/img/group_members_sort_13_7.png b/doc/user/group/img/group_members_sort_13_7.png Binary files differnew file mode 100644 index 00000000000..5d307da649a --- /dev/null +++ b/doc/user/group/img/group_members_sort_13_7.png diff --git a/doc/user/group/img/group_storage_usage_quota.png b/doc/user/group/img/group_storage_usage_quota.png Binary files differdeleted file mode 100644 index c5d81ad7a8b..00000000000 --- a/doc/user/group/img/group_storage_usage_quota.png +++ /dev/null diff --git a/doc/user/group/img/manual_permissions_v13_6.png b/doc/user/group/img/manual_permissions_v13_6.png Binary files differdeleted file mode 100644 index 6d26061b049..00000000000 --- a/doc/user/group/img/manual_permissions_v13_6.png +++ /dev/null diff --git a/doc/user/group/img/manual_permissions_v13_7.png b/doc/user/group/img/manual_permissions_v13_7.png Binary files differnew file mode 100644 index 00000000000..fcea0121915 --- /dev/null +++ b/doc/user/group/img/manual_permissions_v13_7.png diff --git a/doc/user/group/index.md b/doc/user/group/index.md index e09c685147a..a0884461da1 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Access -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 @@ -130,7 +130,7 @@ give a user access to all projects in the group with one action. Add members to a group by navigating to the group's dashboard and clicking **Members**. - + Select the [permission level](../permissions.md#permissions), and add the new member. You can also set the expiring date for that user; this is the date on which they will no longer have access to your group. @@ -211,6 +211,88 @@ To remove a member from a group: 1. (Optional) Select the **Also unassign this user from related issues and merge requests** checkbox. 1. Click **Remove member**. +## Filter and sort members in a group + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21727) in GitLab 12.6. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/228675) in GitLab 13.7. +> - Improvements are [deployed behind a feature flag](../feature_flags.md), enabled by default. +> - Improvements are enabled on GitLab.com. +> - Improvements are recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable improvements](#enable-or-disable-improvements-to-the-ability-to-filter-and-sort-group-members). **(CORE ONLY)** + +The following sections illustrate how you can filter and sort members in a group. To view these options, +navigate to your desired group, go to **Members**, and include the noted search terms. + +### Membership filter + +By default, inherited and direct members are displayed. The [membership](subgroups/index.md#membership) filter can be used to display only inherited or only direct members. + +#### Only display inherited members + +Include `Membership` `=` `Inherited` in the search text box. + + + +#### Only display direct members + +Include `Membership` `=` `Direct` in the search text box. + + + +### 2FA filter + +[Owner](../permissions.md#group-members-permissions) permissions required. + +By default, members with 2FA enabled and disabled are displayed. The 2FA filter can be used to display only members with 2FA enabled or only members with 2FA disabled. + +#### Only display members with 2FA enabled + +Include `2FA` `=` `Enabled` in the search text box. + + + +#### Only display members with 2FA disabled + +Include `2FA` `=` `Disabled` in the search text box. + + + +### Search + +You can search for members by name, username, or email. + + + +### Sort + +You can sort members by **Account**, **Access granted**, **Max role**, or **Last sign-in** in ascending or descending order. + + + +### Enable or disable improvements to the ability to filter and sort group members **(CORE ONLY)** + +Group member filtering and sorting improvements are deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can opt to disable the improvements. + +To disable them: + +```ruby +# For the instance +Feature.disable(:group_members_filtered_search) +# For a single group +Feature.disable(:group_members_filtered_search, Group.find(<group id>)) +``` + +To enable them: + +```ruby +# For the instance +Feature.enable(:group_members_filtered_search) +# For a single group +Feature.enable(:group_members_filtered_search, Group.find(<group id>)) +``` + ## Changing the default branch protection of a group > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7583) in GitLab 12.9. @@ -226,7 +308,7 @@ To change this setting for a specific group: To change this setting globally, see [Default branch protection](../admin_area/settings/visibility_and_access_controls.md#default-branch-protection). -NOTE: **Note:** +NOTE: In [GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab administrators can choose to [disable group owners from updating the default branch protection](../admin_area/settings/visibility_and_access_controls.md#disable-group-owners-from-updating-default-branch-protection). ## Add projects to a group @@ -342,7 +424,7 @@ Group links can be created using either a CN or a filter. These group links are For more information on the administration of LDAP and group sync, refer to the [main LDAP documentation](../../administration/auth/ldap/index.md#group-sync). -NOTE: **Note:** +NOTE: If an LDAP user is a group member when LDAP Synchronization is added, and they are not part of the LDAP group, they will be removed from the group. ### Creating group links via CN **(STARTER ONLY)** @@ -377,7 +459,7 @@ In GitLab [8.15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/822) and 1. Select the pencil icon in the row for the user you are editing. 1. Select the brown `Edit permissions` button in the modal. - + Now you will be able to edit the user's permissions from the **Members** page. @@ -404,7 +486,7 @@ and above. There are a few limitations compared to project wikis: -- Local Git access is not supported yet. +- Git LFS is not supported. - Group wikis are not included in global search, group exports, backups, and Geo replication. - Changes to group wikis don't show up in the group's activity feed. - Group wikis [can't be moved](../../api/project_repository_storage_moves.md#limitations) using the project @@ -482,12 +564,12 @@ To change your group path (group URL): 1. Enter a new name under **Change group URL**. 1. Click **Change group URL**. -CAUTION: **Caution:** +WARNING: It is currently not possible to rename a namespace if it contains a project with [Container Registry](../packages/container_registry/index.md) tags, because the project cannot be moved. -TIP: **Tip:** +NOTE: If you want to retain ownership over the original namespace and protect the URL redirects, then instead of changing a group's path or renaming a username, you can create a new group and transfer projects to it. @@ -716,7 +798,7 @@ To enable delayed deletion of projects: 1. Expand the **Permissions, LFS, 2FA** section, and check **Enable delayed project removal**. 1. Click **Save changes**. -NOTE: **Note:** +NOTE: The group setting for delayed deletion is not inherited by sub-groups and has to be individually defined for each group. #### Prevent project forking outside group **(PREMIUM)** @@ -747,20 +829,6 @@ To enable prevent project forking: - **Pipelines quota**: Keep track of the [pipeline quota](../admin_area/settings/continuous_integration.md) for the group. - **Integrations**: Configure [integrations](../admin_area/settings/project_integration_management.md) for your group. -#### Storage usage quota **(STARTER)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/13294) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.0. - -A group owner can check the aggregated storage usage for all the projects in a group, sub-groups included, in the **Storage** tab of the **Usage Quotas** page available to the group page settings list. - - - -The total usage of the storage is updated if any relevant event that -will affect its value is triggered (e.g., a commit push). -For performance reasons, we may delay the update up to 1 hour and 30 minutes. - -If your namespace shows `N/A` as the total storage usage, you can trigger a recalculation by pushing a commit to any project in that namespace. - #### Group push rules **(STARTER)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34370) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.8. @@ -794,10 +862,21 @@ With [GitLab Issue Analytics](issues_analytics/index.md), you can see a bar char ## Repositories analytics **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215104) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263478) in GitLab 13.6. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/276003) in GitLab 13.7. With [GitLab Repositories Analytics](repositories_analytics/index.md), you can download a CSV of the latest coverage data for all the projects in your group. +### Check code coverage for all projects + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263478) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. + +See the overall activity of all projects with code coverage with [GitLab Repositories Analytics](repositories_analytics/index.md). + +It displays the current code coverage data available for your projects: + + + ## Dependency Proxy Use GitLab as a [dependency proxy](../packages/dependency_proxy/index.md) for upstream Docker images. diff --git a/doc/user/group/insights/index.md b/doc/user/group/insights/index.md index 50dfb0e5ccd..b559e6806e9 100644 --- a/doc/user/group/insights/index.md +++ b/doc/user/group/insights/index.md @@ -1,8 +1,8 @@ --- type: reference, howto stage: Manage -group: Value Stream 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/#designated-technical-writers +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/#assignments --- # Insights **(ULTIMATE)** @@ -40,7 +40,7 @@ more details about the `.gitlab/insights.yml` configuration file. If you have access to view a group, then you have access to view their Insights. -NOTE: **Note:** +NOTE: Issues or merge requests that you don't have access to (because you don't have access to the project they belong to, or because they are confidential) are filtered out of the Insights charts. diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index dea1eaba819..269be19f759 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -1,20 +1,19 @@ --- type: reference stage: Manage -group: Value Stream 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/#designated-technical-writers +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/#assignments --- # Issue Analytics **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7478) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.5. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196561) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9 at the project level. Issue Analytics is a bar graph which illustrates the number of issues created each month. The default timespan is 13 months, which includes the current month, and the 12 months prior. -To access the chart, navigate to your group or project sidebar and select **{chart}** **Analytics > Issue Analytics**. +To access the chart, navigate to your group sidebar and select **{chart}** **Analytics > Issue Analytics**. Hover over each bar to see the total number of issues. diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index 90050e217ee..a06c7a8f325 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -2,7 +2,7 @@ type: reference stage: Plan 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/#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 --- # Iterations **(STARTER)** @@ -38,7 +38,7 @@ From there you can create a new iteration or click an iteration to get a more de ## Create an iteration -NOTE: **Note:** +NOTE: You need Developer [permissions](../../permissions.md) or higher to create an iteration. To create an iteration: @@ -52,7 +52,7 @@ To create an iteration: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218277) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.2. -NOTE: **Note:** +NOTE: You need Developer [permissions](../../permissions.md) or higher to edit an iteration. To edit an iteration, click the three-dot menu (**{ellipsis_v}**) > **Edit iteration**. @@ -71,17 +71,16 @@ To learn how to add an issue to an iteration, see the steps in You can track the progress of an iteration by reviewing iteration reports. An iteration report displays a list of all the issues assigned to an iteration and their status. +The report also shows a breakdown of total issues in an iteration. +Open iteration reports show a summary of completed, unstarted, and in-progress issues. +Closed iteration reports show the total number of issues completed by the due date. + To view an iteration report, go to the iterations list page and click an iteration's title. ### Iteration burndown and burnup charts > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222750) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.5. -> - It was deployed behind a feature flag, disabled by default. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45492) on GitLab 13.6. -> - It's enabled on GitLab.com. -> - It's able to be enabled or disabled per-group. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-iteration-charts). **(STARTER ONLY)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/269972) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.7. The iteration report includes [burndown and burnup charts](../../project/milestones/burndown_and_burnup_charts.md), similar to how they appear when viewing a [milestone](../../project/milestones/index.md). @@ -113,30 +112,6 @@ Feature.disable(:group_iterations) Feature.disable(:group_iterations, Group.find(<group ID>)) ``` -## Disable iteration charts **(STARTER ONLY)** - -GitLab iteration charts feature is deployed with a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can disable it for your instance. `:iteration_charts` can be enabled or disabled per-group. - -To enable it: - -```ruby -# Instance-wide -Feature.enable(:iteration_charts) -# or by group -Feature.enable(:iteration_charts, Group.find(<group ID>)) -``` - -To disable it: - -```ruby -# Instance-wide -Feature.disable(:iteration_charts) -# or by group -Feature.disable(:iteration_charts, Group.find(<group ID>)) -``` - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index fe5e7979592..fc4fb0236de 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -2,14 +2,14 @@ type: reference stage: Verify 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/#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 --- # Repositories Analytics **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215104) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. ## Latest project test coverage list @@ -25,7 +25,9 @@ To see the latest code coverage for each project in your group: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215104) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. -You can get a CSV of the code coverage data for all of the projects in your group. This report has a maximum of 1000 records. To get the report: +You can get a CSV of the code coverage data for all of the projects in your group. This report has a maximum of 1000 records. The code coverage data is from the default branch in each project. + +To get the report: 1. Go to your group's **Analytics > Repositories** page 1. Click **Download historic test coverage data (.csv)**, @@ -44,6 +46,9 @@ For each day that a coverage report was generated by a job in a project's pipeli If the project's code coverage was calculated more than once in a day, we will take the last value from that day. +NOTE: +[In GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/270102), group code coverage data is taken from the configured [default branch](../../project/repository/branches/index.md#default-branch). In earlier versions, it is taken from the `master` branch. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index f9d49c1236e..32abc676352 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -2,7 +2,7 @@ type: reference stage: Plan group: Product Planning -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 --- # Roadmap **(PREMIUM)** diff --git a/doc/user/group/saml_sso/group_managed_accounts.md b/doc/user/group/saml_sso/group_managed_accounts.md index 50f062bafa9..15dd91bece2 100644 --- a/doc/user/group/saml_sso/group_managed_accounts.md +++ b/doc/user/group/saml_sso/group_managed_accounts.md @@ -2,12 +2,12 @@ type: reference, howto stage: Manage group: Access -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 --- # Group Managed Accounts **(PREMIUM)** -CAUTION: **Caution:** +WARNING: This [Closed Beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#sts=Closed%20Beta) feature is being re-evaluated in favor of a different [identity model](https://gitlab.com/groups/gitlab-org/-/epics/4345) that does not require separate accounts. We recommend that group administrators who haven't yet implemented this feature wait for diff --git a/doc/user/group/saml_sso/img/saml_group_links_nav_v13_6.png b/doc/user/group/saml_sso/img/saml_group_links_nav_v13_6.png Binary files differnew file mode 100644 index 00000000000..c1980b24a6d --- /dev/null +++ b/doc/user/group/saml_sso/img/saml_group_links_nav_v13_6.png diff --git a/doc/user/group/saml_sso/img/saml_group_links_v13_6.png b/doc/user/group/saml_sso/img/saml_group_links_v13_6.png Binary files differnew file mode 100644 index 00000000000..c78b77b8fcf --- /dev/null +++ b/doc/user/group/saml_sso/img/saml_group_links_v13_6.png diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 94d2c9afb24..62431747911 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Access -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 --- # SAML SSO for GitLab.com groups **(SILVER ONLY)** @@ -38,13 +38,15 @@ GitLab.com uses the SAML NameID to identify users. The NameID element: - Must be unique to each user. - Must be a persistent value that will never change, such as a randomly generated unique user ID. - Is case sensitive. The NameID must match exactly on subsequent login attempts, so should not rely on user input that could change between upper and lower case. -- Should not be an email address or username. We strongly recommend against these as it is hard to guarantee they will never change, for example when a person's name changes. Email addresses are also case-insensitive, which can result in users being unable to sign in. +- Should not be an email address or username. We strongly recommend against these as it's hard to + guarantee it doesn't ever change, for example, when a person's name changes. Email addresses are + also case-insensitive, which can result in users being unable to sign in. The relevant field name and recommended value for supported providers are in the [provider specific notes](#providers). appropriate corresponding field. -CAUTION: **Warning:** -Once users have signed into GitLab using the SSO SAML setup, changing the `NameID` will break the configuration and potentially lock users out of the GitLab group. +WARNING: +Once users have signed into GitLab using the SSO SAML setup, changing the `NameID` breaks the configuration and potentially locks users out of the GitLab group. #### NameID Format @@ -56,11 +58,11 @@ GitLab provides metadata XML that can be used to configure your Identity Provide 1. Navigate to the group and click **Settings > SAML SSO**. 1. Copy the provided **GitLab metadata URL**. -1. Follow your Identity Provider's documentation and paste the metadata URL when it is requested. +1. Follow your Identity Provider's documentation and paste the metadata URL when it's requested. ## Configuring GitLab -Once you've set up your identity provider to work with GitLab, you'll need to configure GitLab to use it for authentication: +After you set up your identity provider to work with GitLab, you must configure GitLab to use it for authentication: 1. Navigate to the group's **Settings > SAML SSO**. 1. Find the SSO URL from your Identity Provider and enter it the **Identity provider single sign-on URL** field. @@ -71,7 +73,7 @@ Once you've set up your identity provider to work with GitLab, you'll need to co  -NOTE: **Note:** +NOTE: Please note that the certificate [fingerprint algorithm](#additional-providers-and-setup-options) must be in SHA1. When configuring the identity provider, use a secure signature algorithm. ### SSO enforcement @@ -79,18 +81,18 @@ Please note that the certificate [fingerprint algorithm](#additional-providers-a - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5291) in GitLab 11.8. - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/9255) in GitLab 11.11 with ongoing enforcement in the GitLab UI. -With this option enabled, users must go through your group's GitLab single sign-on URL. They may also be added via SCIM, if configured. Users cannot be added manually, and may only access project/group resources via the UI by signing in through the SSO URL. +With this option enabled, users must go through your group's GitLab single sign-on URL. They may also be added via SCIM, if configured. Users can't be added manually, and may only access project/group resources via the UI by signing in through the SSO URL. -However, users will not be prompted to sign in through SSO on each visit. GitLab will check whether a user has authenticated through SSO, and will only prompt the user to sign in via SSO if the session has expired. +However, users are not prompted to sign in through SSO on each visit. GitLab checks whether a user has authenticated through SSO, and only prompts the user to sign in via SSO if the session has expired. You can see more information about how long a session is valid in our [user profile documentation](../../profile/#why-do-i-keep-getting-signed-out). We intend to add a similar SSO requirement for [Git and API activity](https://gitlab.com/gitlab-org/gitlab/-/issues/9152). -When SSO enforcement is enabled for a group, users cannot share a project in the group outside the top-level group, even if the project is forked. +When SSO enforcement is enabled for a group, users can't share a project in the group outside the top-level group, even if the project is forked. ## Providers -NOTE: **Note:** +NOTE: GitLab is unable to provide support for IdPs that are not listed here. | Provider | Documentation | @@ -190,31 +192,77 @@ If the information you need isn't listed above you may wish to check our [troubl ## User access and management +> [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/268142) in GitLab 13.7. + Once Group SSO is configured and enabled, users can access the GitLab.com group through the identity provider's dashboard. If [SCIM](scim_setup.md) is configured, please see the [user access and linking setup section on the SCIM page](scim_setup.md#user-access-and-linking-setup). -When a user tries to sign in with Group SSO, they will need an account that's configured with one of the following: +When a user tries to sign in with Group SSO, GitLab attempts to find or create a user based on the following: -- [SCIM](scim_setup.md). -- [Group-managed accounts](group_managed_accounts.md). -- A GitLab.com account. +- Find an existing user with a matching SAML identity. This would mean the user either had their account created by [SCIM](scim_setup.md) or they have previously signed in with the group's SAML IdP. +- If there is no conflicting user with the same email address, create a new account automatically. +- If there is a conflicting user with the same email address, redirect the user to the sign-in page to: + - Create a new account with another email address. + - Sign-in to their existing account to link the SAML identity. ### Linking SAML to your existing GitLab.com account To link SAML to your existing GitLab.com account: 1. Sign in to your GitLab.com account. -1. Locate and visit the **GitLab single sign-on URL** for the group you are signing in to. A group Admin can find this on the group's **Settings > SAML SSO** page. If the sign-in URL is configured, users can connect to the GitLab app from the Identity Provider. +1. Locate and visit the **GitLab single sign-on URL** for the group you're signing in to. A group Admin can find this on the group's **Settings > SAML SSO** page. If the sign-in URL is configured, users can connect to the GitLab app from the Identity Provider. 1. Click **Authorize**. 1. Enter your credentials on the Identity Provider if prompted. -1. You will be redirected back to GitLab.com and should now have access to the group. In the future, you can use SAML to sign in to GitLab.com. +1. You are then redirected back to GitLab.com and should now have access to the group. In the future, you can use SAML to sign in to GitLab.com. -On subsequent visits, you should be able to go [sign in to GitLab.com with SAML](#signing-in-to-gitlabcom-with-saml) or by visiting links directly. If the **enforce SSO** option is turned on, you will be redirected to sign in through the identity provider. +On subsequent visits, you should be able to go [sign in to GitLab.com with SAML](#signing-in-to-gitlabcom-with-saml) or by visiting links directly. If the **enforce SSO** option is turned on, you are then redirected to sign in through the identity provider. ### Signing in to GitLab.com with SAML 1. Sign in to your identity provider. 1. From the list of apps, click on the "GitLab.com" app (The name is set by the administrator of the identity provider). -1. You will be signed in to GitLab.com and redirected to the group. +1. You are then signed in to GitLab.com and redirected to the group. + +### Configure user settings from SAML response + +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263661) in GitLab 13.7. + +GitLab allows setting certain user attributes based on values from the SAML response. +This affects users created on first sign-in via Group SAML. Existing users' +attributes are not affected regardless of the values sent in the SAML response. + +#### Supported user attributes + +- `can_create_group` - 'true' or 'false' to indicate whether the user can create + new groups. Default is `true`. +- `projects_limit` - The total number of personal projects a user can create. + A value of `0` means the user cannot create new projects in their personal + namespace. Default is `10000`. + +#### Example SAML response + +You can find SAML responses in the developer tools or console of your browser, +in base64-encoded format. Use the base64 decoding tool of your choice to +convert the information to XML. An example SAML response is shown here. + +```xml + <saml2:AttributeStatement> + <saml2:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> + <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.email</saml2:AttributeValue> + </saml2:Attribute> + <saml2:Attribute Name="first_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> + <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.firstName</saml2:AttributeValue> + </saml2:Attribute> + <saml2:Attribute Name="last_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> + <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.lastName</saml2:AttributeValue> + </saml2:Attribute> + <saml2:Attribute Name="can_create_group" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> + <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">true</saml2:AttributeValue> + </saml2:Attribute> + <saml2:Attribute Name="projects_limit" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> + <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">10</saml2:AttributeValue> + </saml2:Attribute> + </saml2:AttributeStatement> +``` ### Role @@ -238,10 +286,53 @@ Users can unlink SAML for a group from their profile page. This can be helpful i - You no longer want a group to be able to sign you in to GitLab.com. - Your SAML NameID has changed and so GitLab can no longer find your user. -For example, to unlink the `MyOrg` account, the following **Disconnect** button will be available under **Profile > Accounts**: +WARNING: +Unlinking an account removes all roles assigned to that user within the group. +If a user relinks their account, roles need to be reassigned. + +For example, to unlink the `MyOrg` account, the following **Disconnect** button is available under **Profile > Accounts**:  +## Group Sync + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a demo of Group Sync using Azure, see [Demo: SAML Group Sync](https://youtu.be/Iqvo2tJfXjg). + +When the SAML response includes a user and their group memberships from the SAML identity provider, +GitLab uses that information to automatically manage that user's GitLab group memberships. + +Ensure your SAML identity provider sends an attribute statement named `Groups` or `groups` like the following: + +```xml +<saml:AttributeStatement> + <saml:Attribute Name="Groups"> + <saml:AttributeValue xsi:type="xs:string">Developers</saml:AttributeValue> + <saml:AttributeValue xsi:type="xs:string">Product Managers</saml:AttributeValue> + </saml:Attribute> +</saml:AttributeStatement> +``` + +When SAML SSO is enabled for the top-level group, `Maintainer` and `Owner` level users +see a new menu item in group **Settings -> SAML Group Links**. Each group (parent or subgroup) can specify +one or more group links to map a SAML identity provider group name to a GitLab access level. + + + +To link the SAML `Freelancers` group in the attribute statement example above: + +1. Enter `Freelancers` in the `SAML Group Name` field. +1. Choose the desired `Access Level`. +1. **Save** the group link. +1. Repeat to add additional group links if desired. + + + +If a user is a member of multiple SAML groups mapped to the same GitLab group, +the user gets the highest access level from the groups. For example, if one group +is linked as `Guest` and another `Maintainer`, a user in both groups gets `Maintainer` +access. + ## Glossary | Term | Description | @@ -250,7 +341,7 @@ For example, to unlink the `MyOrg` account, the following **Disconnect** button | Service Provider | SAML considers GitLab to be a service provider. | | Assertion | A piece of information about a user's identity, such as their name or role. Also know as claims or attributes. | | SSO | Single Sign On. | -| Assertion consumer service URL | The callback on GitLab where users will be redirected after successfully authenticating with the identity provider. | +| Assertion consumer service URL | The callback on GitLab where users are redirected after successfully authenticating with the identity provider. | | Issuer | How GitLab identifies itself to the identity provider. Also known as a "Relying party trust identifier". | | Certificate fingerprint | Used to confirm that communications over SAML are secure by checking that the server is signing communications with the correct certificate. Also known as a certificate thumbprint. | diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 7c089a289c6..40c036e1fc0 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -2,7 +2,7 @@ type: howto, reference stage: Manage group: Access -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 --- # SCIM provisioning using SAML SSO for GitLab.com groups **(SILVER ONLY)** @@ -13,7 +13,7 @@ System for Cross-domain Identity Management (SCIM), is an open standard that ena automation of user provisioning. When SCIM is provisioned for a GitLab group, membership of that group is synchronized between GitLab and the identity provider. -GitLab's [SCIM API](../../../api/scim.md) implements part of [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644). +The GitLab [SCIM API](../../../api/scim.md) implements part of [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644). ## Features @@ -92,14 +92,14 @@ You can then test the connection by clicking on **Test Connection**. If the conn 1. Save your changes. For reference, you can view [an example configuration in the troubleshooting reference](../../../administration/troubleshooting/group_saml_scim.md#azure-active-directory). - NOTE: **Note:** + NOTE: If you used a unique identifier **other than** `objectId`, be sure to map it to `externalId`. 1. Below the mapping list click on **Show advanced options > Edit attribute list for AppName**. 1. Ensure the `id` is the primary and required field, and `externalId` is also required. - NOTE: **Note:** + NOTE: `username` should neither be primary nor required as we don't support that field on GitLab SCIM yet. @@ -108,15 +108,15 @@ You can then test the connection by clicking on **Test Connection**. If the conn  - NOTE: **Note:** + NOTE: You can control what is actually synced by selecting the `Scope`. For example, `Sync only assigned users and groups` only syncs the users assigned to the application (`Users and groups`), otherwise, it syncs the whole Active Directory. Once enabled, the synchronization details and any errors appears on the -bottom of the **Provisioning** screen, together with a link to the audit logs. +bottom of the **Provisioning** screen, together with a link to the audit events. -CAUTION: **Warning:** +WARNING: Once synchronized, changing the field mapped to `id` and `externalId` may cause a number of errors. These include provisioning errors, duplicate users, and may prevent existing users from accessing the GitLab group. ### Okta configuration steps @@ -132,7 +132,7 @@ configuration. Otherwise, the Okta SCIM app may not work properly. 1. If you see an **Admin** button in the top right, click the button. This will ensure you are in the Admin area. - TIP: **Tip:** + NOTE: If you're using the Developer Console, click **Developer Console** in the top bar and select **Classic UI**. Otherwise, you may not see the buttons described in the following steps: @@ -194,7 +194,7 @@ provider or users list for the specific app. Upon the next sync, the user is deprovisioned, which means that the user is removed from the group. -NOTE: **Note:** +NOTE: Deprovisioning does not delete the user account. ```mermaid @@ -240,7 +240,7 @@ To see how the `external_uid` compares to the value returned as the SAML NameId, Whether the value was changed or you need to map to a different field, ensure `id`, `externalId`, and `NameId` all map to the same field. -If GitLab's `externalId` doesn't match the SAML NameId, it will need to be updated in order for the user to log in. Ideally your identity provider will be configured to do such an update, but in some cases it may be unable to do so, such as when looking up a user fails due to an ID change. +If the GitLab `externalId` doesn't match the SAML NameId, it needs to be updated in order for the user to sign in. Ideally your identity provider is configured to do such an update, but in some cases it may be unable to do so, such as when looking up a user fails due to an ID change. Be cautious if you revise the fields used by your SCIM identity provider, typically `id` and `externalId`. We use these IDs to look up users. If the identity provider does not know the current values for these fields, @@ -262,6 +262,15 @@ Individual users can follow the instructions in the ["SAML authentication failed Alternatively, users can be removed from the SCIM app which will delink all removed users. Sync can then be turned on for the new SCIM app to [link existing users](#user-access-and-linking-setup). +### The SCIM app is throwing `"User has already been taken","status":409` error message + +Changing the SAML or SCIM configuration or provider can cause the following problems: + +| Problem | Solution | +|------------------------------------------------------------------------------|--------------------| +| SAML and SCIM identity mismatch. | First [verify that the user's SAML NameId matches the SCIM externalId](#how-do-i-verify-users-saml-nameid-matches-the-scim-externalid) and then [update or fix the mismatched SCIM externalId and SAML NameId](#update-or-fix-mismatched-scim-externalid-and-saml-nameid). | +| SCIM identity mismatch between GitLab and the Identify Provider SCIM app. | You can confirm whether you're hitting the error because of your SCIM identity mismatch between your SCIM app and GitLab.com by using [SCIM API](../../../api/scim.md#update-a-single-saml-user) which shows up in the `id` key and compares it with the user `externalId` in the SCIM app. You can use the same [SCIM API](../../../api/scim.md#update-a-single-saml-user) to update the SCIM `id` for the user on GitLab.com. | + ### Azure #### How do I verify my SCIM configuration is correct? @@ -283,7 +292,7 @@ When testing the connection, you may encounter an error: **You appear to have en #### (Field) can't be blank sync error -When checking the Audit Logs for the Provisioning, you can sometimes see the +When checking the Audit Events for the Provisioning, you can sometimes see the error `Namespace can't be blank, Name can't be blank, and User can't be blank.` This is likely caused because not all required fields (such as first name and last name) are present for all users being mapped. diff --git a/doc/user/group/security_dashboard/index.md b/doc/user/group/security_dashboard/index.md index c59198df081..3feccf2e342 100644 --- a/doc/user/group/security_dashboard/index.md +++ b/doc/user/group/security_dashboard/index.md @@ -3,3 +3,6 @@ redirect_to: '../../application_security/security_dashboard/index.md' --- This document was moved to [another location](../../application_security/security_dashboard/index.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/group/settings/import_export.md b/doc/user/group/settings/import_export.md index 77cb862a49d..2aee8706194 100644 --- a/doc/user/group/settings/import_export.md +++ b/doc/user/group/settings/import_export.md @@ -2,7 +2,7 @@ type: reference stage: Manage group: Import -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 --- # Group Import/Export @@ -55,7 +55,7 @@ The following items are **not** exported: - Runner tokens - SAML discovery tokens -NOTE: **Note:** +NOTE: For more details on the specific data persisted in a group export, see the [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/import_export/group/import_export.yml) file. @@ -75,7 +75,7 @@ For more details on the specific data persisted in a group export, see the 1. Alternatively, you can come back to the project settings and download the file from there by clicking **Download export**, or generate a new file by clicking **Regenerate export**. -NOTE: **Note:** +NOTE: The maximum import file size can be set by the Administrator, default is 50MB. As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin UI](../../admin_area/settings/account_and_limit_settings.md). @@ -121,10 +121,12 @@ For example: ## Rate Limits -To help avoid abuse, users are rate limited to: +To help avoid abuse, by default, users are rate limited to: | Request Type | Limit | | ---------------- | ---------------------------------------- | -| Export | 30 groups every 5 minutes | -| Download export | 10 downloads per group every 10 minutes | -| Import | 30 groups every 5 minutes | +| Export | 6 groups per minute | +| Download export | 1 download per group per minute | +| Import | 6 groups per minute | + +Please note that GitLab.com may have [different settings](../../gitlab_com/index.md#importexport) from the defaults. diff --git a/doc/user/group/subgroups/img/group_members.png b/doc/user/group/subgroups/img/group_members.png Binary files differdeleted file mode 100644 index 830ccafa794..00000000000 --- a/doc/user/group/subgroups/img/group_members.png +++ /dev/null diff --git a/doc/user/group/subgroups/img/group_members_13_7.png b/doc/user/group/subgroups/img/group_members_13_7.png Binary files differnew file mode 100644 index 00000000000..ab22bcb932c --- /dev/null +++ b/doc/user/group/subgroups/img/group_members_13_7.png diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 268014a3cd2..8af075fc0c0 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.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 type: reference, howto, concepts --- @@ -109,16 +109,16 @@ To create a subgroup:  -1. Click the **Create group** button and you will be taken to the new group's +1. Click the **Create group** button to be redirected to the new group's dashboard page. Follow the same process to create any subsequent groups. ## Membership -When you add a member to a subgroup, they inherit the membership and permission -level from the parent group(s). This model allows access to nested groups if you -have membership in one of its parents. +When you add a member to a group, that member is also added to all subgroups. +Permission level is inherited from the group’s parent. This model allows access to +subgroups if you have membership in one of its parents. Jobs for pipelines in subgroups can use [runners](../../../ci/runners/README.md) registered to the parent group(s). This means secrets configured for the parent group are available to subgroup jobs. @@ -131,49 +131,41 @@ the **Members** page of the group the member was added. You can tell if a member has inherited the permissions from a parent group by looking at the group's **Members** page. - + From the image above, we can deduce the following things: - There are 5 members that have access to the group `four`. -- User0 is a Reporter and has inherited their permissions from group `one` +- User 0 is a Reporter and has inherited their permissions from group `one` which is above the hierarchy of group `four`. -- User1 is a Developer and has inherited their permissions from group +- User 1 is a Developer and has inherited their permissions from group `one/two` which is above the hierarchy of group `four`. -- User2 is a Developer and has inherited their permissions from group +- User 2 is a Developer and has inherited their permissions from group `one/two/three` which is above the hierarchy of group `four`. -- For User3 there is no indication of a parent group, therefore they belong to +- For User 3 the **Source** column indicates **Direct member**, therefore they belong to group `four`, the one we're inspecting. - Administrator is the Owner and member of **all** subgroups and for that reason, - as with User3, there is no indication of an ancestor group. + as with User 3, the **Source** column indicates **Direct member**. -[From](https://gitlab.com/gitlab-org/gitlab/-/issues/21727) GitLab 12.6, you can filter -this list using dropdown on the right side: - - - -- **Show only direct members** displays only Administrator and User3, since these are - the only users that belong to group `four`, which is the one we're inspecting. -- **Show only inherited members** displays User0, User1 and User2, no matter which group - above the hierarchy is the source of inherited permissions. +Members can be [filtered by inherited or direct membership](../index.md#membership-filter). ### Overriding the ancestor group membership -NOTE: **Note:** +NOTE: You must be an Owner of a group to be able to add members to it. -NOTE: **Note:** +NOTE: A user's permissions in a subgroup cannot be lower than in any of its ancestor groups. Therefore, you cannot reduce a user's permissions in a subgroup with respect to its ancestor groups. To override a user's membership of an ancestor group (the first group they were added to), add the user to the new subgroup again with a higher set of permissions. -For example, if User0 was first added to group `group-1/group-1-1` with Developer -permissions, then they will inherit those permissions in every other subgroup -of `group-1/group-1-1`. To give them Maintainer access to `group-1/group-1-1/group1-1-1`, +For example, if User 1 was first added to group `one/two` with Developer +permissions, then they inherit those permissions in every other subgroup +of `one/two`. To give them Maintainer access to group `one/two/three/four`, you would add them again in that group as Maintainer. Removing them from that group, -the permissions will fallback to those of the ancestor group. +the permissions fall back to those of the ancestor group. ## Mentioning subgroups diff --git a/doc/user/group/value_stream_analytics/img/delete_value_stream_v13.4.png b/doc/user/group/value_stream_analytics/img/delete_value_stream_v13.4.png Binary files differnew file mode 100644 index 00000000000..c97fcb76343 --- /dev/null +++ b/doc/user/group/value_stream_analytics/img/delete_value_stream_v13.4.png diff --git a/doc/user/group/value_stream_analytics/img/label_based_stage_vsm_v12_9.png b/doc/user/group/value_stream_analytics/img/label_based_stage_vsm_v12_9.png Binary files differnew file mode 100644 index 00000000000..84ce33aece5 --- /dev/null +++ b/doc/user/group/value_stream_analytics/img/label_based_stage_vsm_v12_9.png diff --git a/doc/user/group/value_stream_analytics/img/new_value_stream_v13_3.png b/doc/user/group/value_stream_analytics/img/new_value_stream_v13_3.png Binary files differnew file mode 100644 index 00000000000..bc8502e85a6 --- /dev/null +++ b/doc/user/group/value_stream_analytics/img/new_value_stream_v13_3.png diff --git a/doc/user/group/value_stream_analytics/img/new_vsm_stage_v12_9.png b/doc/user/group/value_stream_analytics/img/new_vsm_stage_v12_9.png Binary files differnew file mode 100644 index 00000000000..dbef25d33ed --- /dev/null +++ b/doc/user/group/value_stream_analytics/img/new_vsm_stage_v12_9.png diff --git a/doc/user/group/value_stream_analytics/img/vsa_filter_bar_v13.3.png b/doc/user/group/value_stream_analytics/img/vsa_filter_bar_v13.3.png Binary files differnew file mode 100644 index 00000000000..506765f63cb --- /dev/null +++ b/doc/user/group/value_stream_analytics/img/vsa_filter_bar_v13.3.png diff --git a/doc/user/group/value_stream_analytics/img/vsa_time_metrics_v13_0.png b/doc/user/group/value_stream_analytics/img/vsa_time_metrics_v13_0.png Binary files differnew file mode 100644 index 00000000000..799a81584a0 --- /dev/null +++ b/doc/user/group/value_stream_analytics/img/vsa_time_metrics_v13_0.png diff --git a/doc/user/group/value_stream_analytics/img/vsm_stage_list_v12_9.png b/doc/user/group/value_stream_analytics/img/vsm_stage_list_v12_9.png Binary files differnew file mode 100644 index 00000000000..3b50dd48543 --- /dev/null +++ b/doc/user/group/value_stream_analytics/img/vsm_stage_list_v12_9.png diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md new file mode 100644 index 00000000000..0f9afdef995 --- /dev/null +++ b/doc/user/group/value_stream_analytics/index.md @@ -0,0 +1,375 @@ +--- +type: reference +stage: Manage +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)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196455) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9 at the group level. + +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 +spent in each stage defined in the process. + +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). + +Group-level Value Stream Analytics is available via **Group > Analytics > Value Stream**. + +[Project-level Value Stream Analytics](../../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. + +- **Issue** (Tracker) + - Time to schedule an issue (by milestone or by adding it to an issue board) +- **Plan** (Board) + - Time to first commit +- **Code** (IDE) + - Time to create a merge request +- **Test** (CI) + - Time it takes GitLab CI/CD to test your code +- **Review** (Merge Request/MR) + - Time spent on code review +- **Staging** (Continuous Deployment) + - Time between merging and deploying to production + +## Filter the analytics data + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13216) in GitLab 13.3 + +GitLab provides the ability to filter analytics based on the following parameters: + +- Milestones (Group level) +- Labels (Group level) +- Author +- Assignees + +To filter results: + +1. Select a group. +1. Click on the filter bar. +1. Select a parameter to filter by. +1. Select a value from the autocompleted results, or type to refine the results. + + + +### Date ranges + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13216) in GitLab 12.4. + +GitLab provides the ability to filter analytics based on a date range. To filter results: + +1. Select a group. +1. Optionally select a project. +1. Select a date range using the available date pickers. + +## How Time metrics are measured + +The "Time" metrics near the top of the page are measured as follows: + +- **Lead time**: median time from issue created to issue closed. +- **Cycle time**: median time from first commit to issue closed. + +A commit is associated with an issue by [crosslinking](../../project/issues/crosslinking_issues.md) in the commit message or by manually linking the merge request containing the commit. + + + +## How the stages are measured + +Value Stream Analytics records stage time and data based on the project issues with the +exception of the staging stage, where only data deployed to +production are measured. + +Specifically, if your CI is not set up and you have not defined a [production environment](#how-the-production-environment-is-identified), then you will not have any +data for this stage. + +Each stage of Value Stream Analytics is further described in the table below. + +| **Stage** | **Description** | +| --------- | --------------- | +| Issue | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whatever comes first. The label will be tracked only if it already has an [Issue Board list](../../project/issue_board.md) created for it. | +| Plan | Measures the median time between the action you took for the previous stage, and pushing the first commit to the branch. The very first commit of the branch is the one that triggers the separation between **Plan** and **Code**, and at least one of the commits in the branch needs to contain the related issue number (e.g., `#42`). If none of the commits in the branch mention the related issue number, it is not considered to the measurement time of the stage. | +| Code | Measures the median time between pushing a first commit (previous stage) and creating a merge request (MR) related to that commit. The key to keep the process tracked is to include the [issue closing pattern](../../project/issues/managing_issues.md#closing-issues-automatically) to the description of the merge request (for example, `Closes #xxx`, where `xxx` is the number of the issue related to this merge request). If the closing pattern is not present, then the calculation takes the creation time of the first commit in the merge request as the start time. | +| Test | Measures the median time to run the entire pipeline for that project. It's related to the time GitLab CI/CD takes to run every job for the commits pushed to that merge request defined in the previous stage. It is basically the start->finish time for all pipelines. | +| Review | Measures the median time taken to review the merge request that has a closing issue pattern, between its creation and until it's merged. | +| Staging | Measures the median time between merging the merge request with a closing issue pattern until the very first deployment to a [production environment](#how-the-production-environment-is-identified). If there isn't a production environment, this is not tracked. | + +How this works, behind the scenes: + +1. Issues and merge requests are grouped together in pairs, such that for each + `<issue, merge request>` pair, the merge request has the [issue closing pattern](../../project/issues/managing_issues.md#closing-issues-automatically) + for the corresponding issue. All other issues and merge requests are **not** + considered. +1. Then the `<issue, merge request>` pairs are filtered out by last XX days (specified + by the UI - default is 90 days). So it prohibits these pairs from being considered. +1. For the remaining `<issue, merge request>` pairs, we check the information that + we need for the stages, like issue creation date, merge request merge time, + etc. + +To sum up, anything that doesn't follow [GitLab flow](../../../topics/gitlab_flow.md) will not be tracked and the +Value Stream Analytics dashboard will 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. +- Staging stage, if the project has no [production environment](#how-the-production-environment-is-identified). + +## How the production environment is identified + +Value Stream Analytics identifies production environments by looking for project [environments](../../../ci/yaml/README.md#environment) with a name matching any of these patterns: + +- `prod` or `prod/*` +- `production` or `production/*` + +These patterns are not case-sensitive. + +You can change the name of a project environment in your GitLab CI/CD configuration. + +## Example workflow + +Below is a simple fictional workflow of a single cycle that happens in a +single day through all noted stages. Note that if a stage does not include a start +and a stop time, its data is not included in the median time. It is assumed that +milestones are created and a CI for testing and setting environments is configured. +a start and a stop mark, it is not measured and hence not calculated in the median +time. It is assumed that milestones are created and CI for testing and setting +environments is configured. + +1. Issue is created at 09:00 (start of **Issue** stage). +1. Issue is added to a milestone at 11:00 (stop of **Issue** stage / start of + **Plan** stage). +1. Start working on the issue, create a branch locally and make one commit at + 12:00. +1. Make a second commit to the branch which mentions the issue number at 12.30 + (stop of **Plan** stage / start of **Code** stage). +1. Push branch and create a merge request that contains the [issue closing pattern](../../project/issues/managing_issues.md#closing-issues-automatically) + in its description at 14:00 (stop of **Code** stage / start of **Test** and + **Review** stages). +1. The CI starts running your scripts defined in [`.gitlab-ci.yml`](../../../ci/yaml/README.md) and + takes 5min (stop of **Test** stage). +1. Review merge request, ensure that everything is OK and merge the merge + request at 19:00. (stop of **Review** stage / start of **Staging** stage). +1. Now that the merge request is merged, a deployment to the `production` + environment starts and finishes at 19:30 (stop of **Staging** stage). + +From the above example you can conclude the time it took each stage to complete +as long as their total time: + +- **Issue**: 2h (11:00 - 09:00) +- **Plan**: 1h (12:00 - 11:00) +- **Code**: 2h (14:00 - 12:00) +- **Test**: 5min +- **Review**: 5h (19:00 - 14:00) +- **Staging**: 30min (19:30 - 19:00) + +A few notes: + +- In the above example we demonstrated that it doesn't matter if your first + commit doesn't mention the issue number, you can do this later in any commit + of the branch you are working on. +- You can see that the **Test** stage is not calculated to the overall time of + the cycle since it is included in the **Review** process (every MR should be + 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. + +## Customizable Stages + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12196) in GitLab 12.9. + +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. + +GitLab allows users to create multiple value streams, hide default stages and create custom stages that align better to their development workflow. + +### Stage path + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210315) in GitLab 13.0. + +Stages are visually depicted as a horizontal process flow. Selecting a stage will update the +the content below the value stream. + +This is disabled by default. If you have a self-managed instance, an +administrator can [open a Rails console](../../../administration/troubleshooting/navigating_gitlab_via_rails_console.md) +and enable it with the following command: + +```ruby +Feature.enable(:value_stream_analytics_path_navigation) +``` + +### Adding a stage + +In the following example we're creating a new stage that measures and tracks issues from creation +time until they are closed. + +1. Navigate to your group's **Analytics > Value Stream**. +1. Click the **Add a stage** button. +1. Fill in the new stage form: + - Name: Issue start to finish. + - Start event: Issue created. + - End event: Issue closed. +1. Click the **Add stage** button. + + + +The new stage is persisted and it will always show up on the Value Stream Analytics page for your +group. + +If you want to alter or delete the stage, you can easily do that for customized stages by: + +1. Hovering over the stage. +1. Clicking the vertical ellipsis (**{ellipsis_v}**) button that appears. + + + +Creating a custom stage requires specifying two events: + +- A start. +- An end. + +Be careful to choose a start event that occurs *before* your end event. For example, consider a +stage that: + +- Started when an issue is added to a board. +- Ended when the issue is created. + +This stage would not work because the end event has already happened when the start event occurs. +To prevent such invalid stages, the UI prohibits incompatible start and end events. After you select +the start event, the stop event dropdown will only list the compatible events. + +### Re-ordering stages + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196698) in GitLab 12.10. + +Once a custom stage has been added, you can "drag and drop" stages to rearrange their order. These changes are automatically saved to the system. + +### Label based stages + +The pre-defined start and end events can cover many use cases involving both issues and merge requests. + +For supporting more complex workflows, use stages based on group labels. These events are based on +labels being added or removed. In particular, [scoped labels](../../project/labels.md#scoped-labels) +are useful for complex workflows. + +In this example, we'd like to measure more accurate code review times. The workflow is the following: + +- When the code review starts, the reviewer adds `workflow::code_review_start` label to the merge request. +- When the code review is finished, the reviewer adds `workflow::code_review_complete` label to the merge request. + +Creating a new stage called "Code Review": + + + +### Hiding unused stages + +Sometimes certain default stages are not relevant to a team. In this case, you can easily hide stages +so they no longer appear in the list. To hide stages: + +1. Add a custom stage to activate customizability. +1. Hover over the default stage you want to hide. +1. Click the vertical ellipsis (**{ellipsis_v}**) button that appears and select **Hide stage**. + +To recover a default stage that was previously hidden: + +1. Click **Add a stage** button. +1. In the top right corner open the **Recover hidden stage** dropdown. +1. Select a stage. + +### Creating a value stream + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221202) in GitLab 13.3 + +A default value stream is readily available for each group. You can create additional value streams based on the different areas of work that you would like to measure. + +Once created, a new value stream includes the [seven stages](#default-stages) that follow +[GitLab workflow](../../../topics/gitlab_flow.md) +best practices. You can customize this flow by adding, hiding or re-ordering stages. + +To create a value stream: + +1. Navigate to your group's **Analytics > Value Stream**. +1. Click the Value stream dropdown and select **Create new Value Stream** +1. Fill in a name for the new Value Stream +1. Click the **Create Value Stream** button. + + + +### Deleting a value stream + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221205) in GitLab 13.4. + +To delete a custom value stream: + +1. Navigate to your group's **Analytics > Value Stream**. +1. Click the Value stream dropdown and select the value stream you would like to delete. +1. Click the **Delete (name of value stream)**. +1. Click the **Delete** button to confirm. + + + +### Disabling custom value streams + +Custom value streams are enabled by default. If you have a self-managed instance, an +administrator can open a Rails console and disable them with the following command: + +```ruby +Feature.disable(:value_stream_analytics_create_multiple_value_streams) +``` + +## Days to completion chart + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21631) in GitLab 12.6. +> - [Chart median line removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235455) in GitLab 13.4. + +This chart visually depicts the total number of days it takes for cycles to be completed. (Totals are being replaced with averages in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/262070).) + +This chart uses the global page filters for displaying data based on the selected +group, projects, and timeframe. In addition, specific stages can be selected +from within the chart itself. + +The chart data is limited to the last 500 items. + +### Disabling chart + +This chart is enabled by default. If you have a self-managed instance, an +administrator can open a Rails console and disable it with the following command: + +```ruby +Feature.disable(:cycle_analytics_scatterplot_enabled) +``` + +## Type of work - Tasks by type chart + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32421) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. + +This chart shows a cumulative count of issues and merge requests per day. + +This chart uses the global page filters for displaying data based on the selected +group, projects, and timeframe. The chart defaults to showing counts for issues but can be +toggled to show data for merge requests and further refined for specific group-level labels. + +By default the top group-level labels (max. 10) are pre-selected, with the ability to +select up to a total of 15 labels. + +## Permissions + +To access Group-level Value Stream Analytics, users must have Reporter access or above. + +You can [read more about permissions](../../permissions.md) in general. + +## More 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/). |
