A group structure often starts as a convenient place to put a few projects. As teams grow, the same structure starts deciding who can reach those projects, which settings they inherit, and who has to help when something changes. A layout that looks tidy on a diagram can still make ordinary collaboration difficult.
The aim is a structure people can work within and explain. You shouldn't need to move every repository when reporting lines change, or give someone access to a whole division so they can contribute to one service. It's worth understanding those problems before drawing a replacement hierarchy; sometimes the better answer is a membership change rather than a project move.
Start with the work that the structure needs to support
A few representative projects can tell you more than an organization chart. Together with their maintainers, follow how someone joins the team, proposes a change, runs a pipeline, and gets help with a release. Include a shared library or service and work involving another team or an outside collaborator. These examples reveal where ownership and collaboration differ.
For each example, note who maintains it, who contributes, which shared resources it uses, and any access or operating requirements that set it apart. Existing access requests and support issues can help explain a frustrating arrangement: perhaps contributors wait on a distant group owner, or a deployment variable is available much more widely than intended.
Expected changes matter too. A new product, an acquisition, or work for another customer might put pressure on different parts of the design. You don't need a hierarchy for every possible future, but a likely change shouldn't force unrelated teams to reorganize their work.
Choose what the groups organize
Grouping by product can bring the services and people responsible for an outcome together. Grouping by function can fit teams that maintain shared capabilities across products. Customer-specific groups can make sense when customers have different access and ownership arrangements. None of these patterns removes the need for collaboration across groups.
For example, two product teams might both use a library maintained by a third team. The library can stay with its maintainers while contributors receive access to it. Putting everyone in a common parent with broad permissions would be easier to administer, but it would also extend that access to unrelated projects.
A hybrid structure can reflect these differences without becoming arbitrary. A short explanation of where new work goes helps: product services live with their product, while shared libraries live with the team that maintains them. When a project seems to fit in two places, ownership and shared configuration are usually better deciding factors than its current reporting line.
Extra nesting adds another place to look for inherited access and settings. A subgroup earns its place when it groups work that needs common administration, not just because another management level exists. Keeping that reasoning in the group's description or team documentation makes the next placement decision easier.
Work through who will receive access
Membership in a parent group extends into its descendants. Making a subgroup private doesn't remove that inherited access, and a lower direct role won't reduce a higher inherited role. A design review therefore needs both the project tree and the grants that apply to it.
Suppose a contractor contributes to one service. Access at that service's project or an appropriate subgroup may cover the work without exposing the rest of the product. If several projects regularly share the same collaborators, inviting a group can reduce repeated membership changes. The eligibility rules differ between inviting a group to a project and inviting it to another group, so check the resulting members rather than assuming the whole source hierarchy receives access.
The invitation's maximum role limits access through that invitation. It doesn't reduce access someone already has through another route. Access reviews that follow how people work explains how to trace those routes before changing a grant.
Pipelines deserve the same attention as human membership. Review which jobs will use the parent group's runners and variables, including protection and environment settings. A sensible place for source code isn't automatically a sensible place to share deployment credentials.
Decide whether a separate top-level group is worth it
Subgroups usually offer a simpler starting point when teams share administration. A separate top-level group may fit genuinely independent ownership or customer arrangements, but it brings separate membership and settings to maintain. It isn't infrastructure isolation.
On GitLab.com, a subscription applies to a top-level group. A proposed split therefore needs a subscription decision as well as a directory decision. Paid features don't follow a team into another top-level group simply because the people are the same.1
Security policy management also differs by offering.2 GitLab.com policy enforcement doesn't span separate top-level groups; GitLab Self-Managed administrators can enforce policies across them. Where teams want common rules or reporting, compare how that work would be maintained in each arrangement. Separation may still be the right choice, but someone should be prepared to manage its consequences.
Introduce the design through representative projects
A review with normal contributors and maintainers helps expose gaps that an administrator's walkthrough would miss. People should be able to find the project, do their usual work, and understand who can help. Someone outside the intended audience shouldn't gain access merely because the project moved.
For existing projects, a move deserves preparation. The project transfer documentation covers restrictions and changes to membership, paths, packages, and policies. Some features need additional handling before a transfer. A repository redirect alone won't tell you whether its pipelines and integrations still work.
You can begin with a small set of projects that reflects those dependencies. Agree with their maintainers when to move, what they'll check afterward, and how they'll recover if an integration or delivery path stops working. Record the current grants and settings before changing them so you're comparing behavior, not relying on memory.
After the first moves, review the original problems. Are access requests easier to resolve? Can the intended people still contribute and release? Are shared settings reaching only the projects they should? Expanding the rollout makes sense when these answers support the design. If everyone still needs help from one administrator, the hierarchy may have changed without improving how it works.
Further Reading
Notes
-
GitLab plans explains subscription scope. On GitLab.com, Premium and Ultimate subscriptions apply to a top-level group and its descendants; a separate top-level group has its own subscription arrangement. ↩
-
Security policies are available in Ultimate. The enforcement guidance explains policy links, inheritance, and differences between GitLab.com and GitLab Self-Managed. ↩
- Subgroups explains inherited membership, shared resources, and how to inspect access.
- Sharing projects and groups helps you choose an invitation without granting broader access than intended.
- Transferring a project covers preparation, restrictions, and checks after a move.