From bb99fc2572a796b938bd67128f6482c180e3942b Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Tue, 7 Mar 2017 21:32:36 +0100 Subject: Add nested groups documentation [ci skip] --- doc/user/group/subgroups/img/create_new_group.png | Bin 0 -> 18503 bytes .../group/subgroups/img/create_subgroup_button.png | Bin 0 -> 8402 bytes doc/user/group/subgroups/img/group_members.png | Bin 0 -> 48240 bytes doc/user/group/subgroups/img/mention_subgroups.png | Bin 0 -> 39666 bytes doc/user/group/subgroups/index.md | 153 +++++++++++++++++++++ doc/user/permissions.md | 1 + doc/workflow/README.md | 1 + 7 files changed, 155 insertions(+) create mode 100644 doc/user/group/subgroups/img/create_new_group.png create mode 100644 doc/user/group/subgroups/img/create_subgroup_button.png create mode 100644 doc/user/group/subgroups/img/group_members.png create mode 100644 doc/user/group/subgroups/img/mention_subgroups.png create mode 100644 doc/user/group/subgroups/index.md diff --git a/doc/user/group/subgroups/img/create_new_group.png b/doc/user/group/subgroups/img/create_new_group.png new file mode 100644 index 00000000000..9d011ec709a Binary files /dev/null and b/doc/user/group/subgroups/img/create_new_group.png differ diff --git a/doc/user/group/subgroups/img/create_subgroup_button.png b/doc/user/group/subgroups/img/create_subgroup_button.png new file mode 100644 index 00000000000..000b54c2855 Binary files /dev/null and b/doc/user/group/subgroups/img/create_subgroup_button.png differ diff --git a/doc/user/group/subgroups/img/group_members.png b/doc/user/group/subgroups/img/group_members.png new file mode 100644 index 00000000000..b95fe6263bf Binary files /dev/null and b/doc/user/group/subgroups/img/group_members.png differ diff --git a/doc/user/group/subgroups/img/mention_subgroups.png b/doc/user/group/subgroups/img/mention_subgroups.png new file mode 100644 index 00000000000..8e6bed0111b Binary files /dev/null and b/doc/user/group/subgroups/img/mention_subgroups.png differ diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md new file mode 100644 index 00000000000..9522e6fc4ba --- /dev/null +++ b/doc/user/group/subgroups/index.md @@ -0,0 +1,153 @@ +# Subgroups + +> [Introduced][ce-2772] in GitLab 9.0. + +With subgroups (also called nested groups or hierarchical groups) you can have +up to 20 levels of nested groups, which among other things can help you to: + +- **Separate internal / external organizations.** Since every group + can have its own visibility level, you are able to host groups for different + purposes under the same umbrella. +- **Organize large projects.** For large projects, subgroups makes it + potentially easier to separate permissions on parts of the source code. +- **Make it easier to manage people and control visibility.** Give people + different [permissions][] depending on their group [membership](#membership). + +## Overview + +A group can have many subgroups inside it, and at the same time a group can have +only 1 parent group. It resembles a directory behavior, like the one below: + +``` +group0 +└── subgroup01a +└── subgroup01b + └── subgroup02 + └── subgroup03 +``` + +In a real world example, imagine maintaining a GNU/Linux distribution with the +first group being the name of the distro and subsequent groups split like: + +``` +Organization Group - GNU/Linux distro + └── Category Subgroup - Packages + └── project - Package01 + └── project - Package02 + └── Category Subgroup - Software + └── project - Core + └── project - CLI + └── project - Android app + └── project - iOS app + └── Category Subgroup - Infra tools + └── project - Ansible playbooks +``` + +Another example of GitLab as a company would be the following: + +``` +Organization Group - GitLab + └── Category Subroup - Marketing + └── project - Design + └── project - General + └── Category Subgroup - Software + └── project - GitLab CE + └── project - GitLab EE + └── project - Omnibus GitLab + └── project - GitLab Runner + └── project - GitLab Pages daemon + └── Category Subgroup - Infra tools + └── project - Chef cookbooks + └── Category Subgroup - Executive team +``` + +--- + +The maximum nested groups a group can have, including the first one in the +hierarchy, is 21. + +Things like transferring or importing a project inside nested groups, work like +when performing these actions the traditional way with the `group/project` +structure. + +## Creating a subgroup + +>**Notes:** +- You need to be an Owner of a group in order to be able to create + a subgroup. For more information check the [permissions table][permissions]. +- For a list of words that are not allowed to be used as group names see the + [`namespace_validator.rb` file][reserved] under the `RESERVED` and + `WILDCARD_ROUTES` lists. + +To create a subgroup: + +1. In the group's dashboard go to the **Subgroups** page and click **Create subgroup**. + + ![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) + +1. Click the **Create group** button and you will be taken to the new group's + dashboard page. + +--- + +You can follow the same process to create any subsequent groups. + +## Membership + +When you add a member to a subgroup, they inherit the membership and permission +level from the parent group. This model allows access to nested groups if you +have membership in one of its parents. + +You can tell if a member has inherited the permissions from a parent group by +looking at the group's **Members** page. + +![Group members page](img/group_members.png) + +From the image above, we can deduct the following things: + +- There are 5 members that have access to the group **four** +- Administrator is the Owner and member of all subgroups +- User0 is a Reporter and has inherited their permissions from group **one** + which is above the hierarchy of group **four** +- User1 is a Developer and has inherited their permissions from group + **one/two** which is above the hierarchy of group **four** +- User2 is a Developer and has inherited their permissions from group + **one/two/three** which is above the hierarchy of group **four** +- User3 is a Master of group **four**, there is no indication of a parent + group therefore they belong to group **four** + +The group permissions for a member can be changed only by Owners and only on +the **Members** page of the group the member was added. + +## Mentioning subgroups + +Mentioning groups (`@group`) in issues, commits and merge requests, would +mention all members of that group. Now with subgroups, there is a more granular +support if you want to split your group's structure. Mentioning works as before +and you can choose the group of people to be summoned. + +![Mentioning subgroups](img/mention_subgroups.png) + +## Limitations + +Here's a list of what you can't do with subgroups: + +- [GitLab Pages](../../project/pages/index.md) are not currently working for + projects hosted under a subgroup. That means that only projects hosted under + the first parent group will work. +- Group level labels don't work in subgroups / sub projects +- It is not possible to share a project with a group that's an ancestor of + the group the project is in. That means you can only share as you walk down + the hierarchy. For example, `group/subgroup01/project` **cannot** be shared + with `group`, but can be shared with `group/subgroup02` or + `group/subgroup01/subgroup03`. + +[ce-2772]: https://gitlab.com/gitlab-org/gitlab-ce/issues/2772 +[permissions]: ../../permissions.md#group +[reserved]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/validators/namespace_validator.rb diff --git a/doc/user/permissions.md b/doc/user/permissions.md index b49a244160a..0ea6d01411f 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -81,6 +81,7 @@ group. |-------------------------|-------|----------|-----------|--------|-------| | Browse group | ✓ | ✓ | ✓ | ✓ | ✓ | | Edit group | | | | | ✓ | +| Create subgroup | | | | | ✓ | | Create project in group | | | | ✓ | ✓ | | Manage group members | | | | | ✓ | | Remove group | | | | | ✓ | diff --git a/doc/workflow/README.md b/doc/workflow/README.md index 9e7ee47387c..a286a23765d 100644 --- a/doc/workflow/README.md +++ b/doc/workflow/README.md @@ -40,3 +40,4 @@ - [Importing from SVN, GitHub, Bitbucket, etc](importing/README.md) - [Todos](todos.md) - [Snippets](../user/snippets.md) +- [Nested groups](../user/group/subgroups/index.md) -- cgit v1.2.1 From 1913f1ed9efced37cc597515ea4c7219eb17b4be Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Fri, 10 Mar 2017 14:15:28 +0100 Subject: Add info on group membership [ci skip] --- doc/user/group/subgroups/index.md | 39 +++++++++++++++++++++++++++++---------- 1 file changed, 29 insertions(+), 10 deletions(-) diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 9522e6fc4ba..2338d8e9b42 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -104,6 +104,9 @@ When you add a member to a subgroup, they inherit the membership and permission level from the parent group. This model allows access to nested groups if you have membership in one of its parents. +The group permissions for a member can be changed only by Owners and only on +the **Members** page of the group the member was added. + You can tell if a member has inherited the permissions from a parent group by looking at the group's **Members** page. @@ -111,19 +114,35 @@ looking at the group's **Members** page. From the image above, we can deduct the following things: -- There are 5 members that have access to the group **four** -- Administrator is the Owner and member of all subgroups -- User0 is a Reporter and has inherited their permissions from group **one** - which is above the hierarchy of group **four** +- There are 5 members that have access to the group `four` +- User0 is a Reporter and has inherited their permissions from group `one` + which is above the hierarchy of group `four` - User1 is a Developer and has inherited their permissions from group - **one/two** which is above the hierarchy of group **four** + `one/two` which is above the hierarchy of group `four` - User2 is a Developer and has inherited their permissions from group - **one/two/three** which is above the hierarchy of group **four** -- User3 is a Master of group **four**, there is no indication of a parent - group therefore they belong to group **four** + `one/two/three` which is above the hierarchy of group `four` +- For User3 there is no indication of a parent group, therefore they belong to + group `four`, the one we're inspecting +- Administrator is the Owner and member of **all** subgroups and for that reason, + same as User3, there is no indication of an ancestor group -The group permissions for a member can be changed only by Owners and only on -the **Members** page of the group the member was added. +### Overriding the ancestor group membership + +>**Note:** +You need to be an Owner of a group in order to be able to add members to it. + +To override the membership of an ancestor group, simply add the user in the new +subgroup again, but with different permissions. + +For example, if User0 was first added to group `one/two` with Developer +permissions, then they will inherit those permissions in every other subgroup +of `one/two`. To give them Master access to `one/two/three`, you would add them +again in that group as Master. Removing them from that group, the permissions +will fallback to those of the ancestor group. + +Note that the higher permission wins, so if in the above example the permissions +where reversed, User0 would have Master access to all groups, even to the one +that was explicitly given Developer access. ## Mentioning subgroups -- cgit v1.2.1 From f35d7a16595c199add9a582b8a80f8da75e5544d Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Fri, 10 Mar 2017 14:18:48 +0100 Subject: Fix wording [ci skip] --- doc/user/group/subgroups/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 2338d8e9b42..ff28f458f99 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -147,9 +147,9 @@ that was explicitly given Developer access. ## Mentioning subgroups Mentioning groups (`@group`) in issues, commits and merge requests, would -mention all members of that group. Now with subgroups, there is a more granular +notify all members of that group. Now with subgroups, there is a more granular support if you want to split your group's structure. Mentioning works as before -and you can choose the group of people to be summoned. +and you can choose the group of people to be notified. ![Mentioning subgroups](img/mention_subgroups.png) -- cgit v1.2.1 From b5142f92a03c1b2a58ee583e2d0632150e74d45a Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Tue, 14 Mar 2017 21:41:46 +0100 Subject: Address subgroups docs review [ci skip] --- doc/user/group/subgroups/index.md | 86 ++++++++++++++++++--------------------- 1 file changed, 39 insertions(+), 47 deletions(-) diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index ff28f458f99..ce5da07c61a 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -2,7 +2,7 @@ > [Introduced][ce-2772] in GitLab 9.0. -With subgroups (also called nested groups or hierarchical groups) you can have +With subgroups (aka nested groups or hierarchical groups) you can have up to 20 levels of nested groups, which among other things can help you to: - **Separate internal / external organizations.** Since every group @@ -16,50 +16,45 @@ up to 20 levels of nested groups, which among other things can help you to: ## Overview A group can have many subgroups inside it, and at the same time a group can have -only 1 parent group. It resembles a directory behavior, like the one below: +only 1 parent group. It resembles a directory behavior or a nested items list: -``` -group0 -└── subgroup01a -└── subgroup01b - └── subgroup02 - └── subgroup03 -``` +- Group 1 + - Group 1.1 + - Group 1.2 + - 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 distro and subsequent groups split like: -``` -Organization Group - GNU/Linux distro - └── Category Subgroup - Packages - └── project - Package01 - └── project - Package02 - └── Category Subgroup - Software - └── project - Core - └── project - CLI - └── project - Android app - └── project - iOS app - └── Category Subgroup - Infra tools - └── project - Ansible playbooks -``` +- Organization Group - GNU/Linux distro + - Category Subgroup - Packages + - (project) Package01 + - (project) Package02 + - Category Subgroup - Software + - (project) Core + - (project) CLI + - (project) Android app + - (project) iOS app + - Category Subgroup - Infra tools + - (project) Ansible playbooks Another example of GitLab as a company would be the following: -``` -Organization Group - GitLab - └── Category Subroup - Marketing - └── project - Design - └── project - General - └── Category Subgroup - Software - └── project - GitLab CE - └── project - GitLab EE - └── project - Omnibus GitLab - └── project - GitLab Runner - └── project - GitLab Pages daemon - └── Category Subgroup - Infra tools - └── project - Chef cookbooks - └── Category Subgroup - Executive team -``` +- Organization Group - GitLab + - Category Subroup - Marketing + - (project) Design + - (project) General + - Category Subgroup - Software + - (project) GitLab CE + - (project) GitLab EE + - (project) Omnibus GitLab + - (project) GitLab Runner + - (project) GitLab Pages daemon + - Category Subgroup - Infra tools + - (project) Chef cookbooks + - Category Subgroup - Executive team --- @@ -131,18 +126,15 @@ From the image above, we can deduct the following things: >**Note:** You need to be an Owner of a group in order to be able to add members to it. -To override the membership of an ancestor group, simply add the user in the new -subgroup again, but with different permissions. +To override a user's membership of an ancestor group (the first group they were +added to), simply add the user in the new subgroup again, but with different +permissions. -For example, if User0 was first added to group `one/two` with Developer +For example, if User0 was first added to group `group-1/group-1-1` with Developer permissions, then they will inherit those permissions in every other subgroup -of `one/two`. To give them Master access to `one/two/three`, you would add them -again in that group as Master. Removing them from that group, the permissions -will fallback to those of the ancestor group. - -Note that the higher permission wins, so if in the above example the permissions -where reversed, User0 would have Master access to all groups, even to the one -that was explicitly given Developer access. +of `group-1/group-1-1`. To give them Master access to `group-1/group-1-1/group1-1-1`, +you would add them again in that group as Master. Removing them from that group, +the permissions will fallback to those of the ancestor group. ## Mentioning subgroups -- cgit v1.2.1 From db8f6259abc0df40ef9c4016b30d14b33b2d13d0 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Wed, 15 Mar 2017 09:16:24 +0100 Subject: Change naming from nested groups to subgroups [ci skip] --- doc/workflow/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/workflow/README.md b/doc/workflow/README.md index a286a23765d..6a8de51a199 100644 --- a/doc/workflow/README.md +++ b/doc/workflow/README.md @@ -40,4 +40,4 @@ - [Importing from SVN, GitHub, Bitbucket, etc](importing/README.md) - [Todos](todos.md) - [Snippets](../user/snippets.md) -- [Nested groups](../user/group/subgroups/index.md) +- [Subgroups](../user/group/subgroups/index.md) -- cgit v1.2.1