diff options
Diffstat (limited to 'doc/user/group')
26 files changed, 593 insertions, 378 deletions
diff --git a/doc/user/group/access_and_permissions.md b/doc/user/group/access_and_permissions.md index 395ed3c91c7..13a1fd31ee4 100644 --- a/doc/user/group/access_and_permissions.md +++ b/doc/user/group/access_and_permissions.md @@ -56,18 +56,20 @@ To change the permitted Git access protocols for a group: 1. Choose the permitted protocols from **Enabled Git access protocols**. 1. Select **Save changes**. -## Restrict group access by IP address **(PREMIUM)** +## Restrict access to groups by IP address **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1985) in GitLab 12.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215410) from GitLab Ultimate to GitLab Premium in 13.1. -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: +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. - [In GitLab 12.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/12874), the API. +Administrators can combine restricted access by IP address with +[globally-allowed IP addresses](../admin_area/settings/visibility_and_access_controls.md#configure-globally-allowed-ip-address-ranges). + ### Security implications You should consider some security implications before configuring IP address restrictions. @@ -94,7 +96,12 @@ To restrict group access by IP address: 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Permissions and group features** section. -1. In the **Restrict access by IP address** field, enter IPv4 or IPv6 address ranges in CIDR notation. +1. In the **Restrict access by IP address** field, enter a list of IPv4 or IPv6 + address ranges in CIDR notation. This list: + - Has no limit on the number of IP address ranges. + - Has a size limit of 1 GB. + - Applies to both SSH or HTTP authorized IP address ranges. You cannot split + this list by type of authorization. 1. Select **Save changes**. In self-managed installations of GitLab 15.1 and later, you can also configure @@ -290,5 +297,4 @@ If a user sees a 404 when they would normally expect access, and the problem is - `json.message`: `'Attempting to access IP restricted group'` - `json.allowed`: `false` -In viewing the log entries, compare the `remote.ip` with the list of -[allowed IPs](#restrict-group-access-by-ip-address) for the group. +In viewing the log entries, compare the `remote.ip` with the list of [allowed IP addresses](#restrict-access-to-groups-by-ip-address) for the group. diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index c6cc828302f..62f5a3ba54f 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -187,6 +187,6 @@ important to describe those, too. Think of things that may go wrong and include This is important to minimize requests for support, and to avoid doc comments with questions that you know someone might ask. -Each scenario can be a third-level heading, e.g. `### Getting error message X`. +Each scenario can be a third-level heading, for example `### Getting error message X`. If you have none to add when creating a doc, leave this section in place but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/compliance_frameworks.md b/doc/user/group/compliance_frameworks.md new file mode 100644 index 00000000000..7bd545003db --- /dev/null +++ b/doc/user/group/compliance_frameworks.md @@ -0,0 +1,262 @@ +--- +stage: Govern +group: Compliance +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Compliance frameworks **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276221) in GitLab 13.9. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/287779) in GitLab 13.12. + +You can create a compliance framework that is a label to identify that your project has certain compliance +requirements or needs additional oversight. The label can optionally enforce +[compliance pipeline configuration](#configure-a-compliance-pipeline) to the projects on which it is +[applied](../project/settings/index.md#add-a-compliance-framework-to-a-project). + +Group owners can create, edit, and delete compliance frameworks: + +1. On the top bar, select **Main menu > Groups > View all groups** and find your group. +1. On the left sidebar, select **Settings** > **General**. +1. Expand the **Compliance frameworks** section. +1. Create, edit, or delete compliance frameworks. + +## Set a default compliance framework + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375036) in GitLab 15.6. + +Group owners can set a default compliance framework. The default framework is applied to all the new projects +that are created within that group. It does not affect the framework applied to the existing projects. The default +framework cannot be deleted. + +### Example GraphQL mutations for setting a default compliance framework + +Creating a new compliance framework and setting it as the default framework for the group. + +```graphql +mutation { + createComplianceFramework( + input: {params: {name: "SOX", description: "Sarbanes-Oxley Act", color: "#87CEEB", default: true}, namespacePath: "gitlab-org"} + ) { + framework { + id + name + default + description + color + pipelineConfigurationFullPath + } + errors + } +} +``` + +Setting an existing compliance framework as the default framework the group. + +```graphql +mutation { + updateComplianceFramework( + input: {id: "gid://gitlab/ComplianceManagement::Framework/<id>", params: {default: true}} + ) { + complianceFramework { + id + name + default + description + color + pipelineConfigurationFullPath + } + } +} +``` + +## Configure a compliance pipeline **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3156) in GitLab 13.9, disabled behind `ff_evaluate_group_level_compliance_pipeline` [feature flag](../../administration/feature_flags.md). +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/300324) in GitLab 13.11. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/331231) in GitLab 14.2. + +Group owners can configure a compliance pipeline in a project separate to other projects. By default, the compliance +pipeline configuration (`.gitlab-ci.yml` file) is run instead of the pipeline configuration of labeled projects. + +However, the compliance pipeline configuration can reference the `.gitlab-ci.yml` file of the labeled projects so that: + +- The compliance pipeline can also run jobs of labeled project pipelines. This allows for centralized control of + pipeline configuration. +- Jobs and variables defined in the compliance pipeline can't be changed by variables in the labeled project's + `.gitlab-ci.yml` file. + +See [example configuration](#example-configuration) for help configuring a compliance pipeline that runs jobs from +labeled project pipeline configuration. + +To configure a compliance pipeline: + +1. On the top bar, select **Main menu > Groups > View all groups** and find your group. +1. On the left sidebar, select **Settings** > **General**. +1. Expand the **Compliance frameworks** section. +1. In **Compliance pipeline configuration (optional)**, add the path to the compliance framework configuration. Use the + `path/file.y[a]ml@group-name/project-name` format. For example: + + - `.compliance-ci.yml@gitlab-org/gitlab`. + - `.compliance-ci.yaml@gitlab-org/gitlab`. + +This configuration is inherited by projects where the compliance framework label is +[applied](../project/settings/index.md#add-a-compliance-framework-to-a-project). In projects with the applied compliance +framework label, the compliance pipeline configuration is run instead of the labeled project's own pipeline configuration. + +The user running the pipeline in the labeled project must at least have the Reporter role on the compliance project. + +When used to enforce scan execution, this feature has some overlap with +[scan execution policies](../application_security/policies/scan-execution-policies.md). We have not +[unified the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312). For details on +the similarities and differences between these features, see [Enforce scan execution](../application_security/index.md#enforce-scan-execution). + +### Example configuration + +The following example `.compliance-gitlab-ci.yml` includes the `include` keyword to ensure labeled project pipeline +configuration is also executed. + +```yaml +# Allows compliance team to control the ordering and interweaving of stages/jobs. +# Stages without jobs defined will remain hidden. +stages: + - pre-compliance + - build + - test + - pre-deploy-compliance + - deploy + - post-compliance + +variables: # Can be overridden by setting a job-specific variable in project's local .gitlab-ci.yml + FOO: sast + +sast: # None of these attributes can be overridden by a project's local .gitlab-ci.yml + variables: + FOO: sast + image: ruby:2.6 + stage: pre-compliance + rules: + - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" + when: never + - when: always # or when: on_success + allow_failure: false + before_script: + - "# No before scripts." + script: + - echo "running $FOO" + after_script: + - "# No after scripts." + +sanity check: + image: ruby:2.6 + stage: pre-deploy-compliance + rules: + - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" + when: never + - when: always # or when: on_success + allow_failure: false + before_script: + - "# No before scripts." + script: + - echo "running $FOO" + after_script: + - "# No after scripts." + +audit trail: + image: ruby:2.7 + stage: post-compliance + rules: + - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" + when: never + - when: always # or when: on_success + allow_failure: false + before_script: + - "# No before scripts." + script: + - echo "running $FOO" + after_script: + - "# No after scripts." + +include: # Execute individual project's configuration (if project contains .gitlab-ci.yml) + project: '$CI_PROJECT_PATH' + file: '$CI_CONFIG_PATH' + ref: '$CI_COMMIT_REF_NAME' # Must be defined or MR pipelines always use the use default branch +``` + +#### CF pipelines in Merge Requests originating in project forks + +When an MR originates in a fork, the branch to be merged usually only exists in the fork. +When creating such an MR against a project with CF pipelines, the above snippet will fail with a +`Project <project-name> reference <branch-name> does not exist!` error message. +This is because in the context of the target project, `$CI_COMMIT_REF_NAME` evaluates to a non-existing branch name. + +To get the correct context, use `$CI_MERGE_REQUEST_SOURCE_PROJECT_PATH` instead of `$CI_PROJECT_PATH`. +This variable is only availabe in +[merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). + +For example, for a configuration that supports both merge request pipelines originating in project forks and branch pipelines, +you need to [combine both `include` directives with `rules:if`](../../ci/yaml/includes.md#use-rules-with-include): + +```yaml +include: # Execute individual project's configuration (if project contains .gitlab-ci.yml) + - project: '$CI_MERGE_REQUEST_SOURCE_PROJECT_PATH' + file: '$CI_CONFIG_PATH' + ref: '$CI_COMMIT_REF_NAME' + rules: + - if: $CI_PIPELINE_SOURCE == 'merge_request_event' + - project: '$CI_PROJECT_PATH' + file: '$CI_CONFIG_PATH' + ref: '$CI_COMMIT_REF_NAME' + rules: + - if: $CI_PIPELINE_SOURCE != 'merge_request_event' +``` + +## Ensure compliance jobs are always run + +Compliance pipelines [use GitLab CI/CD](../../ci/index.md) to give you an incredible amount of flexibility +for defining any sort of compliance jobs you like. Depending on your goals, these jobs +can be configured to be: + +- Modified by users. +- Non-modifiable. + +Generally, if a value in a compliance job: + +- Is set, it cannot be changed or overridden by project-level configurations. +- Is not set, a project-level configuration may set. + +Either might be wanted or not depending on your use case. + +There are a few best practices for ensuring that these jobs are always run exactly +as you define them and that downstream, project-level pipeline configurations +cannot change them: + +- Add [a `rules:when:always` block](../../ci/yaml/index.md#when) to each of your compliance jobs. This ensures they are + non-modifiable and are always run. +- Explicitly set any [variables](../../ci/yaml/index.md#variables) the job references. This: + - Ensures that project-level pipeline configurations do not set them and alter their + behavior. + - Includes any jobs that drive the logic of your job. +- Explicitly set the [container image](../../ci/yaml/index.md#image) to run the job in. This ensures that your script + steps execute in the correct environment. +- Explicitly set any relevant GitLab pre-defined [job keywords](../../ci/yaml/index.md#job-keywords). + This ensures that your job uses the settings you intend and that they are not overridden by + project-level pipelines. + +## Avoid parent and child pipelines in GitLab 14.7 and earlier + +NOTE: +This advice does not apply to GitLab 14.8 and later because [a fix](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78878) added +compatibility for combining compliance pipelines, and parent and child pipelines. + +Compliance pipelines start on the run of _every_ pipeline in a labeled project. This means that if a pipeline in the labeled project +triggers a child pipeline, the compliance pipeline runs first. This can trigger the parent pipeline, instead of the child pipeline. + +Therefore, in projects with compliance frameworks, we recommend replacing +[parent-child pipelines](../../ci/pipelines/downstream_pipelines.md#parent-child-pipelines) with the following: + +- Direct [`include`](../../ci/yaml/index.md#include) statements that provide the parent pipeline with child pipeline configuration. +- Child pipelines placed in another project that are run using the [trigger API](../../ci/triggers/index.md) rather than the parent-child + pipeline feature. + +This alternative ensures the compliance pipeline does not re-start the parent pipeline. diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index 280781a4cad..b1efd2e9251 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3090) in GitLab 12.2 for subgroups. -With Contribution Analytics, you can get an overview of the [contribution events](../../profile/index.md#user-contribution-events) in your +With Contribution Analytics, you can get an overview of the [contribution events](../../profile/contributions_calendar.md#user-contribution-events) in your group. - Analyze your team's contributions over a period of time. @@ -43,7 +43,7 @@ You can choose from the following three periods: - Last month - Last three months -Select the desired period from the calendar dropdown. +Select the desired period from the calendar dropdown list.  @@ -62,6 +62,10 @@ Contributions per group member are also presented in tabular format. Select a co  +## Contribution analytics GraphQL API + +To retrieve metrics for user contributions, use the [GraphQL](../../../api/graphql/reference/index.md#groupcontributions) API. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues @@ -70,6 +74,6 @@ important to describe those, too. Think of things that may go wrong and include This is important to minimize requests for support, and to avoid doc comments with questions that you know someone might ask. -Each scenario can be a third-level heading, e.g. `### Getting error message X`. +Each scenario can be a third-level heading, for example `### Getting error message X`. If you have none to add when creating a doc, leave this section in place but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index 7f77c2147e1..547e64df7c5 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -78,6 +78,6 @@ important to describe those, too. Think of things that may go wrong and include This is important to minimize requests for support, and to avoid doc comments with questions that you know someone might ask. -Each scenario can be a third-level heading, e.g. `### Getting error message X`. +Each scenario can be a third-level heading, for example `### Getting error message X`. If you have none to add when creating a doc, leave this section in place but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/epics/epic_boards.md b/doc/user/group/epics/epic_boards.md index 78cc65f1923..64addd524ad 100644 --- a/doc/user/group/epics/epic_boards.md +++ b/doc/user/group/epics/epic_boards.md @@ -30,7 +30,7 @@ To create a new epic board: 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Epics > Boards**. -1. In the upper left corner, select the dropdown with the current board name. +1. In the upper left corner, select the dropdown list with the current board name. 1. Select **Create new board**. 1. Enter the new board's title. 1. Optional. To hide the Open or Closed lists, clear the **Show the Open list** and @@ -54,7 +54,7 @@ Prerequisites: To delete the active epic board: -1. Select the dropdown with the current board name in the upper left corner of the epic boards page. +1. Select the dropdown list with the current board name in the upper left corner of the epic boards page. 1. Select **Delete board**. 1. Select **Delete**. @@ -80,7 +80,7 @@ To create a new list: 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Epics > Boards**. 1. In the upper-right corner, select **Create list**. -1. In the **New list** column expand the **Select a label** dropdown and select the label to use as +1. In the **New list** column expand the **Select a label** dropdown list and select the label to use as list scope. 1. Select **Add to board**. diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index da6e675f0eb..21c95f37aeb 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -37,15 +37,9 @@ Also, read more about possible [planning hierarchies](../planning_hierarchy/inde ### Child issues from different group hierarchies -<!-- When feature flag is removed, integrate this info as a sentence in -https://docs.gitlab.com/ee/user/group/epics/manage_epics.html#add-an-existing-issue-to-an-epic --> - > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371081) in GitLab 15.5 [with a flag](../../../administration/feature_flags.md) named `epic_issues_from_different_hierarchies`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/373304) in GitLab 15.5. - -FLAG: -On self-managed GitLab, by default this feature is unavailable. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `epic_issues_from_different_hierarchies`. -On GitLab.com, this feature is available. +> - Feature flag `epic_issues_from_different_hierarchies` removed in GitLab 15.6. You can add issues from a different group hierarchy to an epic. To do it, paste the issue URL when @@ -77,6 +71,6 @@ important to describe those, too. Think of things that may go wrong and include This is important to minimize requests for support, and to avoid doc comments with questions that you know someone might ask. -Each scenario can be a third-level heading, e.g. `### Getting error message X`. +Each scenario can be a third-level heading, for example `### Getting error message X`. If you have none to add when creating a doc, leave this section in place but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index 0a12f551588..61aa5c5fe02 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -24,8 +24,8 @@ To create an epic in the group you're in: 1. Get to the New Epic form: - Go to your group and from the left sidebar select **Epics**. Then select **New epic**. - - From an epic in your group, select **New epic**. - - From anywhere, in the top menu, select **New...** (**{plus-square}**) **> New epic**. + - From an epic in your group, select the vertical ellipsis (**{ellipsis_v}**). Then select **New epic**. + - From anywhere, in the top menu, select **New...** (**{plus-square}**). Then select **New epic**. - In an empty [roadmap](../roadmap/index.md), select **New epic**. 1. Enter a title. @@ -257,7 +257,7 @@ To filter: 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Epics**. 1. Select the field **Search or filter results**. -1. From the dropdown menu, select the scope or enter plain text to search by epic title or description. +1. From the dropdown list, select the scope or enter plain text to search by epic title or description. 1. Press <kbd>Enter</kbd> on your keyboard. The list is filtered. ## Sort the list of epics @@ -282,10 +282,10 @@ You can reverse the default order and interact with the activity feed sorted by at the top. Your preference is saved via local storage and automatically applied to every epic and issue you view. -To change the activity sort order, select the **Oldest first** dropdown menu and select either oldest +To change the activity sort order, select the **Oldest first** dropdown list and select either oldest or newest items to be shown first. - + ## Make an epic confidential @@ -311,6 +311,8 @@ To make an epic confidential: - **In an existing epic:** on the right sidebar, select **Edit** next to **Confidentiality**, and then select **Turn on**. +In GitLab 15.6 and later, you can also use the `/confidential` [quick action](../../../user/project/quick_actions.md). + ## Manage issues assigned to an epic This section collects instructions for all the things you can do with [issues](../../project/issues/index.md) @@ -339,9 +341,8 @@ automatically added to the epic. #### Add an existing issue to an epic -You can add existing issues to an epic, including issues in a project in an epic's group, or any of -the epic's subgroups. Newly added issues appear at the top of the list of -issues in the **Epics and Issues** tab. +You can add existing issues to an epic, including issues in a project from a [different group hierarchy](index.md#child-issues-from-different-group-hierarchies). +Newly added issues appear at the top of the list of issues in the **Epics and Issues** tab. An epic contains a list of issues and an issue can be associated with at most one epic. When you add a new issue that's already linked to an epic, the issue is automatically unlinked from its @@ -359,7 +360,8 @@ To add an existing issue to an epic: 1. Identify the issue to be added, using either of the following methods: - Paste the link of the issue. - Search for the desired issue by entering part of the issue's title, then selecting the desired - match ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9126) in GitLab 12.5). + match ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9126) in GitLab 12.5). Issues + from different group hierarchies do not appear in search results. To add such an issue, enter its full URL. If there are multiple issues to be added, press <kbd>Space</kbd> and repeat this step. 1. Select **Add**. @@ -486,9 +488,26 @@ 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. -Epics can contain multiple nested child epics, up to a total of seven levels deep. +Epics can contain multiple nested child epics, up to a total of 7 levels deep. + +The maximum number of direct child epics is 100. + +### Child epics from other groups + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8502) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `child_epics_from_different_hierarchies`. 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 `child_epics_from_different_hierarchies`. +On GitLab.com, this feature is not available. The feature is not ready for production use. + +You can add a child epic that belongs to a group that is different from the parent epic's group. -Maximum number of direct child epics is 100. +Prerequisites: + +- You must have at least the Reporter role for both the child and parent epics' groups. +- Multi-level child epics must be available for both the child and parent epics' groups. + +To add a child epic from another group, paste the epic's URL when [adding an existing epic](#add-a-child-epic-to-an-epic). ### Add a child epic to an epic @@ -496,14 +515,19 @@ Prerequisites: - You must have at least the Reporter role for the parent epic's group. -To add a child epic to an epic: +To add a new epic as child epic: -1. Select **Add**. -1. Select **Add a new epic**. +1. In an epic, in the **Child issues and epics** section, select **Add > Add a new epic**. +1. Select a group from the dropdown. The epic's group is selected by default. +1. Enter a title for the new epic. +1. Select **Create epic**. + +To add an existing epic as child epic: + +1. In an epic, in the **Child issues and epics** section, select **Add > Add an existing epic**. 1. Identify the epic to be added, using either of the following methods: - Paste the link of the epic. - - Search for the desired issue by entering part of the epic's title, then selecting the desired - match ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9126) in GitLab 12.5). + - Search for the desired issue by entering part of the epic's title, then selecting the desired match. This search is only available for epics within the same group hierarchy. If there are multiple epics to be added, press <kbd>Space</kbd> and repeat this step. 1. Select **Add**. diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index ee50cfcf182..6dcc01242c2 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -4,7 +4,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Migrating groups **(FREE)** +# Migrating groups with GitLab Migration **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/249160) in GitLab 13.7 for group resources [with a flag](../../feature_flags.md) named `bulk_import`. Disabled by default. > - Group items [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/338985) in GitLab 14.3. @@ -18,15 +18,15 @@ this feature, ask an administrator to [enable the feature flag](../../../adminis `bulk_import_projects`. On GitLab.com, migrating group resources is available but migrating project resources is not available. -Users with the Owner role on a top-level group can migrate it to: +Users with the Owner role on a top-level group can use GitLab Migration to migrate the group to: - Another top-level group. - The subgroup of any existing top-level group. - Another GitLab instance, including GitLab.com. -Migrating groups using the method documented here is not the same as [migrating groups using file exports](../settings/import_export.md). +Migrating groups using GitLab Migration is not the same as [migrating groups using file exports](../settings/import_export.md). Importing and exporting groups using file exports requires you to export a group to a file and then import that file in -another GitLab instance. Migrating groups using the method documented here automates this step. +another GitLab instance. Migrating groups using GitLab Migration automates this step. ## Import your groups into GitLab @@ -139,6 +139,7 @@ Migrating projects with file exports uses the same export and import mechanisms - Issue resource state events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) - Issue resource milestone events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) - Issue resource iteration events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) + - Merge request URL references ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267947) in GitLab 15.6) - Labels ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339419) in GitLab 14.4) - LFS Objects ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339405) in GitLab 14.8) - Members ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/341886) in GitLab 14.8) @@ -148,6 +149,7 @@ Migrating projects with file exports uses the same export and import mechanisms - Merge request approvers ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339520) in GitLab 15.3) - Merge request resource state events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) - Merge request resource milestone events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) + - Issue URL references ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267947) in GitLab 15.6) - Migrate Push Rules ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339403) in GitLab 14.6) - Pull Requests (including external pull requests) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339409) in GitLab 14.5) - Pipeline History ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339412) in GitLab 14.6) diff --git a/doc/user/group/insights/index.md b/doc/user/group/insights/index.md index b4bca919498..9eb6d4387c1 100644 --- a/doc/user/group/insights/index.md +++ b/doc/user/group/insights/index.md @@ -79,6 +79,6 @@ important to describe those, too. Think of things that may go wrong and include This is important to minimize requests for support, and to avoid doc comments with questions that you know someone might ask. -Each scenario can be a third-level heading, e.g. `### Getting error message X`. +Each scenario can be a third-level heading, for example `### Getting error message X`. If you have none to add when creating a doc, leave this section in place but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index 4764625ff83..dbade014ec2 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -55,6 +55,6 @@ important to describe those, too. Think of things that may go wrong and include This is important to minimize requests for support, and to avoid doc comments with questions that you know someone might ask. -Each scenario can be a third-level heading, e.g. `### Getting error message X`. +Each scenario can be a third-level heading, for example `### Getting error message X`. If you have none to add when creating a doc, leave this section in place but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index a6435ae2aa3..518370fc7ac 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -278,8 +278,8 @@ To group issues by label: 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Issues > Iterations**. -1. In the **Group by** dropdown, select **Label**. -1. Select the **Filter by label** dropdown. -1. Select the labels you want to group by in the labels dropdown. +1. In the **Group by** dropdown list, select **Label**. +1. Select the **Filter by label** dropdown list. +1. Select the labels you want to group by in the labels dropdown list. You can also search for labels by typing in the search input. 1. Select any area outside the label dropdown list. The page is now grouped by the selected labels. diff --git a/doc/user/group/manage.md b/doc/user/group/manage.md index f11d9035a52..a63e6c6dd7f 100644 --- a/doc/user/group/manage.md +++ b/doc/user/group/manage.md @@ -66,6 +66,7 @@ This action removes the group. It also adds a background job to delete all proje Specifically: - In [GitLab 12.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [GitLab Premium](https://about.gitlab.com/pricing/premium/) or higher tiers, this action adds a background job to mark a group for deletion. By default, the job schedules the deletion 7 days in the future. You can modify this waiting period through the [instance settings](../admin_area/settings/visibility_and_access_controls.md#deletion-protection). + - In [GitLab 13.6 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/39504), if the user who sets up the deletion is removed from the group before the deletion happens, the job is cancelled, and the group is no longer scheduled for deletion. @@ -201,6 +202,13 @@ To remove a member from a group: - To unassign the user from linked issues and merge requests, select the **Also unassign this user from linked issues and merge requests** checkbox. 1. Select **Remove member**. +## Ensure removed users cannot invite themselves back + +Malicious users with the Maintainer or Owner role could exploit a race condition that allows +them to invite themselves back to a group or project that a GitLab administrator has removed them from. + +To avoid this problem, GitLab administrators can [ensure removed users cannot invite themselves back](../project/members/index.md#ensure-removed-users-cannot-invite-themselves-back). + ## Add projects to a group There are two different ways to add a new project to a group: @@ -255,6 +263,12 @@ If you are changing the path so it can be claimed by another group or user, you must rename the group too. Both names and paths must be unique. +After you change the group path, the new group path is a new namespace and you must update the existing project URL in the following resources: + +- [Include statements](../../ci/yaml/includes.md#include-a-single-configuration-file). +- Docker image references in CI files. +- Variables that specify a project or namespace. + To retain ownership of the original namespace and protect the URL redirects, create a new group and transfer projects to it instead. @@ -303,9 +317,7 @@ for the group's projects to meet your group's needs. [Feature flag `invite_members_group_modal`](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) removed. Similar to how you [share a project with a group](../project/members/share_project_with_groups.md), -you can share a group with another group. To invite a group, you must be a member of it. Members get direct access -to the shared group. This includes members who inherited group membership from a parent group. - +you can share a group with another group. To invite a group, you must be a member of it. To share a given group, for example, `Frontend` with another group, for example, `Engineering`: @@ -320,7 +332,7 @@ After sharing the `Frontend` group with the `Engineering` group: - The **Groups** tab lists the `Engineering` group. - The **Groups** tab lists a group regardless of whether it is a public or private group. -- All members of the `Engineering` group have access to the `Frontend` group. The same access levels of the members apply up to the maximum access level selected when sharing the group. +- All direct members of the `Engineering` group have access to the `Frontend` group. Direct members of `Engineering` that gain access to the `Frontend` group keep their same access level as in `Engineering`, but up to the maximum access level selected when sharing the group. Inherited members of the `Engineering` group do not gain access to the `Frontend` group. ## Transfer a group @@ -385,214 +397,6 @@ To enable delayed deletion of projects in a group: NOTE: In GitLab 13.11 and above the group setting for delayed project deletion is inherited by subgroups. As discussed in [Cascading settings](../../development/cascading_settings.md) inheritance can be overridden, unless enforced by an ancestor. -## Compliance frameworks **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276221) in GitLab 13.9. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/287779) in GitLab 13.12. - -You can create a compliance framework that is a label to identify that your project has certain compliance -requirements or needs additional oversight. The label can optionally enforce -[compliance pipeline configuration](#configure-a-compliance-pipeline) to the projects on which it is -[applied](../project/settings/index.md#add-a-compliance-framework-to-a-project). - -Group owners can create, edit, and delete compliance frameworks: - -1. On the top bar, select **Main menu > Groups > View all groups** and find your group. -1. On the left sidebar, select **Settings** > **General**. -1. Expand the **Compliance frameworks** section. -1. Create, edit, or delete compliance frameworks. - -### Configure a compliance pipeline **(ULTIMATE)** - -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3156) in GitLab 13.9, disabled behind `ff_evaluate_group_level_compliance_pipeline` [feature flag](../../administration/feature_flags.md). -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/300324) in GitLab 13.11. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/331231) in GitLab 14.2. - -Group owners can configure a compliance pipeline in a project separate to other projects. By default, the compliance -pipeline configuration (`.gitlab-ci.yml` file) is run instead of the pipeline configuration of labeled projects. - -However, the compliance pipeline configuration can reference the `.gitlab-ci.yml` file of the labeled projects so that: - -- The compliance pipeline can also run jobs of labeled project pipelines. This allows for centralized control of - pipeline configuration. -- Jobs and variables defined in the compliance pipeline can't be changed by variables in the labeled project's - `.gitlab-ci.yml` file. - -See [example configuration](#example-configuration) for help configuring a compliance pipeline that runs jobs from -labeled project pipeline configuration. - -To configure a compliance pipeline: - -1. On the top bar, select **Main menu > Groups > View all groups** and find your group. -1. On the left sidebar, select **Settings** > **General**. -1. Expand the **Compliance frameworks** section. -1. In **Compliance pipeline configuration (optional)**, add the path to the compliance framework configuration. Use the - `path/file.y[a]ml@group-name/project-name` format. For example: - - - `.compliance-ci.yml@gitlab-org/gitlab`. - - `.compliance-ci.yaml@gitlab-org/gitlab`. - -This configuration is inherited by projects where the compliance framework label is -[applied](../project/settings/index.md#add-a-compliance-framework-to-a-project). In projects with the applied compliance -framework label, the compliance pipeline configuration is run instead of the labeled project's own pipeline configuration. - -The user running the pipeline in the labeled project must at least have the Reporter role on the compliance project. - -When used to enforce scan execution, this feature has some overlap with -[scan execution policies](../application_security/policies/scan-execution-policies.md). We have not -[unified the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312). For details on -the similarities and differences between these features, see [Enforce scan execution](../application_security/index.md#enforce-scan-execution). - -#### Example configuration - -The following example `.compliance-gitlab-ci.yml` includes the `include` keyword to ensure labeled project pipeline -configuration is also executed. - -```yaml -# Allows compliance team to control the ordering and interweaving of stages/jobs. -# Stages without jobs defined will remain hidden. -stages: - - pre-compliance - - build - - test - - pre-deploy-compliance - - deploy - - post-compliance - -variables: # Can be overridden by setting a job-specific variable in project's local .gitlab-ci.yml - FOO: sast - -sast: # None of these attributes can be overridden by a project's local .gitlab-ci.yml - variables: - FOO: sast - image: ruby:2.6 - stage: pre-compliance - rules: - - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" - when: never - - when: always # or when: on_success - allow_failure: false - before_script: - - "# No before scripts." - script: - - echo "running $FOO" - after_script: - - "# No after scripts." - -sanity check: - image: ruby:2.6 - stage: pre-deploy-compliance - rules: - - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" - when: never - - when: always # or when: on_success - allow_failure: false - before_script: - - "# No before scripts." - script: - - echo "running $FOO" - after_script: - - "# No after scripts." - -audit trail: - image: ruby:2.7 - stage: post-compliance - rules: - - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" - when: never - - when: always # or when: on_success - allow_failure: false - before_script: - - "# No before scripts." - script: - - echo "running $FOO" - after_script: - - "# No after scripts." - -include: # Execute individual project's configuration (if project contains .gitlab-ci.yml) - project: '$CI_PROJECT_PATH' - file: '$CI_CONFIG_PATH' - ref: '$CI_COMMIT_REF_NAME' # Must be defined or MR pipelines always use the use default branch -``` - -##### CF pipelines in Merge Requests originating in project forks - -When an MR originates in a fork, the branch to be merged usually only exists in the fork. -When creating such an MR against a project with CF pipelines, the above snippet will fail with a -`Project <project-name> reference <branch-name> does not exist!` error message. -This is because in the context of the target project, `$CI_COMMIT_REF_NAME` evaluates to a non-existing branch name. - -To get the correct context, use `$CI_MERGE_REQUEST_SOURCE_PROJECT_PATH` instead of `$CI_PROJECT_PATH`. -This variable is only availabe in -[merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). - -For example, for a configuration that supports both branch pipelines, as well as merge request pipelines originating in project forks, -you need to [combine both `include` directives with `rules:if`](../../ci/yaml/includes.md#use-rules-with-include): - -```yaml -include: # Execute individual project's configuration (if project contains .gitlab-ci.yml) - - project: '$CI_MERGE_REQUEST_SOURCE_PROJECT_PATH' - file: '$CI_CONFIG_PATH' - ref: '$CI_COMMIT_REF_NAME' - rules: - - if: $CI_PIPELINE_SOURCE == 'merge_request_event' - - project: '$CI_PROJECT_PATH' - file: '$CI_CONFIG_PATH' - ref: '$CI_COMMIT_REF_NAME' - rules: - - if: $CI_PIPELINE_SOURCE != 'merge_request_event' -``` - -### Ensure compliance jobs are always run - -Compliance pipelines [use GitLab CI/CD](../../ci/index.md) to give you an incredible amount of flexibility -for defining any sort of compliance jobs you like. Depending on your goals, these jobs -can be configured to be: - -- Modified by users. -- Non-modifiable. - -Generally, if a value in a compliance job: - -- Is set, it cannot be changed or overridden by project-level configurations. -- Is not set, a project-level configuration may set. - -Either might be wanted or not depending on your use case. - -There are a few best practices for ensuring that these jobs are always run exactly -as you define them and that downstream, project-level pipeline configurations -cannot change them: - -- Add [a `rules:when:always` block](../../ci/yaml/index.md#when) to each of your compliance jobs. This ensures they are - non-modifiable and are always run. -- Explicitly set any [variables](../../ci/yaml/index.md#variables) the job references. This: - - Ensures that project-level pipeline configurations do not set them and alter their - behavior. - - Includes any jobs that drive the logic of your job. -- Explicitly set the [container image](../../ci/yaml/index.md#image) to run the job in. This ensures that your script - steps execute in the correct environment. -- Explicitly set any relevant GitLab pre-defined [job keywords](../../ci/yaml/index.md#job-keywords). - This ensures that your job uses the settings you intend and that they are not overridden by - project-level pipelines. - -### Avoid parent and child pipelines in GitLab 14.7 and earlier - -NOTE: -This advice does not apply to GitLab 14.8 and later because [a fix](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78878) added -compatibility for combining compliance pipelines, and parent and child pipelines. - -Compliance pipelines start on the run of _every_ pipeline in a labeled project. This means that if a pipeline in the labeled project -triggers a child pipeline, the compliance pipeline runs first. This can trigger the parent pipeline, instead of the child pipeline. - -Therefore, in projects with compliance frameworks, we recommend replacing -[parent-child pipelines](../../ci/pipelines/downstream_pipelines.md#parent-child-pipelines) with the following: - -- Direct [`include`](../../ci/yaml/index.md#include) statements that provide the parent pipeline with child pipeline configuration. -- Child pipelines placed in another project that are run using the [trigger API](../../ci/triggers/index.md) rather than the parent-child - pipeline feature. - -This alternative ensures the compliance pipeline does not re-start the parent pipeline. - ## Disable email notifications > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23585) in GitLab 12.2. @@ -722,7 +526,7 @@ This includes projects shared with the group, but it **excludes** projects in subgroups or parent groups of the group being configured. You can configure this feature for both subgroups and immediate parent groups. A project -in a subgroup has access to the templates for that subgroup, as well as +in a subgroup has access to the templates for that subgroup and any immediate parent groups. To learn how to create templates for issues and merge requests, see @@ -811,7 +615,7 @@ Group.find_by_sql("SELECT * FROM namespaces WHERE name LIKE '%oup'") If transferring a group doesn't work through the UI or API, you may want to attempt the transfer in a [Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session): WARNING: -Any command that changes data directly could be damaging if not run correctly, or under the right conditions. We highly recommend running them in a test environment with a backup of the instance ready to be restored, just in case. +Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore. ```ruby user = User.find_by_username('<username>') @@ -842,8 +646,27 @@ At times, a group deletion may get stuck. If needed, in a [Rails console session you can attempt to delete a group using the following command: WARNING: -Any command that changes data directly could be damaging if not run correctly, or under the right conditions. We highly recommend running them in a test environment with a backup of the instance ready to be restored, just in case. +Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore. ```ruby GroupDestroyWorker.new.perform(group_id, user_id) ``` + +### Find a user's maximum permissions for a group or project + +Administrators can find a user's maximum permissions for a group or project. + +1. Start a [Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session). +1. Run the following commands: + + ```ruby + user = User.find_by_username 'username' + project = Project.find_by_full_path 'group/project' + user.max_member_access_for_project project.id + ``` + + ```ruby + user = User.find_by_username 'username' + group = Group.find_by_full_path 'group' + user.max_member_access_for_group group.id + ``` diff --git a/doc/user/group/planning_hierarchy/index.md b/doc/user/group/planning_hierarchy/index.md index baa2a4d6046..f48a027ab2d 100644 --- a/doc/user/group/planning_hierarchy/index.md +++ b/doc/user/group/planning_hierarchy/index.md @@ -58,10 +58,10 @@ Epic "1"*-- "0..*" Issue In an issue, you can view the parented epic above the issue in the right sidebar under **Epic**. - + ## View ancestry of an epic In an epic, you can view the ancestors as parents in the right sidebar under **Ancestors**. - + diff --git a/doc/user/group/reporting/git_abuse_rate_limit.md b/doc/user/group/reporting/git_abuse_rate_limit.md new file mode 100644 index 00000000000..1cf3a9dbe7d --- /dev/null +++ b/doc/user/group/reporting/git_abuse_rate_limit.md @@ -0,0 +1,36 @@ +--- +stage: Anti-Abuse +group: Anti-Abuse +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Git abuse rate limit **(ULTIMATE SELF)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8066) in GitLab 15.2 [with a flag](../../../administration/feature_flags.md) named `limit_unique_project_downloads_per_namespace_user`. 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 `limit_unique_project_downloads_per_namespace_user`. On GitLab.com, this feature is not available. + +Git abuse rate limiting is a feature to automatically ban users who download or clone more than a specified number of repositories in a group or any of its subgroups within a given time frame. Banned users cannot access the main group or any of its non-public subgroups via HTTP or SSH. Access to unrelated groups is unaffected. + +If the `limit_unique_project_downloads_per_namespace_user` feature flag is enabled, all users with the Owner role for the main group receive an email when a user is about to be banned. + +If automatic banning is disabled, a user is not banned automatically when they exceed the limit. However, users with the Owner role for the main group are still notified. You can use this setup to determine the correct values of the rate limit settings before enabling automatic banning. + +If automatic banning is enabled, users with the Owner role for the main group receive an email when a user is about to be banned, and the user is automatically banned from the group and its subgroups. + +## Configure Git abuse rate limiting + +1. On the left sidebar, select **Settings > Reporting**. +1. Update the Git abuse rate limit settings: + 1. Enter a number in the **Number of repositories** field, greater than or equal to `0` and less than or equal to `10,000`. This number specifies the maximum amount of unique repositories a user can download in the specified time period before they're banned. When set to `0`, Git abuse rate limiting is disabled. + 1. Enter a number in the **Reporting time period (seconds)** field, greater than or equal to `0` and less than or equal to `86,400` (10 days). This number specifies the time in seconds a user can download the maximum amount of repositories before they're banned. When set to `0`, Git abuse rate limiting is disabled. + 1. Optional. Exclude up to `100` users by adding them to the **Excluded users** field. Excluded users are not automatically banned. + 1. Optional. Turn on the **Automatically ban users from this namespace when they exceed the specified limits** toggle to enable automatic banning. +1. Select **Save changes**. + +## Unban a user + +1. On the left sidebar, select **Group information > Members**. +1. Select the **Banned** tab. +1. For the account you want to unban, select **Unban**. diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index 0a4d7f5eae4..9971457f2ac 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -58,7 +58,7 @@ To get the report: 1. Select the projects and date range you want to include in the report. 1. Select **Download test coverage data (.csv)**. -The projects dropdown shows up to 100 projects from your group. If the project you want to check is not in the dropdown list, you can select **All projects** to download the report for all projects in your group, including any projects that are not listed. There is a plan to improve this behavior in this [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/250684). +The projects dropdown list shows up to 100 projects from your group. If the project you want to check is not in the dropdown list, you can select **All projects** to download the report for all projects in your group, including any projects that are not listed. There is a plan to improve this behavior in this [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/250684). For each day that a coverage report was generated by a job in a project's pipeline, a row in the CSV includes: @@ -82,6 +82,6 @@ important to describe those, too. Think of things that may go wrong and include This is important to minimize requests for support, and to avoid doc comments with questions that you know someone might ask. -Each scenario can be a third-level heading, e.g. `### Getting error message X`. +Each scenario can be a third-level heading, for example `### Getting error message X`. If you have none to add when creating a doc, leave this section in place but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/roadmap/img/roadmap_blocked_icon_v15_5.png b/doc/user/group/roadmap/img/roadmap_blocked_icon_v15_5.png Binary files differindex 52130672e5a..625e4afc714 100644 --- a/doc/user/group/roadmap/img/roadmap_blocked_icon_v15_5.png +++ b/doc/user/group/roadmap/img/roadmap_blocked_icon_v15_5.png diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index 28431cb6b9a..3a9d0c833c1 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -164,6 +164,6 @@ important to describe those, too. Think of things that may go wrong and include This is important to minimize requests for support, and to avoid doc comments with questions that you know someone might ask. -Each scenario can be a third-level heading, e.g. `### Getting error message X`. +Each scenario can be a third-level heading, for example `### Getting error message X`. If you have none to add when creating a doc, leave this section in place but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/saml_sso/group_sync.md b/doc/user/group/saml_sso/group_sync.md index 3a50470ce50..001c73b6979 100644 --- a/doc/user/group/saml_sso/group_sync.md +++ b/doc/user/group/saml_sso/group_sync.md @@ -77,12 +77,8 @@ Users granted: ### Automatic member removal After a group sync, for GitLab subgroups, users who are not members of a mapped SAML -group are removed from the group. - -FLAG: -In [GitLab 15.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/364144), on GitLab.com, users in the top-level -group are assigned the [default membership role](index.md#role) rather than removed. This setting is enabled with the -`saml_group_sync_retain_default_membership` feature flag and can be configured by GitLab.com administrators only. +group are removed from the group. Users in the top-level group are assigned the +[default membership role](index.md#role). For example, in the following diagram: diff --git a/doc/user/group/saml_sso/img/member_enterprise_badge_v14_0.png b/doc/user/group/saml_sso/img/member_enterprise_badge_v14_0.png Binary files differdeleted file mode 100644 index f9534b14a51..00000000000 --- a/doc/user/group/saml_sso/img/member_enterprise_badge_v14_0.png +++ /dev/null diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index fa6f378e811..1c5e7ff0115 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -121,11 +121,18 @@ It can also help to compare the XML response from your provider with our [exampl > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/211962) in GitLab 13.8 with allowing group owners to not go through SSO. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/9152) in GitLab 13.11 with enforcing open SSO session to use Git if this setting is switched on. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/339888) in GitLab 14.7 to not enforce SSO checks for Git activity originating from CI/CD jobs. -> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/215155) in GitLab 15.5 [with a flag](../../../administration/feature_flags.md) named `transparent_sso_enforcement` to include transparent enforcement even when SSO enforcement is not enabled. Enabled on GitLab.com. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/215155) in GitLab 15.5 [with a flag](../../../administration/feature_flags.md) named `transparent_sso_enforcement` to include transparent enforcement even when SSO enforcement is not enabled. Disabled on GitLab.com. + +FLAG: +On self-managed GitLab, transparent SSO enforcement is unavailable. On GitLab.com, transparent SSO enforcement is unavailable and can be configured by GitLab.com administrators only. SSO is enforced when users access groups and projects in the organization's group hierarchy. Users can view other groups and projects without SSO sign in. -When SAML SSO is enabled, SSO is enforced for each user with an existing SAML identity. +SSO is enforced for each user with an existing SAML identity when the following is enabled: + +- SAML SSO. +- The `:transparent_sso_enforcement` feature flag. + A user has a SAML identity if one or both of the following are true: - They have signed in to GitLab by using their GitLab group's single sign-on URL. @@ -142,6 +149,15 @@ However, users are not prompted to sign in through SSO on each visit. GitLab che has authenticated through SSO. If it's been more than 1 day since the last sign-in, GitLab prompts the user to sign in again through SSO. +When the transparent SSO enforcement feature flag is enabled, SSO is enforced as follows: + +| Project/Group visibility | Enforce SSO setting | Member with identity | Member without identity | Non-member or not signed in | +|--------------------------|---------------------|--------------------| ------ |------------------------------| +| Private | Off | Enforced | Not enforced | No access | +| Private | On | Enforced | Enforced | No access | +| Public | Off | Enforced | Not enforced | Not enforced | +| Public | On | Enforced | Enforced | Not enforced | + An [issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/297389) to add a similar SSO requirement for API activity. SSO enforcement has the following effects when enabled: @@ -306,9 +322,11 @@ To migrate users to a new email domain, users must: ## User access and management -> SAML user provisioning [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/268142) in GitLab 13.7. +> - SAML user provisioning [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/268142) in GitLab 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325712) in GitLab 14.0, GitLab users created by [SAML SSO](index.md#user-access-and-management) or SCIM provisioning are displayed with an **Enterprise** badge in the **Members** view. -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, see the [user access and linking setup section on the SCIM page](scim_setup.md#user-access-and-linking-setup). +After 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, see [user access](scim_setup.md#user-access) on the SCIM page. When a user tries to sign in with Group SSO, GitLab attempts to find or create a user based on the following: @@ -422,7 +440,7 @@ To rescind a user's access to the group when only SAML SSO is configured, either 1. The GitLab.com group. - Use Group Sync at the top-level of your group to [automatically remove the user](group_sync.md#automatic-member-removal). -To rescind a user's access to the group when also using SCIM, refer to [Blocking access](scim_setup.md#blocking-access). +To rescind a user's access to the group when also using SCIM, refer to [Remove access](scim_setup.md#remove-access). ### Unlinking accounts diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 55990336a50..18af39f4271 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -168,13 +168,16 @@ Prerequisites: OneLogin provides a **GitLab (SaaS)** app in their catalog, which includes a SCIM integration. Contact OneLogin if you encounter issues. -## User access and linking setup +## User access -During the synchronization process, all of your users get GitLab accounts, welcoming them -to their respective groups, with an invitation email. When implementing SCIM provisioning, -you may want to warn your security-conscious employees about this email. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325712) in GitLab 14.0, GitLab users created by [SAML SSO](index.md#user-access-and-management) or SCIM provisioning are displayed with an **Enterprise** badge in the **Members** view. -The following diagram is a general outline on what happens when you add users to your SCIM app: +During the synchronization process, all new users: + +- Receive GitLab accounts. +- Are welcomed to their groups with an invitation email. You may want to warn your employees to expect this email. + +The following diagram describes what happens when you add users to your SCIM app: ```mermaid graph TD @@ -186,29 +189,38 @@ graph TD During provisioning: - Both primary and secondary emails are considered when checking whether a GitLab user account exists. -- Duplicate usernames are also handled, by adding suffix `1` upon user creation. For example, - due to already existing `test_user` username, `test_user1` is used. +- Duplicate usernames are handled by adding suffix `1` when creating the user. For example, if `test_user` already + exists, `test_user1` is used. If `test_user1` already exists, GitLab increments the suffix until an unused username + is found. -If [Group SAML](index.md) has been configured and you have an existing GitLab.com account, you can link your SCIM and SAML identities: +On subsequent visits, new and existing users can access groups either: -1. Update the [primary email](../../profile/index.md#change-your-primary-email) address in your GitLab.com user account to match the - user profile email address in your identity provider. -1. [Link your SAML identity](index.md#linking-saml-to-your-existing-gitlabcom-account). +- Through the identity provider's dashboard. +- By visiting links directly. -We recommend users do this prior to turning on sync, because while synchronization is active, there may be provisioning errors for existing users. +For role information, see the [Group SAML](index.md#user-access-and-management) page. -New users and existing users on subsequent visits can access the group through the identity provider's dashboard or by visiting links directly. +### Link SCIM and SAML identities -[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. +If [group SAML](index.md) is configured and you have an existing GitLab.com account, users can link their SCIM and SAML +identities. Users should do this before synchronization is turned on because there can be provisioning errors for +existing users when synchronization is active. + +To link your SCIM and SAML identities: + +1. Update the [primary email](../../profile/index.md#change-your-primary-email) address in your GitLab.com user account + to match the user profile email address in your identity provider. +1. [Link your SAML identity](index.md#linking-saml-to-your-existing-gitlabcom-account). - +### Remove access -For role information, see the [Group SAML page](index.md#user-access-and-management) +Remove or deactivate a user on the identity provider to remove their access to: -### Blocking access +- The top-level group. +- All subgroups and projects. -To rescind access to the top-level group, all subgroups, and projects, remove or deactivate the user -on the identity provider. After the identity provider performs a sync, based on its configured schedule, the user's membership is revoked and they lose access. +After the identity provider performs a sync based on its configured schedule, the user's membership is revoked and they +lose access. NOTE: Deprovisioning does not delete the GitLab user account. diff --git a/doc/user/group/saml_sso/troubleshooting.md b/doc/user/group/saml_sso/troubleshooting.md index bde5ed1762a..7dafd2c5075 100644 --- a/doc/user/group/saml_sso/troubleshooting.md +++ b/doc/user/group/saml_sso/troubleshooting.md @@ -19,9 +19,10 @@ SAML responses are base64 encoded, so we recommend the following browser plugins - [SAML-tracer](https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/) for Firefox. - [SAML Message Decoder](https://chrome.google.com/webstore/detail/saml-message-decoder/mpabchoaimgbdbbjjieoaeiibojelbhm?hl=en) for Chrome. -Specific attention should be paid to: +Pay specific attention to: -- The NameID, which we use to identify which user is signing in. If the user has previously signed in, this [must match the value we have stored](#verifying-nameid). +- The `NameID`, which we use to identify which user is signing in. If the user has previously signed in, this + [must match the value we have stored](#verify-nameid). - The presence of a `X509Certificate`, which we require to verify the response signature. - The `SubjectConfirmation` and `Conditions`, which can cause errors if misconfigured. @@ -32,7 +33,7 @@ using an identity provider. To generate a SAML Response: -1. Install one of the browser debugging tools previously mentioned. +1. Install one of the [browser debugging tools](#saml-debugging-tools). 1. Open a new browser tab. 1. Open the SAML tracer console: - Chrome: On a context menu on the page, select **Inspect**, then select the **SAML** tab in the opened developer @@ -43,16 +44,17 @@ To generate a SAML Response: [example SAML response](index.md#example-saml-response). 1. Within the SAML tracer, select the **Export** icon to save the response in JSON format. -## GitLab SAML Testing Environments +## Testing GitLab SAML -To troubleshoot, [a complete GitLab with SAML testing environment using Docker compose](https://gitlab.com/gitlab-com/support/toolbox/replication/tree/master/compose_files) -is available. +You can use one of the following to troubleshoot SAML: -If you only require a SAML provider for testing, a [quick start guide to start a Docker container](../../../administration/troubleshooting/test_environments.md#saml) with a plug and play SAML 2.0 Identity Provider (identity provider) is available. +- A [complete GitLab with SAML testing environment using Docker compose](https://gitlab.com/gitlab-com/support/toolbox/replication/tree/master/compose_files). +- A [quick start guide to start a Docker container](../../../administration/troubleshooting/test_environments.md#saml) + with a plug and play SAML 2.0 identity provider if you only require a SAML provider. +- A local environment by + [enabling SAML for groups on a self-managed instance](../../../integration/saml.md#configuring-group-saml-on-a-self-managed-gitlab-instance). -You can test the SaaS feature locally by [enabling SAML for groups on a self-managed instance](../../../integration/saml.md#configuring-group-saml-on-a-self-managed-gitlab-instance). - -## Verifying configuration +## Verify configuration For convenience, we've included some [example resources](../../../user/group/saml_sso/example_saml_config.md) used by our Support Team. While they may help you verify the SAML app configuration, they are not guaranteed to reflect the current state of third-party products. @@ -82,7 +84,7 @@ in case the customer has [configured SAML Group Sync](group_sync.md): - `json.class`: `GroupSamlGroupSyncWorker` - `json.args`: `<user ID> or <group ID>` -In the relevant log entry, the: +In the relevant log entry, the: - `json.args` are in the form `<userID>, <group ID>, [group link ID 1, group link ID 2, ..., group link ID N]`. @@ -148,13 +150,13 @@ If you do not wish to use that GitLab user with the SAML login, you can [unlink ### Message: "SAML authentication failed: User has already been taken" -The user that you're signed in with already has SAML linked to a different identity, or the NameID value has changed. +The user that you're signed in with already has SAML linked to a different identity, or the `NameID` value has changed. Here are possible causes and solutions: | Cause | Solution | | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | You've tried to link multiple SAML identities to the same user, for a given identity provider. | Change the identity that you sign in with. To do so, [unlink the previous SAML identity](index.md#unlinking-accounts) from this GitLab account before attempting to sign in again. | -| The NameID changes every time the user requests SSO identification | [Check the NameID](#verifying-nameid) is not set with `Transient` format, or the NameID is not changing on subsequent requests.| +| The `NameID` changes every time the user requests SSO identification | [Check the `NameID`](#verify-nameid) is not set with `Transient` format, or the `NameID` is not changing on subsequent requests.| ### Message: "SAML authentication failed: Email has already been taken" @@ -171,9 +173,9 @@ User accounts are created in one of the following ways: ### Message: "SAML authentication failed: Extern UID has already been taken, User has already been taken" -Getting both of these errors at the same time suggests the NameID capitalization provided by the identity provider didn't exactly match the previous value for that user. +Getting both of these errors at the same time suggests the `NameID` capitalization provided by the identity provider didn't exactly match the previous value for that user. -This can be prevented by configuring the NameID to return a consistent value. Fixing this for an individual user involves changing the identifier for the user. For GitLab.com, the user needs to [unlink their SAML from the GitLab account](index.md#unlinking-accounts). +This can be prevented by configuring the `NameID` to return a consistent value. Fixing this for an individual user involves changing the identifier for the user. For GitLab.com, the user needs to [unlink their SAML from the GitLab account](index.md#unlinking-accounts). ### Message: "Request to link SAML account must be authorized" @@ -196,15 +198,15 @@ to [reset their password](https://gitlab.com/users/password/new) if both: ## Other user sign in issues -### Verifying NameID +### Verify `NameID` -In troubleshooting, any authenticated user can use the API to verify the NameID GitLab already has linked to the user by visiting [`https://gitlab.com/api/v4/user`](https://gitlab.com/api/v4/user) and checking the `extern_uid` under identities. +In troubleshooting, any authenticated user can use the API to verify the `NameID` GitLab already has linked to their user by visiting [`https://gitlab.com/api/v4/user`](https://gitlab.com/api/v4/user) and checking the `extern_uid` under identities. For self-managed, administrators can use the [users API](../../../api/users.md) to see the same information. When using SAML for groups, group members of a role with the appropriate permissions can make use of the [members API](../../../api/members.md) to view group SAML identity information for members of the group. -This can then be compared to the NameID being sent by the identity provider by decoding the message with a [SAML debugging tool](#saml-debugging-tools). We require that these match to identify users. +This can then be compared to the `NameID` being sent by the identity provider by decoding the message with a [SAML debugging tool](#saml-debugging-tools). We require that these match to identify users. ### Stuck in a login "loop" diff --git a/doc/user/group/saml_sso/troubleshooting_scim.md b/doc/user/group/saml_sso/troubleshooting_scim.md index 6f8aed4b386..22562c51e9e 100644 --- a/doc/user/group/saml_sso/troubleshooting_scim.md +++ b/doc/user/group/saml_sso/troubleshooting_scim.md @@ -8,93 +8,120 @@ info: To determine the technical writer assigned to the Stage/Group associated w This section contains possible solutions for problems you might encounter. -## How come I can't add a user after I removed them? +## User cannot be added after they are removed -As outlined in the [Blocking access section](scim_setup.md#blocking-access), when you remove a user, they are removed from the group. However, their account is not deleted. +When you remove a user, they are removed from the group but their account is not deleted +(see [remove access](scim_setup.md#remove-access)). When the user is added back to the SCIM app, GitLab cannot create a new user because the user already exists. -Solution: Have a user sign in directly to GitLab, then [manually link](scim_setup.md#user-access-and-linking-setup) their account. +To solve this problem: -## How do I diagnose why a user is unable to sign in +1. Have the user sign in directly to GitLab. +1. [Manually link](scim_setup.md#link-scim-and-saml-identities) their account. -Ensure that the user has been added to the SCIM app. +## User cannot sign in -If you receive "User is not linked to a SAML account", then most likely the user already exists in GitLab. Have the user follow the [User access and linking setup](scim_setup.md#user-access-and-linking-setup) instructions. +The following are possible solutions for problems where users cannot sign in: -The **Identity** (`extern_uid`) value stored by GitLab is updated by SCIM whenever `id` or `externalId` changes. Users cannot sign in unless the GitLab Identity (`extern_uid`) value matches the `NameId` sent by SAML. +- Ensure that the user was added to the SCIM app. +- If you receive the `User is not linked to a SAML account` error, the user probably already exists in GitLab. Have the + user follow the [Link SCIM and SAML identities](scim_setup.md#link-scim-and-saml-identities) instructions. +- The **Identity** (`extern_uid`) value stored by GitLab is updated by SCIM whenever `id` or `externalId` changes. Users + cannot sign in unless the GitLab Identity (`extern_uid`) value matches the `NameId` sent by SAML. This value is also + used by SCIM to match users on the `id`, and is updated by SCIM whenever the `id` or `externalId` values change. +- The SCIM `id` and SCIM `externalId` must be configured to the same value as the SAML `NameId`. You can trace SAML responses + using [debugging tools](troubleshooting.md#saml-debugging-tools), and check any errors against the + [SAML troubleshooting](troubleshooting.md) information. -This value is also used by SCIM to match users on the `id`, and is updated by SCIM whenever the `id` or `externalId` values change. +## Unsure if user's SAML `NameId` matches the SCIM `externalId` -It is important that this SCIM `id` and SCIM `externalId` are configured to the same value as the SAML `NameId`. SAML responses can be traced using [debugging tools](troubleshooting.md#saml-debugging-tools), and any errors can be checked against our [SAML troubleshooting docs](troubleshooting.md). +To check if a user's SAML `NameId` matches their SCIM `externalId`: -## How do I verify user's SAML NameId matches the SCIM externalId +- Administrators can use the Admin Area to [list SCIM identities for a user](../../admin_area/index.md#user-identities). +- Group owners can see the list of users and the identifier stored for each user in the group SAML SSO Settings page. +- You can use the [SCIM API](../../../api/scim.md) to manually retrieve the `external_uid` GitLab has stored for users and compare the value for each user from the [SAML API](../../../api/saml.md) . +- Have the user use a [SAML Tracer](troubleshooting.md#saml-debugging-tools) and compare the `external_uid` to + the value returned as the SAML `NameId`. -Administrators can use the Admin Area to [list SCIM identities for a user](../../admin_area/index.md#user-identities). +## Mismatched SCIM `extern_uid` and SAML `NameId` -Group owners can see the list of users and the `externalId` stored for each user in the group SAML SSO Settings page. +Whether the value was changed or you need to map to a different field, the following must map to the same field: -A possible alternative is to use the [SCIM API](../../../api/scim.md) to manually retrieve the `externalId` we have stored for users, also called the `external_uid` or `NameId`. +- `id` +- `externalId` +- `NameId` -To see how the `external_uid` compares to the value returned as the SAML NameId, you can have the user use a [SAML Tracer](troubleshooting.md#saml-debugging-tools). - -## Update or fix mismatched SCIM externalId and 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 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. +If the GitLab `extern_uid` doesn't match the SAML `NameId`, it must be updated for the user to sign in. Your identity +provider should be configured to do this update. In some cases the identity provider cannot do the update, for example +when a user lookup fails because of 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, +GitLab uses these IDs to look up users. If the identity provider does not know the current values for these fields, that provider may create duplicate users. -If the `externalId` for a user is not correct, and also doesn't match the SAML NameID, -you can address the problem in the following ways: +If the `extern_uid` for a user is not correct, and also doesn't match the SAML `NameID`, either: + +- Have users unlink and relink themselves, based on the + [SAML authentication failed: User has already been taken](troubleshooting.md#message-saml-authentication-failed-user-has-already-been-taken) + section. +- Unlink all users simultaneously by removing all users from the SCIM app while provisioning is turned on. +- Use the [SCIM API](../../../api/scim.md) to manually correct the `extern_uid` stored for users to match the SAML + `NameId`. To look up a user, you must know the desired value that matches the `NameId` as well as the current + `extern_uid`. -- You can have users unlink and relink themselves, based on the ["SAML authentication failed: User has already been taken"](troubleshooting.md#message-saml-authentication-failed-user-has-already-been-taken) section. -- You can unlink all users simultaneously, by removing all users from the SAML app while provisioning is turned on. -- Use the [SCIM API](../../../api/scim.md) to manually correct the `externalId` stored for users to match the SAML `NameId`. - To look up a user, you need to know the desired value that matches the `NameId` as well as the current `externalId`. +You must not: -It is important not to update these to incorrect values, since this causes users to be unable to sign in. It is also important not to assign a value to the wrong user, as this causes users to get signed into the wrong account. +- Update these to incorrect values because this causes users to be unable to sign in. +- Assign a value to the wrong user because this causes users to be signed in to the wrong account. -## I need to change my SCIM app +## Change SCIM app -Individual users can follow the instructions in the ["SAML authentication failed: User has already been taken"](index.md#change-the-saml-app) section. +When the SCIM app changes: -Alternatively, users can be removed from the SCIM app which de-links all removed users. Sync can then be turned on for the new SCIM app to [link existing users](scim_setup.md#user-access-and-linking-setup). +- Users can follow the instructions in the [Change the SAML app](index.md#change-the-saml-app) section. +- Administrators of the identity provider can: + 1. Remove users from the SCIM app, which unlinks all removed users. + 1. Turn on sync for the new SCIM app to [link existing users](scim_setup.md#link-scim-and-saml-identities). -## The SCIM app is throwing `"User has already been taken","status":409` error message +## SCIM app returns `"User has already been taken","status":409` error 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 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 the [SCIM API](../../../api/scim.md) 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) to update the SCIM `id` for the user on GitLab.com. | +- SAML and SCIM identity mismatch. To solve this problem: + 1. [Verify that the user's SAML `NameId` matches the SCIM `extern_uid`](#unsure-if-users-saml-nameid-matches-the-scim-externalid). + 1. [Update or fix the mismatched SCIM `extern_uid` and SAML `NameId`](#mismatched-scim-extern_uid-and-saml-nameid). +- SCIM identity mismatch between GitLab and the identity provider SCIM app. To solve this problem: + 1. Use the [SCIM API](../../../api/scim.md), which displays the user's `extern_uid` stored in GitLab and compares it with the user `externalId` in + the SCIM app. + 1. Use the same SCIM API to update the SCIM `extern_uid` 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 internal -[SCIM API](../../../development/internal_api/index.md#scim-api): +[Kibana](https://about.gitlab.com/handbook/support/workflows/kibana.html#using-kibana). Use the following filters based +on the internal [SCIM API](../../../development/internal_api/index.md#scim-api): - `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. +In a relevant log entry, the `json.params.value` shows the values of SCIM parameters GitLab receives. Use these values +to verify if SCIM parameters configured in an identity provider's SCIM app are communicated to GitLab as intended. -## Azure +For example, 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 do not match +the SCIM app configuration. -### How do I verify my SCIM configuration is correct? +## Azure Active Directory -Review the following: +The following troubleshooting information is specifically for SCIM provisioned through Azure Active Directory. -- Ensure that the SCIM value for `id` matches the SAML value for `NameId`. -- Ensure that the SCIM value for `externalId` matches the SAML value for `NameId`. +### Verify my SCIM configuration is correct + +Ensure that: + +- The matching precedence for `externalId` is 1. +- The SCIM value for `externalId` matches the SAML value for `NameId`. Review the following SCIM parameters for sensible values: @@ -102,28 +129,37 @@ Review the following SCIM parameters for sensible values: - `displayName` - `emails[type eq "work"].value` -### Testing Azure connection: invalid credentials +### `invalid credentials` error when testing connection + +When testing the connection, you may encounter an error: + +```plaintext +You appear to have entered invalid credentials. Please confirm +you are using the correct information for an administrative account +``` -When testing the connection, you may encounter an error: **You appear to have entered invalid credentials. Please confirm you are using the correct information for an administrative account**. If `Tenant URL` and `secret token` are correct, check whether your group path contains characters that may be considered invalid JSON primitives (such as `.`). Removing such characters from the group path typically resolves the error. +If `Tenant URL` and `secret token` are correct, check whether your group path contains characters that may be considered +invalid JSON primitives (such as `.`). Removing or URL encoding these characters in the group path typically resolves the error. -### (Field) can't be blank sync error +### `(Field) can't be blank` sync error -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.` +When checking the Audit Events for the provisioning, you sometimes see a `Namespace can't be blank, Name can't be blank, +and User can't be blank.` error. -This is likely caused because not all required fields (such as first name and last name) are present for all users being mapped. +This error can occur because not all required fields (such as first name and last name) are present for all users +being mapped. As a workaround, try an alternate mapping: -1. Follow the Azure mapping instructions from above. +1. Follow the [Azure mapping instructions](scim_setup.md#configure-attribute-mappings). 1. Delete the `name.formatted` target attribute entry. 1. Change the `displayName` source attribute to have `name.formatted` target attribute. -### Failed to match an entry in the source and target systems Group 'Group-Name' +### `Failed to match an entry in the source and target systems Group 'Group-Name'` error -Group provisioning in Azure can fail with the `Failed to match an entry in the source and target systems Group 'Group-Name'` error message, -and the error response can include a HTML result of the GitLab URL `https://gitlab.com/users/sign_in`. +Group provisioning in Azure can fail with the `Failed to match an entry in the source and target systems Group 'Group-Name'` +error. The error response can include a HTML result of the GitLab URL `https://gitlab.com/users/sign_in`. -This error is harmless and occurs because Group provisioning was turned on but GitLab SCIM integration does not support it nor require it. To -remove the error, follow the instructions in the Azure configuration guide to disable the option -[`Synchronize Azure Active Directory Groups to AppName`](scim_setup.md#configure-azure-active-directory). +This error is harmless and occurs because group provisioning was turned on but GitLab SCIM integration does not support +it nor require it. To remove the error, follow the instructions in the Azure configuration guide to disable the option +to [synchronize Azure Active Directory groups to AppName](scim_setup.md#configure-azure-active-directory). diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 58f5e476f26..95c8e60af5d 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -212,6 +212,6 @@ important to describe those, too. Think of things that may go wrong and include This is important to minimize requests for support, and to avoid doc comments with questions that you know someone might ask. -Each scenario can be a third-level heading, e.g. `### Getting error message X`. +Each scenario can be a third-level heading, for example `### Getting error message X`. If you have none to add when creating a doc, leave this section in place but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index fcf4189aa32..980618ac3ae 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -104,7 +104,7 @@ The **Overview** dashboard shows the following key metrics that measure team per > - [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. -The value stream analytics **Overview** dashboard displays the following [DORA](../../../user/analytics/index.md) metrics: +The value stream analytics **Overview** dashboard displays the following [DORA](../../../user/analytics/dora_metrics.md) metrics: - Deployment Frequency. - Lead time for changes. |
