DevOps AcademyLearn the delivery system
Chapter 04Lesson 03~160 minutes

Groups, Subgroups, Namespaces, Membership, Roles, Custom Roles, and Access Governance: Configuration, Design Choices, and Tradeoffs

Choose group hierarchy, membership placement, built-in versus custom roles, sharing, delegated administration, and identity-governance patterns by balancing least privilege, blast radius, auditability, compatibility, and cost.

Least privilegeSubgroupsDelegationGroup sharingSSO/SCIMTradeoffs

Learning objectives

  • Choose between flat and subgroup-based namespace structures using ownership, delegation, blast radius, discoverability, and maintenance criteria.
  • Decide whether access belongs at a group, subgroup, or project and explain how the choice changes inherited reach and offboarding complexity.
  • Choose built-in roles by default and justify when an Ultimate custom role is worth the additional governance complexity.
  • Evaluate group sharing, expiration, centralized ownership, delegated administration, SAML/SCIM/LDAP, and seat implications without conflating them.
  • Produce a maintainable access-governance design for a realistic engineering organization while preserving a complete Free learning path.
Availability baseline (verified 2026-08-21). Groups, subgroups, built-in roles, direct/inherited membership, membership expiration, group/project sharing, and the group/project Members REST APIs are documented across Free, Premium, and Ultimate on GitLab.com, Self-Managed, and Dedicated. The Planner role was introduced in GitLab 17.7. Security Manager is documented as Beta, introduced in GitLab 18.11 and enabled on GitLab.com; treat its Self-Managed status/version carefully. Custom roles are Ultimate. GitLab.com group SAML SSO and SCIM are Premium/Ultimate; Self-Managed identity-provider capabilities have different configuration and tier boundaries. Exact UI labels, seat rules, role-promotion behavior, and administrator restrictions can vary by version and instance policy.

1. Authorization design is an architecture decision

A group tree is easy to create and expensive to untangle after hundreds of projects and identities depend on it. The design question is not “how many subgroups can GitLab nest?” but “where should ownership and access intentionally inherit?” Every parent membership is a promise that the identity may reach descendants. Every direct project membership is an exception that future auditors must discover.

Use hierarchy to represent stable organizational or product boundaries. Use roles to express capability. Use identity-provider automation to control lifecycle when available. Keep these axes separate so a reorganization does not silently become a privilege redesign.

2. Flat groups versus subgroup hierarchy

Criterion Flatter groups Subgroup hierarchy
Access inheritance Less implicit downward inheritance. Efficient when the same team truly owns many descendants.
Delegation May require more separate owners/settings. Can delegate management at a subtree while preserving parent governance.
Blast radius A mistaken grant may affect fewer descendants. A high parent role can affect every child project.
Discoverability Many top-level groups can become noisy. Path communicates organizational context.
Policy consistency Repeated configuration may drift. Inheritance can centralize compatible policy/access.
Reorganization Moving boundaries can be explicit but numerous. Deep hierarchy can make transfers and ownership changes harder to reason about.
Performance/complexity Simple access graph. GitLab supports deep nesting, but shallow intentional trees are easier to operate.

3. Direct project membership versus inherited group membership

Prefer inherited group/subgroup membership when a person legitimately needs the same class of access across the whole subtree. Prefer a direct project membership when the access really is a project-specific exception. The dangerous pattern is using direct memberships as the default because they are locally convenient.

Question Group/subgroup membership Direct project membership
Scope All descendants that inherit the membership. One project.
Onboarding Efficient for teams. Fine-grained but repetitive.
Offboarding Remove one source, then verify descendants/shares. Must find every project-specific grant.
Least privilege Good only if the whole subtree is required. Good for true one-project exceptions.
Auditability Clear if group ownership is well designed. Can become scattered exception debt.

4. Built-in role first; custom role only for a stable permission gap

Start with the documented built-in role that satisfies the workflow. If the only way to meet a long-lived business need would otherwise be granting much broader authority, an Ultimate custom role may be justified. But custom roles add a new policy object with its own lifecycle, assignment surface, testing requirement, and documentation burden.

Choice Use when Avoid when
Built-in role The standard permission bundle matches the job. Do not jump to Maintainer merely because one action is blocked.
Ultimate custom role A repeated, stable permission gap exists and owners can govern/test it. Free/Premium path, one-off exception, unclear owner, or rapidly changing requirement.
Temporary higher built-in role Rare break-glass training/incident process with approval, expiry, and review. As a permanent workaround for missing custom-role entitlement.
Security Manager status: because the role is currently documented as Beta, do not build a durable production authorization architecture that silently assumes identical behavior on every Self-Managed version. Record the version/status and provide a fallback role/control model.

5. Centralized ownership versus delegated administration

Central ownership can make policy consistent, but a small Owner group becomes a bottleneck and a high-value target. Delegated administration lets teams operate their subtree, but every delegation increases the number of identities that can change membership or settings.

