Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 36 ยท Administration and Best Practices

Groups, Subgroups and Governance

Organize hundreds of projects with GitLab groups and subgroups: inheritance, group variables, shared CI templates, project templates, SSO, SCIM and naming conventions.

One project is easy to manage. Two hundred projects, ten teams and a few contractors are not. Groups are GitLab's answer: a folder-like container that holds projects and other groups, and lets you set rules once for everything inside. Good group design is the difference between "everything is consistent" and "every team did it differently".

This lesson covers the group hierarchy, what flows down from a group, shared CI/CD building blocks, templates, single sign-on, and the conventions that keep a large instance understandable. It cannot run on this site; the examples model inheritance of settings and a naming checker.

Groups and subgroups

A group has a name and a path (acme), and can contain subgroups up to 20 levels deep, though two or three levels is plenty. A project lives at group/subgroup/project, so the structure becomes part of every URL.

flowchart TD
  A["acme (top-level group)"] --> P["payments (subgroup)"]
  A --> W["web (subgroup)"]
  A --> PL["platform (subgroup)"]
  P --> P1["api"]
  P --> P2["ledger"]
  W --> W1["storefront"]
  PL --> PL1["ci-templates"]
  PL --> PL2["terraform-modules"]

Group paths become URLs: acme/payments/api.

Choose the structure by ownership and access, because that is what changes at a group boundary: who may see projects, who gets which role, which variables are shared. Avoid mirroring your org chart down to tiny teams (reorganizations make you move projects), and avoid putting every project into one flat group (no way to give a team its own access). A common layout is one top-level group per company or product area and subgroups per team or domain, plus a platform or shared subgroup for common tooling.

Moving a project between groups is possible (the old URL redirects for a while), but links in documents, Docker image names and package paths may break, so settle the structure early.

What a group gives its projects

Feature Effect
Members and roles Inherited by all subgroups and projects (the highest role wins, see Roles, Permissions and Protected Branches)
CI/CD variables Defined once, available to every project below (use protected and masked options)
Runners Group runners serve every project in the group
Visibility A project cannot be more visible than its group
Container and package registry, dependency proxy Group-level views and shared caching
Epics, milestones, labels Planning across projects (higher tiers for epics)
Merge request approval settings, push rules Defaults in higher tiers that apply to all projects
Compliance frameworks and policies Defined at top-level group (see Compliance, Audit Events and Approvals)

Putting runners and variables at group level removes the "copy this secret into 40 projects" chore. It also shifts risk: a group-level secret is visible to every pipeline below, so scope it by protected and environment whenever possible (see CI Variables and Secrets Security).

Shared CI/CD building blocks

The strongest governance tool is a shared pipeline configuration. Keep reusable pieces in one project, for example acme/platform/ci-templates, and include them elsewhere:

YAML
include:
  - project: acme/platform/ci-templates
    ref: v3.2.0
    file:
      - /templates/build-node.yml
      - /templates/security.yml

Pin ref to a tag (v3.2.0) rather than main, so a change in the template is a deliberate upgrade of each consumer and not a surprise. Newer GitLab versions also offer the CI/CD Catalog, where components are published with versions and inputs, and consumers use include: - component: .... Protect the template project with a strict review process: whoever can change it changes the pipelines of everybody.

Templates for new projects

Group-level project templates let people create a new project that already has the standard .gitlab-ci.yml, issue templates, CODEOWNERS and a README skeleton. File templates (Premium) offer standard .gitignore or Dockerfile files in the editor. The effect is a consistent starting point instead of copy and paste from an old project.

Identity: SSO, SAML and SCIM

In a company, accounts should come from the company's identity provider, not be created by hand:

  • SAML or OpenID Connect single sign-on lets users log in with company credentials, so MFA and password rules are enforced centrally.
  • SCIM automatically creates and removes users in GitLab when HR systems change. Automatic removal is the key security benefit, since leavers lose access at once.
  • Group-managed accounts / enterprise users (on GitLab.com) tie users to the organization.
  • Map identity-provider groups to GitLab groups and roles, so access follows team membership.

Require two-factor authentication at the group level when you cannot rely on the provider, and set an expiry for personal access tokens.

Conventions that scale

Write down a few rules and check them automatically:

  1. Naming: lowercase kebab-case paths (order-service), no personal names, no dates.
  2. Ownership: every project has a CODEOWNERS file and a named owning team in the README.
  3. Default branch is main, protected, with merge request approvals.
  4. Archive unused projects (read-only) instead of deleting them, and review inactive ones each quarter.
  5. Topics and descriptions are mandatory, since search depends on them.
  6. Fewer people with Owner (two or three per top-level group, with one backup).

The GitLab API can list all projects in a group (GET /groups/:id/projects) and report violations, which turns the conventions into a regular scan.

Stand-in: inheritance of group settings

The first example resolves a setting for a project by walking up the group path: a value at the lowest level wins, and a locked parent value cannot be overridden.

JS Settings inheritance

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The second example is a small audit script in the spirit of the conventions above. It checks a list of projects (sample data) for naming and ownership problems.

JS Convention checker

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A user is Maintainer on a top-level group. What is their role in a project of a subgroup?

    Roles flow down through subgroups to projects unless a higher role is granted lower down.
  2. 2. Why pin the ref of an included template project to a tag?

    Pointing at main means every consumer pipeline changes the moment the template does.
  3. 3. What is the main security benefit of SCIM?

    SCIM provisions and deprovisions users, so access ends when employment does.
  4. 4. What should drive the choice of group structure?

    Permissions, shared variables and runners change at group boundaries, so groups should match who owns and may access what.

Summary

  • Groups and subgroups hold projects and pass down members, variables, runners and policies.
  • Design the hierarchy for ownership and access; keep it shallow and stable.
  • Share pipelines through a versioned template or component project and pin the version.
  • Use SSO and SCIM for identity, project templates for consistent starts, and automated checks for conventions.

Next: Pipeline Efficiency Best Practices