summaryrefslogtreecommitdiff
path: root/doc/user/group
diff options
context:
space:
mode:
Diffstat (limited to 'doc/user/group')
-rw-r--r--doc/user/group/bulk_editing/img/bulk-editing.pngbin0 -> 99844 bytes
-rw-r--r--doc/user/group/bulk_editing/index.md31
-rw-r--r--doc/user/group/clusters/index.md10
-rw-r--r--doc/user/group/contribution_analytics/index.md3
-rw-r--r--doc/user/group/custom_project_templates.md2
-rw-r--r--doc/user/group/epics/img/bulk_editing.pngbin0 -> 72912 bytes
-rw-r--r--doc/user/group/epics/img/button_reopen_epic.pngbin14153 -> 14148 bytes
-rw-r--r--doc/user/group/epics/img/containing_epic.pngbin159939 -> 159919 bytes
-rw-r--r--doc/user/group/epics/img/epic_view.pngbin176759 -> 176740 bytes
-rw-r--r--doc/user/group/epics/index.md20
-rw-r--r--doc/user/group/img/group_file_template_dropdown.pngbin9519 -> 9516 bytes
-rw-r--r--doc/user/group/img/group_file_template_settings.pngbin6217 -> 6210 bytes
-rw-r--r--doc/user/group/index.md73
-rw-r--r--doc/user/group/insights/img/insights_example_stacked_bar_chart.pngbin86062 -> 40798 bytes
-rw-r--r--doc/user/group/insights/img/insights_group_configuration.pngbin24107 -> 14125 bytes
-rw-r--r--doc/user/group/insights/img/insights_sidebar_link.pngbin18826 -> 12327 bytes
-rw-r--r--doc/user/group/roadmap/img/roadmap_view.pngbin49774 -> 49757 bytes
-rw-r--r--doc/user/group/saml_sso/img/group_saml_configuration_information.pngbin50435 -> 16489 bytes
-rw-r--r--doc/user/group/saml_sso/img/group_saml_settings.pngbin89399 -> 50300 bytes
-rw-r--r--doc/user/group/saml_sso/img/scim_advanced.pngbin21568 -> 6920 bytes
-rw-r--r--doc/user/group/saml_sso/img/scim_attribute_mapping.pngbin95420 -> 34642 bytes
-rw-r--r--doc/user/group/saml_sso/img/scim_name_identifier_mapping.pngbin0 -> 59409 bytes
-rw-r--r--doc/user/group/saml_sso/img/scim_provisioning_status.pngbin0 -> 7756 bytes
-rw-r--r--doc/user/group/saml_sso/img/scim_token.pngbin154318 -> 57095 bytes
-rw-r--r--doc/user/group/saml_sso/img/unlink_group_saml.pngbin27077 -> 9399 bytes
-rw-r--r--doc/user/group/saml_sso/index.md21
-rw-r--r--doc/user/group/saml_sso/scim_setup.md118
-rw-r--r--doc/user/group/subgroups/index.md64
28 files changed, 244 insertions, 98 deletions
diff --git a/doc/user/group/bulk_editing/img/bulk-editing.png b/doc/user/group/bulk_editing/img/bulk-editing.png
new file mode 100644
index 00000000000..ca1662a781b
--- /dev/null
+++ b/doc/user/group/bulk_editing/img/bulk-editing.png
Binary files differ
diff --git a/doc/user/group/bulk_editing/index.md b/doc/user/group/bulk_editing/index.md
new file mode 100644
index 00000000000..ea48b0b9fef
--- /dev/null
+++ b/doc/user/group/bulk_editing/index.md
@@ -0,0 +1,31 @@
+# Bulk editing issues, merge requests, and epics at the group level **(PREMIUM)**
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7249) for issues in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/12719) for merge requests in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7250) for epics in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2.
+
+## Editing milestones and labels
+
+> **Notes:**
+>
+> - A permission level of `Reporter` or higher is required in order to manage issues.
+> - A permission level of `Developer` or higher is required in order to manage merge requests.
+> - A permission level of `Reporter` or higher is required in order to manage epics.
+
+By using the bulk editing feature:
+
+- Milestones can be updated simultaneously across multiple issues or merge requests.
+- Labels can be updated simultaneously across multiple issues, merge requests, or epics.
+
+![Bulk editing](img/bulk-editing.png)
+
+To bulk update group issues, merge requests, or epics:
+
+1. Navigate to the issues, merge requests, or epics list.
+1. Click **Edit issues**, **Edit merge requests**, or **Edit epics**.
+ - This will open a sidebar on the right-hand side where editable fields
+ for milestones and labels will be displayed.
+ - Checkboxes will also appear beside each issue, merge request, or epic.
+1. Check the checkbox beside each issue, merge request, or epic to be edited.
+1. Select the desired new values from the sidebar.
+1. Click **Update all**.
diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md
index 0dffc216f8e..d41f44f85cc 100644
--- a/doc/user/group/clusters/index.md
+++ b/doc/user/group/clusters/index.md
@@ -5,7 +5,6 @@ type: reference
# Group-level Kubernetes clusters
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/34758) in GitLab 11.6.
-> Group Cluster integration is currently in [Beta](https://about.gitlab.com/handbook/product/#alpha-beta-ga).
## Overview
@@ -87,7 +86,7 @@ The domain should have a wildcard DNS configured to the Ingress IP address.
When adding more than one Kubernetes cluster to your project, you need to differentiate
them with an environment scope. The environment scope associates clusters with
[environments](../../../ci/environments.md) similar to how the
-[environment-specific variables](../../../ci/variables/README.md#limiting-environment-scopes-of-environment-variables-premium)
+[environment-specific variables](../../../ci/variables/README.md#limiting-environment-scopes-of-environment-variables)
work.
While evaluating which environment matches the environment scope of a
@@ -138,6 +137,13 @@ The result will then be:
- The Staging cluster will be used for the `deploy to staging` job.
- The Production cluster will be used for the `deploy to production` job.
+## Security of Runners
+
+For important information about securely configuring GitLab Runners, see
+[Security of
+Runners](../../project/clusters/index.md#security-of-gitlab-runners)
+documentation for project-level clusters.
+
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md
index 2d37fc375db..a0dd5cd497d 100644
--- a/doc/user/group/contribution_analytics/index.md
+++ b/doc/user/group/contribution_analytics/index.md
@@ -4,7 +4,8 @@ type: reference
# Contribution Analytics **(STARTER)**
-> Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3.
+> - Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3090) for subgroups in GitLab 12.2.
## Overview
diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md
index 8a85c375490..7cdba8cf2b5 100644
--- a/doc/user/group/custom_project_templates.md
+++ b/doc/user/group/custom_project_templates.md
@@ -24,7 +24,7 @@ project in the group will be available to every logged in user.
However, private projects will be available only if the user is a member of the project.
NOTE: **Note:**
-Projects of nested subgroups of a selected template source cannot be used.
+Only direct subgroups can be set as the template source. Projects of nested subgroups of a selected template source cannot be used.
Repository and database information that are copied over to each new project are
identical to the data exported with [GitLab's Project Import/Export](../project/settings/import_export.md).
diff --git a/doc/user/group/epics/img/bulk_editing.png b/doc/user/group/epics/img/bulk_editing.png
new file mode 100644
index 00000000000..85610bef83e
--- /dev/null
+++ b/doc/user/group/epics/img/bulk_editing.png
Binary files differ
diff --git a/doc/user/group/epics/img/button_reopen_epic.png b/doc/user/group/epics/img/button_reopen_epic.png
index 7a953189270..9d1be88549d 100644
--- a/doc/user/group/epics/img/button_reopen_epic.png
+++ b/doc/user/group/epics/img/button_reopen_epic.png
Binary files differ
diff --git a/doc/user/group/epics/img/containing_epic.png b/doc/user/group/epics/img/containing_epic.png
index 5ed693e6d6a..dc13d55e2bc 100644
--- a/doc/user/group/epics/img/containing_epic.png
+++ b/doc/user/group/epics/img/containing_epic.png
Binary files differ
diff --git a/doc/user/group/epics/img/epic_view.png b/doc/user/group/epics/img/epic_view.png
index dbda98e4351..c55d302ec29 100644
--- a/doc/user/group/epics/img/epic_view.png
+++ b/doc/user/group/epics/img/epic_view.png
Binary files differ
diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md
index 601ffd4947b..5968b91c9b7 100644
--- a/doc/user/group/epics/index.md
+++ b/doc/user/group/epics/index.md
@@ -97,6 +97,22 @@ have a [start or due date](#start-date-and-due-date), then you can see a
Drag and drop to reorder issues and child epics. New issues and child epics added to an epic appear at the top of the list.
+## Updating epics
+
+### Using bulk editing
+
+To apply labels across multiple epics:
+
+1. Go to the Epics list.
+1. Click **Edit epics**.
+ - Checkboxes will appear beside each epic.
+ - A sidebar on the right-hand side will appear, with an editable field for labels.
+1. Check the checkbox beside each epic to be edited.
+1. Select the desired labels.
+1. Click **Update all**.
+
+![bulk editing](img/bulk_editing.png)
+
## Deleting an epic
NOTE: **Note:**
@@ -205,12 +221,12 @@ You may also consult the [group permissions table][permissions].
These text fields also fully support
[GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm).
-## Comment, or start a discussion
+## Comment, or start a thread
Once you wrote your comment, you can either:
- Click "Comment" and your comment will be published.
-- Click "Start discussion": start a thread within that epic's thread to discuss specific points.
+- Click "Start thread": start a thread within that epic's discussion to discuss specific points.
## Award emoji
diff --git a/doc/user/group/img/group_file_template_dropdown.png b/doc/user/group/img/group_file_template_dropdown.png
index d9caae1a223..f0586772218 100644
--- a/doc/user/group/img/group_file_template_dropdown.png
+++ b/doc/user/group/img/group_file_template_dropdown.png
Binary files differ
diff --git a/doc/user/group/img/group_file_template_settings.png b/doc/user/group/img/group_file_template_settings.png
index ca42f7726db..5e07974bc86 100644
--- a/doc/user/group/img/group_file_template_settings.png
+++ b/doc/user/group/img/group_file_template_settings.png
Binary files differ
diff --git a/doc/user/group/index.md b/doc/user/group/index.md
index db348c678eb..864f1a397d5 100644
--- a/doc/user/group/index.md
+++ b/doc/user/group/index.md
@@ -78,6 +78,10 @@ Issues and merge requests are part of projects. For a given group, you can view
[issues](../project/issues/index.md#issues-list) and [merge requests](../project/merge_requests/index.md#merge-requests-per-group) across all projects in that group,
together in a single list view.
+### Bulk editing issues and merge requests
+
+For details, see [bulk editing issues and merge requests](../group/bulk_editing/index.md).
+
## Create a new group
> For a list of words that are not allowed to be used as group names see the
@@ -87,11 +91,11 @@ To create a new Group, either:
- In the top menu, click **Groups** and then **Your Groups**, and click the green button **New group**.
- ![new group from groups page](img/new_group_from_groups.png)
+ ![new group from groups page](img/new_group_from_groups.png)
- Or, in the top menu, expand the `plus` sign and choose **New group**.
- ![new group from elsewhere](img/new_group_from_other_pages.png)
+ ![new group from elsewhere](img/new_group_from_other_pages.png)
Add the following information:
@@ -100,15 +104,15 @@ Add the following information:
1. The **Group name** will automatically populate the URL. Optionally, you can change it.
This is the name that displays in group views.
The name can contain only:
- - Alphanumeric characters
- - Underscores
- - Dashes and dots
- - Spaces
+ - Alphanumeric characters
+ - Underscores
+ - Dashes and dots
+ - Spaces
1. The **Group URL** is the namespace under which your projects will be hosted.
The URL can contain only:
- - Alphanumeric characters
- - Underscores
- - Dashes and dots (it cannot start with dashes or end in a dot)
+ - Alphanumeric characters
+ - Underscores
+ - Dashes and dots (it cannot start with dashes or end in a dot)
1. Optionally, you can add a brief description to tell others
what this group is about.
1. Optionally, choose an avatar for your group.
@@ -162,12 +166,12 @@ There are two different ways to add a new project to a group:
- Select a group, and then click **New project**. You can then continue [creating your project](../../gitlab-basics/create-project.md).
- ![New project](img/create_new_project_from_group.png)
+ ![New project](img/create_new_project_from_group.png)
- While you are creating a project, select a group namespace
you've already created from the dropdown menu.
- ![Select group](img/select_group_dropdown.png)
+ ![Select group](img/select_group_dropdown.png)
### Default project-creation level
@@ -327,7 +331,7 @@ This will disable the option for all users who previously had permissions to
operate project memberships, so no new users can be added. Furthermore, any
request to add a new user to a project through API will not be possible.
-#### IP access restriction **(ULTIMATE)**
+#### IP access restriction **(ULTIMATE ONLY)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/1985) in
[GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0.
@@ -338,7 +342,7 @@ underlying projects, issues, etc, by IP address. This can help ensure that
particular content doesn't leave the premises, while not blocking off access to
the entire instance.
-Add whitelisted IP subnet using CIDR notation to the group settings and anyone
+Add one or more whitelisted IP subnets using CIDR notation in comma separated format to the group settings and anyone
coming from a different IP address won't be able to access the restricted
content.
@@ -346,6 +350,38 @@ Restriction currently applies to UI, API access is not restricted.
To avoid accidental lock-out, admins and group owners are are able to access
the group regardless of the IP restriction.
+#### Allowed domain restriction **(PREMIUM ONLY)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7297) in
+[GitLab Premium](https://about.gitlab.com/pricing/) 12.2.
+
+You can restrict access to groups and their underlying projects by
+allowing only users with email addresses in particular domains to be added to the group.
+
+Add email domains you want to whitelist and users with emails from different
+domains won't be allowed to be added to this group.
+
+Some domains cannot be restricted. These are the most popular public email domains, such as:
+
+- `gmail.com`
+- `yahoo.com`
+- `hotmail.com`
+- `aol.com`
+- `msn.com`
+- `hotmail.co.uk`
+- `hotmail.fr`
+- `live.com`
+- `outlook.com`
+- `icloud.com`
+
+To enable this feature:
+
+1. Navigate to the group's **Settings > General** page.
+1. Expand the **Permissions, LFS, 2FA** section, and enter domain name into **Restrict membership by email** field.
+1. Click **Save changes**.
+
+This will enable the domain-checking for all new users added to the group from this moment on.
+
#### Group file templates **(PREMIUM)**
Group file templates allow you to share a set of templates for common file
@@ -375,6 +411,17 @@ To enable this feature, navigate to the group settings page, expand the
Define project templates at a group level by setting a group as the template source.
[Learn more about group-level project templates](custom_project_templates.md).
+#### Disabling email notifications
+
+You can disable all email notifications related to the group, which also includes
+it's subgroups and projects.
+
+To enable this feature:
+
+1. Navigate to the group's **Settings > General** page.
+1. Expand the **Permissions, LFS, 2FA** section, and select **Disable email notifications**.
+1. Click **Save changes**.
+
### Advanced settings
- **Projects**: View all projects within that group, add members to each project,
diff --git a/doc/user/group/insights/img/insights_example_stacked_bar_chart.png b/doc/user/group/insights/img/insights_example_stacked_bar_chart.png
index 791d0e4bcdf..0e338b99e4c 100644
--- a/doc/user/group/insights/img/insights_example_stacked_bar_chart.png
+++ b/doc/user/group/insights/img/insights_example_stacked_bar_chart.png
Binary files differ
diff --git a/doc/user/group/insights/img/insights_group_configuration.png b/doc/user/group/insights/img/insights_group_configuration.png
index 0af0073e448..d181a1e94c3 100644
--- a/doc/user/group/insights/img/insights_group_configuration.png
+++ b/doc/user/group/insights/img/insights_group_configuration.png
Binary files differ
diff --git a/doc/user/group/insights/img/insights_sidebar_link.png b/doc/user/group/insights/img/insights_sidebar_link.png
index 64bbd1fc4d3..f7b0c2daae3 100644
--- a/doc/user/group/insights/img/insights_sidebar_link.png
+++ b/doc/user/group/insights/img/insights_sidebar_link.png
Binary files differ
diff --git a/doc/user/group/roadmap/img/roadmap_view.png b/doc/user/group/roadmap/img/roadmap_view.png
index ff41a2e0441..2be3849ba1b 100644
--- a/doc/user/group/roadmap/img/roadmap_view.png
+++ b/doc/user/group/roadmap/img/roadmap_view.png
Binary files differ
diff --git a/doc/user/group/saml_sso/img/group_saml_configuration_information.png b/doc/user/group/saml_sso/img/group_saml_configuration_information.png
index 98b83d0cb0f..e03c50ceb01 100644
--- a/doc/user/group/saml_sso/img/group_saml_configuration_information.png
+++ b/doc/user/group/saml_sso/img/group_saml_configuration_information.png
Binary files differ
diff --git a/doc/user/group/saml_sso/img/group_saml_settings.png b/doc/user/group/saml_sso/img/group_saml_settings.png
index d95acb5075f..487be4faeba 100644
--- a/doc/user/group/saml_sso/img/group_saml_settings.png
+++ b/doc/user/group/saml_sso/img/group_saml_settings.png
Binary files differ
diff --git a/doc/user/group/saml_sso/img/scim_advanced.png b/doc/user/group/saml_sso/img/scim_advanced.png
index 3b70e3fbe83..c9e095dc89a 100644
--- a/doc/user/group/saml_sso/img/scim_advanced.png
+++ b/doc/user/group/saml_sso/img/scim_advanced.png
Binary files differ
diff --git a/doc/user/group/saml_sso/img/scim_attribute_mapping.png b/doc/user/group/saml_sso/img/scim_attribute_mapping.png
index c9f6b71f5b0..933d8fb6f36 100644
--- a/doc/user/group/saml_sso/img/scim_attribute_mapping.png
+++ b/doc/user/group/saml_sso/img/scim_attribute_mapping.png
Binary files differ
diff --git a/doc/user/group/saml_sso/img/scim_name_identifier_mapping.png b/doc/user/group/saml_sso/img/scim_name_identifier_mapping.png
new file mode 100644
index 00000000000..f9c63970f16
--- /dev/null
+++ b/doc/user/group/saml_sso/img/scim_name_identifier_mapping.png
Binary files differ
diff --git a/doc/user/group/saml_sso/img/scim_provisioning_status.png b/doc/user/group/saml_sso/img/scim_provisioning_status.png
new file mode 100644
index 00000000000..41466ec9276
--- /dev/null
+++ b/doc/user/group/saml_sso/img/scim_provisioning_status.png
Binary files differ
diff --git a/doc/user/group/saml_sso/img/scim_token.png b/doc/user/group/saml_sso/img/scim_token.png
index 7eb52bf6ea2..bf9347716e9 100644
--- a/doc/user/group/saml_sso/img/scim_token.png
+++ b/doc/user/group/saml_sso/img/scim_token.png
Binary files differ
diff --git a/doc/user/group/saml_sso/img/unlink_group_saml.png b/doc/user/group/saml_sso/img/unlink_group_saml.png
index 0561443b5f4..9d53a9bf407 100644
--- a/doc/user/group/saml_sso/img/unlink_group_saml.png
+++ b/doc/user/group/saml_sso/img/unlink_group_saml.png
Binary files differ
diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md
index 54923ab69ff..bd50367681e 100644
--- a/doc/user/group/saml_sso/index.md
+++ b/doc/user/group/saml_sso/index.md
@@ -39,6 +39,25 @@ However, users will not be prompted to log via SSO on each visit. GitLab will ch
We intend to add a similar SSO requirement for [Git and API activity](https://gitlab.com/gitlab-org/gitlab-ee/issues/9152) in the future.
+#### Group-managed accounts
+
+[Introduced in GitLab 12.1](https://gitlab.com/groups/gitlab-org/-/epics/709).
+
+When SSO is being enforced, groups can enable an additional level of protection by enforcing the creation of dedicated user accounts to access the group.
+
+Without group-managed accounts, users can link their SAML identity with any existing user on the instance. With group-managed accounts enabled, users are required to create a new, dedicated user linked to the group. The notification email address associated with the user is locked to the email address received from the configured identity provider.
+
+When this option is enabled:
+
+- All existing and new users in the group will be required to log in via the SSO URL associated with the group.
+- On successfully authenticating, GitLab will prompt the user to create a new, dedicated account using the email address received from the configured identity provider.
+- After the group managed account has been created, group activity will require the use of this user account.
+
+Since use of the group managed account requires the use of SSO, users of group managed accounts will lose access to these accounts when they are no longer able to authenticate with the connected identity provider. In the case of an offboarded employee who has been removed from your identity provider:
+
+- The user will be unable to access the group (their credentials will no longer work on the identity provider when prompted to SSO).
+- Contributions in the group (e.g. issues, merge requests) will remain intact.
+
### NameID
GitLab.com uses the SAML NameID to identify users. The NameID element:
@@ -71,7 +90,7 @@ Once you've set up your identity provider to work with GitLab, you'll need to co
1. Navigate to the group's **Settings > SAML SSO**.
1. Find the SSO URL from your Identity Provider and enter it the **Identity provider single sign on URL** field.
1. Find and enter the fingerprint for the SAML token signing certificate in the **Certificate** field.
-1. Check the **Enable SAML authentication for this group** checkbox.
+1. Click the **Enable SAML authentication for this group** toggle switch.
1. Click the **Save changes** button.
![Group SAML Settings for GitLab.com](img/group_saml_settings.png)
diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md
index 2d408766db8..5d136ad62da 100644
--- a/doc/user/group/saml_sso/scim_setup.md
+++ b/doc/user/group/saml_sso/scim_setup.md
@@ -27,25 +27,25 @@ The following identity providers are supported:
- [Group SSO](index.md) needs to be configured.
- The `scim_group` feature flag must be enabled:
- Run the following commands in a Rails console:
+ Run the following commands in a Rails console:
- ```sh
- # Omnibus GitLab
- gitlab-rails console
+ ```sh
+ # Omnibus GitLab
+ gitlab-rails console
- # Installation from source
- cd /home/git/gitlab
- sudo -u git -H bin/rails console RAILS_ENV=production
- ```
+ # Installation from source
+ cd /home/git/gitlab
+ sudo -u git -H bin/rails console RAILS_ENV=production
+ ```
- To enable SCIM for a group named `group_name`:
+ To enable SCIM for a group named `group_name`:
- ```ruby
- group = Group.find_by_full_path('group_name')
- Feature.enable(:group_scim, group)
- ```
+ ```ruby
+ group = Group.find_by_full_path('group_name')
+ Feature.enable(:group_scim, group)
+ ```
-### GitLab configuration
+## GitLab configuration
Once [Single sign-on](index.md) has been configured, we can:
@@ -55,68 +55,84 @@ Once [Single sign-on](index.md) has been configured, we can:
![SCIM token configuration](img/scim_token.png)
-## SCIM IdP configuration
+## Identity Provider configuration
-### Configuration on Azure
+### Azure
-In the [Single sign-on](index.md) configuration for the group, make sure
-that the **Name identifier value** (NameID) points to a unique identifier, such
-as the `user.objectid`. This will match the `extern_uid` used on GitLab.
+The SAML application that was created during [Single sign-on](index.md) setup now needs to be set up for SCIM.
-The GitLab app in Azure needs to be configured following
-[Azure's SCIM setup](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/use-scim-to-provision-users-and-groups#getting-started).
+1. Check the configuration for your GitLab SAML app and ensure that **Name identifier value** (NameID) points to `user.objectid` or another unique identifier. This will match the `extern_uid` used on GitLab.
-Note the following:
+ ![Name identifier value mapping](img/scim_name_identifier_mapping.png)
+
+1. Set up automatic provisioning and administrative credentials by following the
+ [Provisioning users and groups to applications that support SCIM](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/use-scim-to-provision-users-and-groups#provisioning-users-and-groups-to-applications-that-support-scim) section in Azure's SCIM setup documentation.
+
+During this configuration, note the following:
- The `Tenant URL` and `secret token` are the ones retrieved in the
[previous step](#gitlab-configuration).
- Should there be any problems with the availability of GitLab or similar
errors, the notification email set will get those.
+- It is recommended to set a notification email and check the **Send an email notification when a failure occurs** checkbox.
- For mappings, we will only leave `Synchronize Azure Active Directory Users to AppName` enabled.
-You can then test the connection clicking on `Test Connection`.
+You can then test the connection by clicking on **Test Connection**. If the connection is successful, be sure to save your configuration before moving on. See below for [troubleshooting](#troubleshooting).
+
+#### Configure attribute mapping
-### Synchronize Azure Active Directory users
+1. Click on `Synchronize Azure Active Directory Users to AppName`, to configure the attribute mapping.
+1. Click **Delete** next to the `mail` mapping.
+1. Map `userPrincipalName` to `emails[type eq "work"].value` and change it's **Matching precedence** to `2`.
+1. Map `mailNickname` to `userName`.
+1. Create a new mapping by clicking **Add New Mapping** then set **Source attribute** to `objectId`, **Target attribute** to `id`, **Match objects using this attribute** to `Yes`, and **Matching precedence** to `1`.
+1. Create a new mapping by clicking **Add New Mapping** then set **Source attribute** to `objectId`, and **Target attribute** to `externalId`.
+1. Click the `userPrincipalName` mapping and change **Match objects using this attribute** to `No`.
-1. Click on `Synchronize Azure Active Directory Users to AppName`, to configure
- the attribute mapping.
-1. Select the unique identifier (in the example `objectId`) as the `id` and `externalId`,
- and enable the `Create`, `Update`, and `Delete` actions.
-1. Map the `userPricipalName` to `emails[type eq "work"].value` and `mailNickname` to
- `userName`.
+ Save your changes and you should have the following configuration:
- Example configuration:
+ ![Azure's attribute mapping configuration](img/scim_attribute_mapping.png)
- ![Azure's attribute mapping configuration](img/scim_attribute_mapping.png)
+ NOTE: **Note:** If you used a unique identifier **other than** `objectId`, be sure to map it instead to both `id` and `externalId`.
+
+1. Below the mapping list click on **Show advanced options > Edit attribute list for AppName**.
-1. Click on **Show advanced options > Edit attribute list for AppName**.
1. Leave the `id` as the primary and only required field.
- NOTE: **Note:**
- `username` should neither be primary nor required as we don't support
- that field on GitLab SCIM yet.
+ NOTE: **Note:**
+ `username` should neither be primary nor required as we don't support
+ that field on GitLab SCIM yet.
- ![Azure's attribute advanced configuration](img/scim_advanced.png)
+ ![Azure's attribute advanced configuration](img/scim_advanced.png)
1. Save all the screens and, in the **Provisioning** step, set
- the `Provisioning Status` to `ON`.
+ the `Provisioning Status` to `On`.
+
+ ![Provisioning status toggle switch](img/scim_provisioning_status.png)
- NOTE: **Note:**
- You can control what is actually synced by selecting the `Scope`. For example,
- `Sync only assigned users and groups` will only sync the users assigned to
- the application (`Users and groups`), otherwise it will sync the whole Active Directory.
+ NOTE: **Note:**
+ You can control what is actually synced by selecting the `Scope`. For example,
+ `Sync only assigned users and groups` will only sync the users assigned to
+ the application (`Users and groups`), otherwise, it will sync the whole Active Directory.
Once enabled, the synchronization details and any errors will appear on the
bottom of the **Provisioning** screen, together with a link to the audit logs.
-<!-- ## Troubleshooting
+## Troubleshooting
+
+### Testing Azure connection: invalid credentials
+
+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.
+
+### Azure: (Field) can't be blank sync error
+
+When checking the Audit Logs for the Provisioning, you can sometimes see the
+error `Namespace can't be blank, Name can't be blank, and User can't be blank.`
+
+This is likely caused because not all required fields (such as first name and last name) are present for all users being mapped.
-Include any troubleshooting steps that you can foresee. If you know beforehand what issues
-one might have when setting this up, or when something is changed, or on upgrading, it's
-important to describe those, too. Think of things that may go wrong and include them here.
-This is important to minimize requests for support, and to avoid doc comments with
-questions that you know someone might ask.
+As a workaround, try an alternate mapping:
-Each scenario can be a third-level heading, e.g. `### 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. -->
+1. Follow the Azure mapping instructions from above.
+1. Delete the `name.formatted` target attribute entry.
+1. Change the `displayName` source attribute to have `name.formatted` target attribute.
diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md
index 1c6cca049c5..2eb3fae1a85 100644
--- a/doc/user/group/subgroups/index.md
+++ b/doc/user/group/subgroups/index.md
@@ -28,39 +28,39 @@ only 1 parent group. It resembles a directory behavior or a nested items list:
- Group 1
- Group 1.1
- Group 1.2
- - Group 1.2.1
- - Group 1.2.2
- - Group 1.2.2.1
+ - Group 1.2.1
+ - Group 1.2.2
+ - Group 1.2.2.1
In a real world example, imagine maintaining a GNU/Linux distribution with the
first group being the name of the distribution, and subsequent groups split as follows:
- Organization Group - GNU/Linux distro
- Category Subgroup - Packages
- - (project) Package01
- - (project) Package02
+ - (project) Package01
+ - (project) Package02
- Category Subgroup - Software
- - (project) Core
- - (project) CLI
- - (project) Android app
- - (project) iOS app
+ - (project) Core
+ - (project) CLI
+ - (project) Android app
+ - (project) iOS app
- Category Subgroup - Infra tools
- - (project) Ansible playbooks
+ - (project) Ansible playbooks
Another example of GitLab as a company would be the following:
- Organization Group - GitLab
- Category Subgroup - Marketing
- - (project) Design
- - (project) General
+ - (project) Design
+ - (project) General
- Category Subgroup - Software
- - (project) GitLab CE
- - (project) GitLab EE
- - (project) Omnibus GitLab
- - (project) GitLab Runner
- - (project) GitLab Pages daemon
+ - (project) GitLab CE
+ - (project) GitLab EE
+ - (project) Omnibus GitLab
+ - (project) GitLab Runner
+ - (project) GitLab Pages daemon
- Category Subgroup - Infra tools
- - (project) Chef cookbooks
+ - (project) Chef cookbooks
- Category Subgroup - Executive team
---
@@ -74,27 +74,37 @@ structure.
## Creating a subgroup
-NOTE: **Note:**
-You must be an Owner of a group to create a subgroup. For
-more information check the [permissions table](../../permissions.md#group-members-permissions).
-For a list of words that are not allowed to be used as group names see the
+To create a subgroup you must either be an Owner or a Maintainer of the
+group, depending on the group's setting.
+
+By default, groups created in:
+
+- GitLab 12.2 or later allow both Owners and Maintainers to create subgroups.
+- GitLab 12.1 or earlier only allow Owners to create subgroups.
+
+This setting can be for any group by an Owner or Administrator.
+
+For more information check the
+[permissions table](../../permissions.md#group-members-permissions). For a list
+of words that are not allowed to be used as group names see the
[reserved names](../../reserved_names.md).
-Users can always create subgroups if they are explicitly added as an Owner to
-a parent group, even if group creation is disabled by an administrator in their
-settings.
+
+Users can always create subgroups if they are explicitly added as an Owner (or
+Maintainer, if that setting is enabled) to a parent group, even if group
+creation is disabled by an administrator in their settings.
To create a subgroup:
1. In the group's dashboard expand the **New project** split button, select
**New subgroup** and click the **New subgroup** button.
- ![Subgroups page](img/create_subgroup_button.png)
+ ![Subgroups page](img/create_subgroup_button.png)
1. Create a new group like you would normally do. Notice that the parent group
namespace is fixed under **Group path**. The visibility level can differ from
the parent group.
- ![Subgroups page](img/create_new_group.png)
+ ![Subgroups page](img/create_new_group.png)
1. Click the **Create group** button and you will be taken to the new group's
dashboard page.