Subgroups

You can organize WVS groups into subgroups. You can use subgroups to:

  • Separate internal and external organizations. Because every subgroup can have its own visibility level, you can host groups for different purposes under the same parent group.
  • Organize large projects. You can use subgroups to give different access to parts of the source code.
  • Manage people and control visibility. Give a user a different role for each group they’re a member of.

Subgroups can:

  • Belong to one immediate parent group.
  • Have many subgroups.
  • Be nested up to 20 levels.
  • Use runners registered to parent groups:
    • Secrets configured for the parent group are available to subgroup jobs.
    • Users with the Maintainer role in projects that belong to subgroups can see the details of runners registered to parent groups.

For example:

graph TD subgraph "Parent group" subgraph "Subgroup A" subgraph "Subgroup A1" G["Project E"] end C["Project A"] D["Project B"] E["Project C"] end subgraph "Subgroup B" F["Project D"] end end

Create a subgroup

Prerequisites:

note
You cannot host a WVS Pages subgroup website with a top-level domain name. For example, subgroupname.example.io.

To create a subgroup:

  1. On the top bar, select My Groups and find and select the parent group to add a subgroup to.
  2. On the parent group’s overview page, in the top right, select New subgroup.
  3. Select Create group.
  4. Fill in the fields. View a list of reserved names that cannot be used as group names.
  5. Select Create group.

Change who can create subgroups

To create a subgroup, you must have at least the Maintainer role on the group, depending on the group’s setting.

To change who can create subgroups on a group:

  • As a user with the Owner role on the group:
    1. On the top bar, select My Groups and find the group.
    2. On the left sidebar, select Settings > General.
    3. Expand Permissions and group features.
    4. Select a role from the Allowed to create subgroups dropdown.

For more information, view the permissions table.

Subgroup membership

When you add a member to a group, that member is also added to all subgroups. The user’s permissions are inherited from the group’s parent.

Subgroup members can:

  1. Be direct members of the subgroup.
  2. Inherit membership of the subgroup from the subgroup’s parent group.
  3. Be a member of a group that was shared with the subgroup’s top-level group.
flowchart RL subgraph Group A A(Direct member) B{{Shared member}} subgraph Subgroup A H(1. Direct member) C{{2. Inherited member}} D{{Inherited member}} E{{3. Shared member}} end A-->|Direct membership of Group A\nInherited membership of Subgroup A|C end subgraph Group C G(Direct member) end subgraph Group B F(Direct member) end F-->|Group B\nshared with\nGroup A|B B-->|Inherited membership of Subgroup A|D G-->|Group C shared with Subgroup A|E

Group permissions for a member can be changed only by:

  • Users with the Owner role on the group.
  • Changing the configuration of the group the member was added to.

Determine membership inheritance

To see if a member has inherited the permissions from a parent group:

  1. On the top bar, select My Groups and find the group.
  2. Select Group information > Members.

Members list for an example subgroup Four:

In the screenshot above:

  • Five members have access to group Four.
  • User 0 has the Reporter role on group Four, and has inherited their permissions from group One:
    • User 0 is a direct member of group One.
    • Group One is above group Four in the hierarchy.
  • User 1 has the Developer role on group Four and inherited their permissions from group Two:
    • User 0 is a direct member of group Two, which is a subgroup of group One.
    • Groups One / Two are above group Four in the hierarchy.
  • User 2 has the Developer role on group Four and has inherited their permissions from group Three:
    • User 0 is a direct member of group Three, which is a subgroup of group Two. Group Two is a subgroup of group One.
    • Groups One / Two / Three are above group Four the hierarchy.
  • User 3 is a direct member of group Four. This means they get their Maintainer role directly from group Four.
  • Administrator has the Owner role on group Four and is a member of all subgroups. For that reason, as with User 3, the Source column indicates they are a direct member.

Members can be filtered by inherited or direct membership.

Override ancestor group membership

Users with the Owner role on a subgroup can add members to it.

You can’t give a user a role on a subgroup that’s lower than the roles they have on ancestor groups. To override a user’s role on an ancestor group, add the user to the subgroup again with a higher role. For example:

  • If User 1 is added to group Two with the Developer role, they inherit that role in every subgroup of group Two.
  • To give User 1 the Maintainer role on group Four (under One / Two / Three), add them again to group Four with the Maintainer role.
  • If User 1 is removed from group Four, their role falls back to their role on group Two. They have the Developer role on group Four again.

Mention subgroups

Mentioning subgroups (@<subgroup_name>) in issues, commits, and merge requests notifies all members of that group. Mentioning works the same as for projects and groups, and you can choose the group of people to be notified.