A strong design separates:

  • Top-level Owners: few, accountable identities responsible for namespace-wide governance and recovery.
  • Subgroup Maintainers/Owners where supported: only where the team truly administers the subtree.
  • Project Maintainers: project operations without automatically granting top-level ownership.
  • Developers/Reporters/Planners/Guests: task-oriented roles selected from actual permissions.

Also inspect project/subgroup creation permissions. If every developer can create arbitrary namespaces/projects under a governed group, your intended hierarchy can drift into an unreviewed access topology.

6. Group sharing: collaboration shortcut or hidden access edge?

Sharing is appropriate when another existing team needs controlled access without moving projects or duplicating individual memberships. Set a maximum role based on the target need, then remember that the invited group remains the source identity collection. Offboarding a person from the target project alone cannot revoke a share-derived path.

Pattern Advantage Risk/control
Invite one group to one project Efficient cross-team access. Document the share, maximum role, owner, and expiration if temporary.
Invite group to parent group Broad collaboration across descendants. Large blast radius; require explicit governance justification.
Add users individually Precise for exceptions. Creates scattered membership debt.
Duplicate a source group Avoids dynamic shared membership only superficially. Creates synchronization/offboarding drift; usually worse than a governed share.

7. SSO, SCIM, SAML group sync, and LDAP: authentication is not the same as authorization

Identity-provider integration should reduce lifecycle drift, not obscure GitLab’s authorization model. On GitLab.com, group SAML SSO and SCIM are Premium/Ultimate capabilities at the top-level-group enterprise boundary. SAML group sync can map IdP groups to GitLab groups/roles on supported tiers. Self-Managed SAML/LDAP configuration is administered at the instance boundary and has different capabilities.

Design questions include: Who is authoritative for join/leave? What happens if sync is delayed? Which GitLab membership is manually managed versus provider-managed? Can emergency access work during IdP outage? How are tokens/service accounts handled when a human is deprovisioned? These questions belong in an offboarding runbook, not in a generic “enable SSO” checkbox.

8. Expiration and seat control are lifecycle policies

Expiration is strongest when attached to temporary access at the narrowest useful scope and reviewed before renewal. It is weaker when the same identity retains a permanent ancestor membership. Likewise, optimizing paid-seat consumption must never become an excuse to use shared credentials or over-broad automation identities. Verify current billable-member rules because subscription behavior evolves independently of Git permissions.

9. Worked decision: three teams, one platform namespace

Scenario: acme-platform owns payments and identity subgroups. Platform operators need Maintainer across both. Payments developers need Developer only under payments. An external auditor needs read-oriented access to one project for 30 days. Security needs broad read/security visibility but no routine branch administration.

Need Recommended starting point Why
Platform operators Maintainer at acme-platform, with very few Owners above them. The scope intentionally spans descendants; inheritance is useful.
Payments developers Developer at acme-platform/payments. Avoids unintended access to identity projects.
External auditor Narrow project membership with appropriate read role + expiration. No need to expose the whole subgroup.
Security team Built-in role/group placement matching current permissions; evaluate Security Manager status/version; Ultimate custom role only for a stable unmet need. Avoid turning security visibility into blanket Maintainer authority.
Cross-team temporary review Project/group share with a deliberate maximum role and expiration where supported. Avoid individual duplication while bounding the share.

10. Design review questions before approval

  • Can you explain every parent membership that intentionally reaches descendants?
  • Could a lower-scope direct role be misleading because a higher ancestor role wins?
  • Are Owners few, non-shared, protected by strong authentication, and covered by recovery procedures?
  • Are project-level exceptions discoverable and owned?
  • Are shares documented with maximum role, expiration/lifecycle, and source group?
  • Does offboarding include human memberships, identity-provider state, service accounts, project/group tokens, deploy credentials, and shared-group paths?
  • For paid features, is tier/offering/version documented rather than assumed?

Knowledge check

When is subgroup inheritance a feature rather than a risk?

Why is a custom role not automatically “more least privilege” than a built-in role?

A contractor needs one project for 30 days. Is top-level group membership a good default?

Does SCIM remove the need for an offboarding checklist?

Summary

Good GitLab authorization design minimizes hidden edges. Use shallow intentional namespaces, inherited membership for genuinely shared scope, direct project access for true exceptions, built-in roles by default, Ultimate custom roles only for stable gaps, and explicit lifecycle ownership for shares and identity-provider integrations.

Official references

Next lesson

Diagnose access that refuses to disappear

Lesson 4 turns the hierarchy into failure analysis: inherited fallback, higher-role dominance, over-broad sharing, unavailable custom roles, and incomplete offboarding.

Keep the academy open

Support free, practical DevOps education.

Every lesson is designed to remain readable in a browser, downloadable from GitHub, and usable without a paid learning platform. Contributions help expand and maintain the curriculum.

Ethereum / ERC-20
0x716c4Ab160C4B66F31a28AE2448BfF68fc3a2ef0Send only Ethereum/ERC-20 compatible assets to this address.