diff options
Diffstat (limited to 'doc/user/group')
| -rw-r--r-- | doc/user/group/epics/manage_epics.md | 14 | ||||
| -rw-r--r-- | doc/user/group/import/index.md | 2 | ||||
| -rw-r--r-- | doc/user/group/index.md | 66 | ||||
| -rw-r--r-- | doc/user/group/saml_sso/group_managed_accounts.md | 14 | ||||
| -rw-r--r-- | doc/user/group/saml_sso/group_sync.md | 10 | ||||
| -rw-r--r-- | doc/user/group/saml_sso/img/unlink_group_saml.png | bin | 9399 -> 0 bytes | |||
| -rw-r--r-- | doc/user/group/saml_sso/index.md | 10 | ||||
| -rw-r--r-- | doc/user/group/saml_sso/scim_setup.md | 22 | ||||
| -rw-r--r-- | doc/user/group/settings/group_access_tokens.md | 4 | ||||
| -rw-r--r-- | doc/user/group/subgroups/index.md | 13 | ||||
| -rw-r--r-- | doc/user/group/value_stream_analytics/index.md | 144 |
11 files changed, 160 insertions, 139 deletions
diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index e0334eda875..71d7b7fbb0c 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -34,6 +34,7 @@ To create an epic in the group you're in: - To [make the epic confidential](#make-an-epic-confidential), select the checkbox under **Confidentiality**. - Choose labels. - Select a start and due date, or [inherit](#start-and-due-date-inheritance) them. + - Select a [color](#epic-color). 1. Select **Create epic**. The newly created epic opens. @@ -62,6 +63,18 @@ 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. +### Epic color + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/79940) in GitLab 14.9 [with a flag](../../../administration/feature_flags.md) named `epic_color_highlight`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per group, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `epic_color_highlight`. +On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. +The feature is not ready for production use. + +When you create or edit an epic, you can select its color. +An epic's color is shown in [roadmaps](../roadmap/index.md), and [epic boards](epic_boards.md). + ## Edit an epic After you create an epic, you can edit the following details: @@ -71,6 +84,7 @@ After you create an epic, you can edit the following details: - Start date - Due date - Labels +- [Color](#epic-color) Prerequisites: diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index ae1465d0b1b..edf4d7677df 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -86,7 +86,7 @@ migrated: - Badges ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292431) in 13.11) - Board Lists -- Boards +- Boards - Epics ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250281) in 13.7) - Finisher - Group Labels ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292429) in 13.9) diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 6ba8251ba05..56d1569c908 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -45,16 +45,19 @@ the immediate parent group. ### Namespaces -In GitLab, a namespace is a unique name for a user, a group, or subgroup under -which a project can be created. +In GitLab, a *namespace* organizes related projects together. +GitLab has two types of namespaces: -For example, consider a user named Alex: +- A *personal* namespace, which is based on your username. Projects under a personal namespace must be configured one at a time. +- A *group* or *subgroup* namespace. In these namespaces, you can manage multiple projects at once. -| GitLab URL | Namespace | -| ---------- | --------- | -| Alex creates an account with the username `alex`: `https://gitlab.example.com/alex`. | The namespace in this case is `alex`. | -| Alex creates a group for their team with the group name `alex-team`. The group and its projects are available at: `https://gitlab.example.com/alex-team`. | The namespace in this case is `alex-team`. | -| Alex creates a subgroup of `alex-team` with the subgroup name `marketing`. The subgroup and its projects are available at: `https://gitlab.example.com/alex-team/marketing`. | The namespace in this case is `alex-team/marketing`. | +To determine whether you're viewing a group or personal namespace, you can view the URL. For example: + +| Namespace for | URL | Namespace | +| ------------- | --- | --------- | +| A user named `alex`. | `https://gitlab.example.com/alex` | `alex` | +| A group named `alex-team`. | `https://gitlab.example.com/alex-team` | `alex-team` | +| A group named `alex-team` with a subgroup named `marketing`. | `https://gitlab.example.com/alex-team/marketing` | `alex-team/marketing` | ## Create a group @@ -240,7 +243,7 @@ To change this setting for a specific group: 1. Find the group and select it. 1. From the left menu, select **Settings > General**. 1. Expand the **Permissions and group features** section. -1. Select the desired option in the **Allowed to create projects** dropdown list. +1. Select the desired option in the **Roles allowed to create projects** dropdown list. 1. Select **Save changes**. To change this setting globally, see [Default project creation protection](../admin_area/settings/visibility_and_access_controls.md#define-which-roles-can-create-projects). @@ -478,7 +481,7 @@ To prevent sharing outside of the group's hierarchy: 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. 1. Expand **Permissions and group features**. -1. Select **Prevent members from sending invitations to groups outside of `<group_name>` and its subgroups**. +1. Select **Members cannot invite groups outside of `<group_name>` and its subgroups**. 1. Select **Save changes**. ## Prevent a project from being shared with groups @@ -490,7 +493,7 @@ To prevent a project from being shared with other groups: 1. Go to the group's **Settings > General** page. 1. Expand the **Permissions and group features** section. -1. Select **Prevent sharing a project in `<group_name>` with other groups**. +1. Select **Projects in `<group_name>` cannot be shared with other groups**. 1. Select **Save changes**. This setting applies to all subgroups unless overridden by a group owner. Groups already @@ -582,7 +585,7 @@ To prevent members from being added to projects in a group: 1. Go to the group's **Settings > General** page. 1. Expand the **Permissions and group features** section. -1. Under **Membership**, select **Prevent adding new members to projects within this group**. +1. Under **Membership**, select **Users cannot be added to projects in this group**. 1. Select **Save changes**. All users who previously had permissions can no longer add members to a group. @@ -608,15 +611,14 @@ To ensure only people from your organization can access particular resources, you can restrict access to groups by IP address. This group-level setting applies to: -- The GitLab UI, including subgroups, projects, and issues. +- The GitLab UI, including subgroups, projects, issues, and pages. - [In GitLab 12.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/12874), the API. +- Using Git over SSH on GitLab.com. ### Security implications You should consider some security implications before configuring IP address restrictions. -- Restricting HTTP traffic on GitLab.com with IP address restrictions causes SSH requests (including Git operations over - SSH) to fail. For more information, see [the relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/271673). - Administrators and group owners can access group settings from any IP address, regardless of IP restriction. However: - Groups owners cannot access projects belonging to the group when accessing from a disallowed IP address. - Administrators can access projects belonging to the group when accessing from a disallowed IP address. @@ -629,6 +631,8 @@ You should consider some security implications before configuring IP address res restricted IP address, the IP restriction prevents code from being cloned. - Users may still see some events from the IP restricted groups and projects on their dashboard. Activity may include push, merge, issue, or comment events. +- IP access restrictions for Git operations via SSH are supported only on GitLab SaaS. + IP access restrictions applied to self-managed instances block SSH completely. ### Restrict group access by IP address @@ -636,7 +640,7 @@ To restrict group access by IP address: 1. Go to the group's **Settings > General** page. 1. Expand the **Permissions and group features** section. -1. In the **Allow access to the following IP addresses** field, enter IPv4 or IPv6 address ranges in CIDR notation. +1. In the **Restrict access by IP address** field, enter IPv4 or IPv6 address ranges in CIDR notation. 1. Select **Save changes**. In self-managed installations of GitLab 15.1 and later, you can also configure @@ -671,6 +675,26 @@ The most popular public email domains cannot be restricted, such as: When you share a group, both the source and target namespaces must allow the domains of the members' email addresses. +## Restrict Git access protocols + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/365601) in GitLab 15.1 [with a flag](../../administration/feature_flags.md) named `group_level_git_protocol_control`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to +[enable the feature flag](../../administration/feature_flags.md) named `group_level_git_protocol_control`. On GitLab.com, +this feature is available. + +You can set the permitted protocols used to access a group's repositories to either SSH, HTTPS, or both. This setting +is disabled when the [instance setting](../admin_area/settings/visibility_and_access_controls.md#configure-enabled-git-access-protocols) is +configured by an administrator. + +To change the permitted Git access protocols for a group: + +1. Go to the group's **Settings > General** page. +1. Expand the **Permissions and group features** section. +1. Choose the permitted protocols from **Enabled Git access protocols**. +1. Select **Save changes**. + ## Group file templates **(PREMIUM)** Use group file templates to share a set of templates for common file @@ -712,7 +736,7 @@ To disable email notifications: 1. Go to the group's **Settings > General** page. 1. Expand the **Permissions and group features** section. -1. Select **Disable email notifications**. +1. Select **Email notifications are disabled**. 1. Select **Save changes**. ## Disable group mentions @@ -731,7 +755,7 @@ To disable group mentions: 1. Go to the group's **Settings > General** page. 1. Expand the **Permissions and group features** section. -1. Select **Disable group mentions**. +1. Select **Group mentions are disabled**. 1. Select **Save changes**. ## Enable delayed project deletion **(PREMIUM)** @@ -743,7 +767,7 @@ To disable group mentions: > - [User interface changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352961) in GitLab 15.1. [Delayed project deletion](../project/settings/index.md#delayed-project-deletion) is locked and disabled unless the instance-level settings for -[deletion protection](../admin_area/settings/visibility_and_access_controls.md#deletion-protection) is enabled for either groups only or groups and projects. +[deletion protection](../admin_area/settings/visibility_and_access_controls.md#deletion-protection) are enabled for either groups only or groups and projects. When enabled on groups, projects in the group are deleted after a period of delay. During this period, projects are in a read-only state and can be restored. The default period is seven days but [is configurable at the instance level](../admin_area/settings/visibility_and_access_controls.md#retention-period). @@ -848,12 +872,12 @@ Support for group-level settings for merge request approval rules is tracked in - [Audit Events](../../administration/audit_events.md#group-events). - [CI/CD minutes quota](../../ci/pipelines/cicd_minutes.md): Keep track of the CI/CD minute quota for the group. - [Integrations](../admin_area/settings/project_integration_management.md). -- [Transfer a project into a group](../project/settings/index.md#transferring-an-existing-project-into-another-namespace). +- [Transfer a project into a group](../project/settings/index.md#transfer-a-project-to-another-namespace). - [Share a project with a group](../project/members/share_project_with_groups.md): Give all group members access to the project at once. - [Lock the sharing with group feature](#prevent-a-project-from-being-shared-with-groups). - [Enforce two-factor authentication (2FA)](../../security/two_factor_authentication.md#enforce-2fa-for-all-users-in-a-group): Enforce 2FA for all group members. -- Namespaces [API](../../api/namespaces.md) and [Rake tasks](../../raketasks/features.md). +- Namespaces [API](../../api/namespaces.md) and [Rake tasks](../../raketasks/index.md). - [Control access and visibility](../admin_area/settings/visibility_and_access_controls.md). ## Troubleshooting diff --git a/doc/user/group/saml_sso/group_managed_accounts.md b/doc/user/group/saml_sso/group_managed_accounts.md deleted file mode 100644 index 0a00d0c1c1c..00000000000 --- a/doc/user/group/saml_sso/group_managed_accounts.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -type: reference, howto -stage: Manage -group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -remove_date: '2022-06-13' -redirect_to: 'index.md' ---- - -# Group Managed Accounts **(PREMIUM)** - -This [closed beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#sts=Closed%20Beta) feature was never enabled globally. See -[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/296544) for progress on removing the feature. -Use [SAML SSO](index.md) instead. diff --git a/doc/user/group/saml_sso/group_sync.md b/doc/user/group/saml_sso/group_sync.md index 2239562b831..b8b7a16b31b 100644 --- a/doc/user/group/saml_sso/group_sync.md +++ b/doc/user/group/saml_sso/group_sync.md @@ -23,10 +23,12 @@ For a demo of Group Sync using Azure, see [Demo: SAML Group Sync](https://youtu. To configure SAML Group Sync: -1. Configure SAML authentication: - - For GitLab self-managed, see [SAML OmniAuth Provider](../../../integration/saml.md). - - For GitLab.com, see [SAML SSO for GitLab.com groups](index.md). -1. Ensure your SAML identity provider sends an attribute statement named `Groups` or `groups`. +- For GitLab self-managed: + 1. Configure the [SAML OmniAuth Provider](../../../integration/saml.md). + 1. Ensure your SAML identity provider sends an attribute statement with the same name as the value of the `groups_attribute` setting. +- For GitLab.com: + 1. See [SAML SSO for GitLab.com groups](index.md). + 1. Ensure your SAML identity provider sends an attribute statement named `Groups` or `groups`. NOTE: The value for `Groups` or `groups` in the SAML response can be either the group name or the group ID. diff --git a/doc/user/group/saml_sso/img/unlink_group_saml.png b/doc/user/group/saml_sso/img/unlink_group_saml.png Binary files differdeleted file mode 100644 index 9d53a9bf407..00000000000 --- a/doc/user/group/saml_sso/img/unlink_group_saml.png +++ /dev/null diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index c05e847e2c9..80e7a5903fa 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -189,7 +189,9 @@ with the notes below for consideration. | GitLab single sign-on URL | Start URL | | Identity provider single sign-on URL | SSO URL | -You must download the certificate to get the SHA1 certificate fingerprint. +NOTE: +Google Workspace displays a SHA256 fingerprint. To retrieve the SHA1 fingerprint required by GitLab for [configuring SAML](#configure-gitlab), download the certificate and calculate +the SHA1 certificate fingerprint. The recommended attributes and claims settings are: @@ -396,9 +398,7 @@ For example, to unlink the `MyOrg` account: 1. On the top bar, in the top right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Account**. -1. In the **Social sign-in** section, select **Disconnect** next to the connected account. - - +1. In the **Service sign-in** section, select **Disconnect** next to the connected account. ## Group Sync @@ -511,7 +511,7 @@ Alternatively, the SAML response may be missing the `InResponseTo` attribute in The identity provider administrator should ensure that the login is initiated by the service provider and not the identity provider. -### Message: "Login to a GitLab account to link with your SAML identity" +### Message: "Sign in to GitLab to connect your organization's account" A user can see this message when they are trying to [manually link SAML to their existing GitLab.com account](#linking-saml-to-your-existing-gitlabcom-account). diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index cc154b96ed0..04aa99e08af 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -71,8 +71,10 @@ Follow [Azure documentation to configure the attribute mapping](https://docs.mic The following table below provides an attribute mapping known to work with GitLab. If your SAML configuration differs from [the recommended SAML settings](index.md#azure-setup-notes), -modify the corresponding `customappsso` settings accordingly. If a mapping is not listed in the -table, use the Azure defaults. For a list of required attributes, refer to the [SCIM API documentation](../../../api/scim.md). +modify the corresponding `customappsso` settings accordingly. In particular, the `externalId` must +match the [SAML NameID](index.md#nameid). +If a mapping is not listed in the table, use the Azure defaults. +For a list of required attributes, refer to the [SCIM API documentation](../../../api/scim.md). | Azure Active Directory Attribute | `customappsso` Attribute | Matching precedence | | -------------------------------- | ------------------------------ | ------------------- | @@ -169,7 +171,7 @@ If [Group SAML](index.md) has been configured and you have an existing GitLab.co We recommend users do this prior to turning on sync, because while synchronization is active, there may be provisioning errors for existing users. -New users and existing users on subsequent visits can access the group through the identify provider's dashboard or by visiting links directly. +New users and existing users on subsequent visits can access the group through the identity provider's dashboard or by visiting links directly. [In GitLab 14.0 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/325712), GitLab users created by [SAML SSO](index.md#user-access-and-management) or SCIM provisioning display with an **Enterprise** badge in the **Members** view. @@ -257,7 +259,19 @@ Changing the SAML or SCIM configuration or provider can cause the following prob | 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-scim-provisioned-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-scim-provisioned-user) to update the SCIM `id` for the user on GitLab.com. | +| SCIM identity mismatch between GitLab and the identity 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-scim-provisioned-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-scim-provisioned-user) to update the SCIM `id` for the user on GitLab.com. | + +### Search Rails logs for SCIM requests + +GitLab.com administrators can search for SCIM requests in the `api_json.log` using the `pubsub-rails-inf-gprd-*` index in [Kibana](https://about.gitlab.com/handbook/support/workflows/kibana.html#using-kibana). Use the following filters based on the [SCIM API](../../../api/scim.md): + +- `json.path`: `/scim/v2/groups/<group-path>` +- `json.params.value`: `<externalId>` + +In a relevant log entry, the `json.params.value` shows the values of SCIM parameters GitLab receives. These values can be used to verify if SCIM parameters configured in an +identity provider's SCIM app are communicated to GitLab as intended. For example, we can use these values as a definitive source on why an account was provisioned with a certain +set of details. This information can help where an account was SCIM provisioned with details that appear to be incongruent with what might have been configured within an identity +provider's SCIM app. ### Azure diff --git a/doc/user/group/settings/group_access_tokens.md b/doc/user/group/settings/group_access_tokens.md index 649e7f2c264..9e8fc120731 100644 --- a/doc/user/group/settings/group_access_tokens.md +++ b/doc/user/group/settings/group_access_tokens.md @@ -78,7 +78,7 @@ or API. However, administrators can use a workaround: bot.confirm # Add the bot to the group with the required role. - group.add_user(bot, :maintainer) + group.add_member(bot, :maintainer) # Give the bot a personal access token. token = bot.personal_access_tokens.create(scopes:[:api, :write_repository], name: 'group_token') @@ -141,7 +141,7 @@ To enable or disable group access token creation for all sub-groups in a top-lev 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. 1. Expand **Permissions and group features**. -1. Under **Permissions**, turn on or off **Allow project and group access token creation**. +1. Under **Permissions**, turn on or off **Users can create project access tokens and group access tokens in this group**. Even when creation is disabled, you can still use and revoke existing group access tokens. diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 5f3c859d15a..bf4e13779fd 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -73,21 +73,20 @@ To create a subgroup: To create a subgroup, you must have at least the Maintainer role on the group, depending on the group's setting. By default: -- In GitLab 12.2 or later, users with at least the Maintainer role can create subgroups. -- In GitLab 12.1 or earlier, only users with the Owner role can create subgroups. - To change who can create subgroups on a group: - As a user with the Owner role on the group: - 1. On the top bar, select **Menu > Groups** and find the group. + 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. 1. Expand **Permissions and group features**. - 1. Select a role from the **Allowed to create subgroups** dropdown. + 1. Select a role from **Roles allowed to create subgroups**. + 1. Select **Save changes**. - As an administrator: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Groups**. - 1. Select the group, and select **Edit**. - 1. Select a role from the **Allowed to create subgroups** dropdown. + 1. In the group's row select **Edit**. + 1. Select a role from **Allowed to create subgroups**. + 1. Select **Save changes**. For more information, view the [permissions table](../../permissions.md#group-members-permissions). diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 72d42a8081f..3e41b7b63cc 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -7,8 +7,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Value stream analytics for groups **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196455) in GitLab 12.9 for groups. - Value stream analytics provides metrics about each stage of your software development process. A **value stream** is the entire work process that delivers value to customers. For example, @@ -20,14 +18,13 @@ Use value stream analytics to identify: - The amount of time it takes to go from an idea to production. - The velocity of a given project. - Bottlenecks in the development process. -- Detecting long-running issues or merge requests. +- Long-running issues or merge requests. - Factors that cause your software development lifecycle to slow down. Value stream analytics is also available for [projects](../../analytics/value_stream_analytics.md). ## View value stream analytics -> - Date range filter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13216) in GitLab 12.4 > - Filtering [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13216) in GitLab 13.3 > - Horizontal stage path [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12196) in 13.0 and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323982) in 13.12 @@ -40,7 +37,7 @@ To view value stream analytics for your group: 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Value stream**. -1. To view metrics for each stage, above the **Filter results** text box, select a stage. +1. To view metrics for a particular stage, select a stage below the **Filter results** text box. 1. Optional. Filter the results: 1. Select the **Filter results** text box. 1. Select a parameter. @@ -63,57 +60,18 @@ The table shows a list of related workflow items for the selected stage. Based o - Merge requests - Pipelines -## View metrics for each development stage +## View DORA metrics and key metrics for a group > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210315) in GitLab 13.0. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323982) in GitLab 13.12. -Value stream analytics shows the median time spent by issues or merge requests in each development stage. - -To view the median time spent in each stage by a group: - -1. On the top bar, select **Menu > Groups** and find your group. -1. On the left sidebar, select **Analytics > Value stream**. -1. Optional. Filter the results: - 1. Select the **Filter results** text box. - 1. Select a parameter. - 1. Select a value or enter text to refine the results. - 1. To adjust the date range: - - In the **From** field, select a start date. - - In the **To** field, select an end date. -1. To view the metrics for each stage, above the **Filter results** text box, hover over a stage. - -## View the lead time and cycle time for issues - -Value stream analytics shows the lead time and cycle time for issues in your groups: - -- Lead time: Median time from when the issue was created to when it was closed. -- Cycle time: Median time from first commit to issue closed. GitLab measures cycle time from the earliest -commit of a [linked issue's merge request](../../project/issues/crosslinking_issues.md#from-commit-messages) -to when that issue is closed. The cycle time approach underestimates the lead time because merge request creation -is always later than commit time. - -To view the lead time and cycle time for issues: - -1. On the top bar, select **Menu > Groups** and find your group. -1. On the left sidebar, select **Analytics > Value stream**. -1. Optional. Filter the results: - 1. Select the **Filter results** text box. - 1. Select a parameter. - 1. Select a value or enter text to refine the results. - 1. To adjust the date range: - - In the **From** field, select a start date. - - In the **To** field, select an end date. - -The **Lead Time** and **Cycle Time** metrics display below the **Filter results** text box. - -## View lead time for changes for merge requests **(ULTIMATE)** +The **Overview** dashboard in value stream analytics shows key metrics and DORA metrics of group performance. Based on the filter you select, +the dashboard automatically aggregates DORA metrics and displays the current status of the value stream. Select a DORA metric to view its chart. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340150) in GitLab 14.5. - -Lead time for changes is the median duration between when a merge request is merged and when it's deployed to production. +To view deployment metrics, you must have a +[production environment configured](../../../ci/environments/index.md#deployment-tier-of-environments). -To view the lead time for changes for merge requests in your group: +To view the DORA metrics and key metrics: 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Value stream**. @@ -124,45 +82,46 @@ To view the lead time for changes for merge requests in your group: 1. To adjust the date range: - In the **From** field, select a start date. - In the **To** field, select an end date. +Key metrics and DORA metrics display below the **Filter results** text box. -The **Lead Time for Changes** metrics display below the **Filter results** text box. - -## View number of successful deployments **(PREMIUM)** - -> DORA API-based deployment metrics for value stream analytics for groups were [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/337256) from GitLab Ultimate to GitLab Premium in 14.3. +### Key metrics in the value stream -To view deployment metrics, you must have a -[production environment configured](../../../ci/environments/index.md#deployment-tier-of-environments). +The **Overview** dashboard shows the following key metrics that measure team performance: -Value stream analytics shows the following deployment metrics for your group: - -- Deploys: The number of successful deployments in the date range. -- Deployment Frequency: The average number of successful deployments per day in the date range. +- Lead time: Median time from when the issue was created to when it was closed. +- Cycle time: Median time from first commit to issue closed. GitLab measures cycle time from the earliest commit of a + [linked issue's merge request](../../project/issues/crosslinking_issues.md#from-commit-messages) to when that issue is closed. + The cycle time approach underestimates the lead time because merge request creation is always later than commit time. +- New issues: Number of new issues created. +- Deploys: Total number of deployments to production. -To view deployment metrics for your group: +### DORA metrics **(ULTIMATE)** -1. On the top bar, select **Menu > Groups** and find your group. -1. On the left sidebar, select **Analytics > Value stream**. -1. Optional. Filter the results: - 1. Select the **Filter results** text box. - 1. Select a parameter. - 1. Select a value or enter text to refine the results. - 1. To adjust the date range: - - In the **From** field, select a start date. - - In the **To** field, select an end date. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340150) lead time for changes DORA metric in GitLab 14.5. +> - DORA API-based deployment metrics for value stream analytics for groups were [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/337256) from GitLab Ultimate to GitLab Premium in GitLab 14.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355304) time to restore service tile in GitLab 15.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357071) change failure rate tile in GitLab 15.0. -NOTE: -The date range selector filters items by the event time. This is the time when the currently -selected stage finished for the given item. +The value stream analytics **Overview** dashboard displays the following [DORA](../../../user/analytics/index.md) metrics: -The **Deploys** and **Deployment Frequency** metrics display below the **Filter results** text box. +- Deployment Frequency. +- Lead time for changes. +- Time to restore service. +- Change failure rate. -Deployment metrics are calculated based on data from the +DORA metrics are calculated based on data from the [DORA API](../../../api/dora/metrics.md#devops-research-and-assessment-dora-key-metrics-api). NOTE: -In GitLab 13.9 and later, metrics are calculated based on when the deployment was finished. -In GitLab 13.8 and earlier, metrics are calculated based on when the deployment was created. +In GitLab 13.9 and later, deployment frequency metrics are calculated based on when the deployment was finished. +In GitLab 13.8 and earlier, deployment frequency metrics are calculated based on when the deployment was created. + +<div class="video-fallback"> + See the video: <a href="https://www.youtube.com/embed/wQU-mWvNSiI">DORA metrics and value stream analytics</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube.com/embed/wQU-mWvNSiI" frameborder="0" allowfullscreen="true"> </iframe> +</figure> ### How value stream analytics aggregates data @@ -186,6 +145,30 @@ longer than 10 minutes in the following cases: To view when the data was most recently updated, in the right corner next to **Edit**, hover over the **Last updated** badge. +## View metrics for each development stage + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210315) in GitLab 13.0. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323982) in GitLab 13.12. + +Value stream analytics shows the median time spent by issues or merge requests in each development stage. + +To view the median time spent in each stage by a group: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Analytics > Value stream**. +1. Optional. Filter the results: + 1. Select the **Filter results** text box. + 1. Select a parameter. + 1. Select a value or enter text to refine the results. + 1. To adjust the date range: + - In the **From** field, select a start date. + - In the **To** field, select an end date. +1. To view the metrics for each stage, above the **Filter results** text box, hover over a stage. + +NOTE: +The date range selector filters items by the event time. The event time is when the +selected stage finished for the given item. + ## How value stream analytics measures stages Value stream analytics measures each stage from its start event to its end event. @@ -207,6 +190,8 @@ Each pre-defined stages of value stream analytics is further described in the ta | Review | The median time taken to review a merge request that has a closing issue pattern, between its creation and until it's merged. | | Staging | The median time between merging a merge request that has a closing issue pattern until the very first deployment to a [production environment](#how-value-stream-analytics-identifies-the-production-environment). If there isn't a production environment, this is not tracked. | +For information about how value stream analytics calculates each stage, see the [Value stream analytics development guide](../../../development/value_stream_analytics.md). + ### Example workflow This example shows a workflow through all seven stages in one day. @@ -345,7 +330,6 @@ To delete a custom value stream: ## View number of days for a cycle to complete -> - [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. > - Totals [replaced](https://gitlab.com/gitlab-org/gitlab/-/issues/262070) with averages in GitLab 13.12. @@ -367,8 +351,6 @@ The chart shows data for the last 500 workflow items. ## Tasks by type chart -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32421) in GitLab 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 |
