1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
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**.
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.
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.
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.
## 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
|
