debian-mirror-gitlab/doc/user/group/subgroups/index.md

201 lines
7.9 KiB
Markdown
Raw Normal View History

2019-09-04 21:01:54 +05:30
---
type: reference, howto, concepts
---
2017-08-17 22:00:37 +05:30
# Subgroups
2018-12-05 23:21:45 +05:30
NOTE: **Note:**
2019-07-07 11:18:12 +05:30
[Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/2772) in GitLab 9.0. Not available when using MySQL as external
database (support removed in GitLab 9.3 [due to performance reasons](https://gitlab.com/gitlab-org/gitlab-ce/issues/30472#note_27747600)).
2017-08-17 22:00:37 +05:30
2019-09-04 21:01:54 +05:30
Subgroups, also known as nested groups or hierarchical groups, allow you to have up to 20
levels of groups.
By using subgroups you can do the following:
2017-08-17 22:00:37 +05:30
- **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
2019-07-07 11:18:12 +05:30
different [permissions](../../permissions.md#group-members-permissions) depending on their group [membership](#membership).
2017-08-17 22:00:37 +05:30
2017-09-10 17:25:29 +05:30
## Database Requirements
2019-09-04 21:01:54 +05:30
Subgroups are only supported when you use PostgreSQL. Supporting subgroups on MySQL in an
efficient way is not possible due to MySQL's limitations.
2017-09-10 17:25:29 +05:30
See the following links for more information:
2019-03-02 22:35:43 +05:30
- <https://gitlab.com/gitlab-org/gitlab-ce/issues/30472>
- <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10885>
2017-09-10 17:25:29 +05:30
2017-08-17 22:00:37 +05:30
## 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 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
In a real world example, imagine maintaining a GNU/Linux distribution with the
2019-09-04 21:01:54 +05:30
first group being the name of the distribution, and subsequent groups split as follows:
2017-08-17 22:00:37 +05:30
- 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
2018-10-15 14:42:47 +05:30
- Category Subgroup - Marketing
2017-08-17 22:00:37 +05:30
- (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
---
2019-09-04 21:01:54 +05:30
The maximum subgroups a group can have, including the first one in the
2017-08-17 22:00:37 +05:30
hierarchy, is 21.
2019-09-04 21:01:54 +05:30
Actions such as transferring or importing a project inside subgroups, work like
2017-08-17 22:00:37 +05:30
when performing these actions the traditional way with the `group/project`
structure.
## Creating a subgroup
2018-12-05 23:21:45 +05:30
NOTE: **Note:**
2019-09-04 21:01:54 +05:30
You must be an Owner of a group to create a subgroup. For
2019-07-07 11:18:12 +05:30
more information check the [permissions table](../../permissions.md#group-members-permissions).
2018-12-05 23:21:45 +05:30
For a list of words that are not allowed to be used as group names see the
2019-07-07 11:18:12 +05:30
[reserved names](../../reserved_names.md).
2018-12-05 23:21:45 +05:30
Users can always create subgroups if they are explicitly added as an Owner to
2019-09-04 21:01:54 +05:30
a parent group, even if group creation is disabled by an administrator in their
2018-12-05 23:21:45 +05:30
settings.
2017-08-17 22:00:37 +05:30
To create a subgroup:
2018-03-17 18:26:18 +05:30
1. In the group's dashboard expand the **New project** split button, select
**New subgroup** and click the **New subgroup** button.
2017-08-17 22:00:37 +05:30
![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.
2018-03-17 18:26:18 +05:30
Follow the same process to create any subsequent groups.
2017-08-17 22:00:37 +05:30
## 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.
2019-09-04 21:01:54 +05:30
The group permissions for a member can be changed only by Owners, and only on
2017-08-17 22:00:37 +05:30
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.
![Group members page](img/group_members.png)
2019-09-04 21:01:54 +05:30
From the image above, we can deduce the following things:
2017-08-17 22:00:37 +05:30
2019-09-04 21:01:54 +05:30
- There are 5 members that have access to the group `four`.
2017-08-17 22:00:37 +05:30
- User0 is a Reporter and has inherited their permissions from group `one`
2019-09-04 21:01:54 +05:30
which is above the hierarchy of group `four`.
2017-08-17 22:00:37 +05:30
- User1 is a Developer and has inherited their permissions from group
2019-09-04 21:01:54 +05:30
`one/two` which is above the hierarchy of group `four`.
2017-08-17 22:00:37 +05:30
- User2 is a Developer and has inherited their permissions from group
2019-09-04 21:01:54 +05:30
`one/two/three` which is above the hierarchy of group `four`.
2017-08-17 22:00:37 +05:30
- For User3 there is no indication of a parent group, therefore they belong to
2019-09-04 21:01:54 +05:30
group `four`, the one we're inspecting.
2017-08-17 22:00:37 +05:30
- Administrator is the Owner and member of **all** subgroups and for that reason,
2019-09-04 21:01:54 +05:30
as with User3, there is no indication of an ancestor group.
2017-08-17 22:00:37 +05:30
### Overriding the ancestor group membership
2018-12-05 23:21:45 +05:30
NOTE: **Note:**
2019-09-04 21:01:54 +05:30
You must be an Owner of a group to be able to add members to it.
2017-08-17 22:00:37 +05:30
2018-12-05 23:21:45 +05:30
NOTE: **Note:**
A user's permissions in a subgroup cannot be lower than in any of its ancestor groups.
Therefore, you cannot reduce a user's permissions in a subgroup with respect to its ancestor groups.
2017-08-17 22:00:37 +05:30
To override a user's membership of an ancestor group (the first group they were
2018-12-05 23:21:45 +05:30
added to), add the user to the new subgroup again with a higher set of permissions.
2017-08-17 22:00:37 +05:30
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
2018-11-08 19:23:39 +05:30
of `group-1/group-1-1`. To give them Maintainer access to `group-1/group-1-1/group1-1-1`,
you would add them again in that group as Maintainer. Removing them from that group,
2017-08-17 22:00:37 +05:30
the permissions will fallback to those of the ancestor group.
## Mentioning subgroups
Mentioning groups (`@group`) in issues, commits and merge requests, would
2019-09-04 21:01:54 +05:30
notify all members of that group. Now with subgroups, there is more granular
2017-08-17 22:00:37 +05:30
support if you want to split your group's structure. Mentioning works as before
and you can choose the group of people to be notified.
![Mentioning subgroups](img/mention_subgroups.png)
## Limitations
Here's a list of what you can't do with subgroups:
2019-03-02 22:35:43 +05:30
- [GitLab Pages](../../project/pages/index.md) supports projects hosted under
a subgroup, but not subgroup websites.
That means that only the highest-level group supports
2019-07-31 22:56:46 +05:30
[group websites](../../project/pages/getting_started_part_one.md#gitlab-pages-domain-names),
2019-03-02 22:35:43 +05:30
although you can have project websites under a subgroup.
2017-08-17 22:00:37 +05:30
- 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
2019-07-07 11:18:12 +05:30
[permissions]: ../../permissions.md#group-members-permissions
2018-03-17 18:26:18 +05:30
[reserved]: ../../reserved_names.md
2017-09-10 17:25:29 +05:30
[issue]: https://gitlab.com/gitlab-org/gitlab-ce/issues/30472#note_27747600
2019-09-04 21:01:54 +05:30
<!-- ## Troubleshooting
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.
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. -->