A group gives related work a common home, but it also changes who can reach that work and which shared settings can affect it. Membership inherited from a parent reaches into its subgroups and projects. Runners, CI/CD variables, and policies can also apply below the level where they're configured. Choosing a group structure therefore means deciding what people should share, alongside making projects easy to find.
Start with the work and the people who need it
Look at how teams collaborate today. Which projects share owners, contributors, operating responsibilities, or requirements? Where do people wait for access, encounter conflicting rules, or struggle to find related work? Include runner use, storage, reporting, and expected growth in that picture, because a convenient structure for today's repositories may be awkward for tomorrow's workloads.
You can organize groups around products, services, customers, or parts of the organization. A company division can make a sensible group when it has lasting ownership and distinct access needs. Problems arise when a reporting-line change forces projects to move even though their contributors and responsibilities haven't changed. Choose names and relationships that describe the work people will recognize.
For example, several services maintained by one product team may fit under a product subgroup. A shared library used by many teams may need its own maintainer group and contribution path. It doesn't necessarily need to share the parent membership of every team that consumes it.
Place membership where it should continue to apply
A parent-group role is a grant to the work beneath that group. A private subgroup doesn't take that inherited access away. If developers should reach only their own team's projects, grant their membership at that subgroup or project rather than granting a broad role above it and trying to reduce it below.
The same reasoning applies to shared resources. Projects under a parent can use its group runners, and group variables can be available to their pipelines according to their scope and protection settings. Before putting more sensitive work beneath a broad parent, examine the people, jobs, and credentials involved.
Subgroups let teams manage their own work while sharing administration. Separate top-level groups fit when parent membership also needs to be independent. They still share the administration and infrastructure of the GitLab instance; top-level separation alone doesn't provide a separate instance.
Balance separation with shared administration
Keeping related projects in one top-level group can simplify common policies and group reports. On GitLab.com, the subscription applies to a top-level group, so a split also changes how paid access is managed. GitLab.com policy enforcement doesn't span separate top-level groups. GitLab Self-Managed administrators can enforce policies across multiple top-level groups, so the same layout can have different consequences across offerings.
Separation can be worthwhile for independent ownership, customer access, or distinct rules, but it adds administration. Check which reports need a common view and which settings or policies would need to be maintained in more than one place. The purpose of separation should outweigh the extra coordination.
Keep nesting understandable. GitLab recommends five levels or fewer to avoid performance problems, and a shallower structure can make inherited access easier to trace. Add a level when it groups work that shares a meaningful responsibility or setting, rather than using depth to reproduce every management layer.
Test the design through ordinary work
Before moving projects, try a representative group of users and projects against the proposed structure. Can a contributor find the right project and open a change? Can an owner manage access without granting it too widely? Does a pipeline use the intended runners and variables, and do the expected policies and reports include the project?
Review the results with the people who will use and maintain the structure. Investigate differences between the diagram and the experience: a missing permission may need a narrower grant, while an unexpected inherited permission may require changing the parent membership or project placement.
When the structure changes, update contribution instructions and check access, pipeline behavior, URLs, integrations, and policy coverage again. A well-organized hierarchy should remain explainable to the next team that joins it.
Further Reading
- A group structure that fits your teams offers a method for comparing layouts and introducing changes with project maintainers.
- Understand subgroup membership and inheritance explains what passes from a parent group and how to inspect membership.
- Share projects and groups deliberately describes collaboration across groups and invitation role limits.
- Choose where policies apply explains inheritance, scope, and offering differences.
- Review GitLab subscription scope helps you account for the subscription consequences of a top-level group design.