GitLab Hierarchy: Organization, Namespace, Group & Project

Here’s a comprehensive, up-to-date tutorial on GitLab 18.0 entity structure as of May 2026, covering:

• GitLab Organization
• GitLab Namespaces
• GitLab Groups
• GitLab Subgroups
• GitLab Projects

This includes definitions, scopes, use cases, comparisons, and tutorial instructions for setup across both GitLab SaaS (cloud) and Self-Managed (CE/EE) environments.

📌 Introduction

GitLab’s entity model defines how users organize, secure, and collaborate across codebases, projects, and teams. Understanding this structure ensures scalable DevOps practices in both SaaS (GitLab.com) and Self-Managed instances.

🔷 1. GitLab Organization

✅ Definition

In GitLab 18.0, an Organization is a new, top-level administrative abstraction, currently available in GitLab SaaS only (cloud). It acts as a logical container for top-level groups, enabling centralized governance and billing.

⚠️ Availability

🧰 What it Contains

• Top-Level Groups
• Users (org-wide membership management)
• Billing settings
• Audit logs
• (Roadmap: Org-wide SAML/SCIM, policies)

🔧 Use Cases

• Central billing and licensing
• Multi-group user identity control
• Enterprise-wide policy enforcement
• Sharding (via GitLab Cells architecture)

🔍 Scope

• Logical boundary above top-level groups
• Not used for CI/CD execution or repository directly

🔷 2. GitLab Namespace

✅ Definition

A namespace is a container for GitLab entities such as projects or groups. All projects belong to exactly one namespace, which defines the project’s path and access scope.

🔁 Types

🔧 Use Cases

• Defines URL structure of projects
• Manages project ownership
• Scopes CI/CD variables, runners, permissions

🔍 Scope

• Always associated with projects
• Can be visualized in hierarchy trees (namespace/project)

🔷 3. GitLab Group

✅ Definition

A Group is a primary organizational unit used to:

• Host multiple projects
• Share permissions
• Define CI/CD settings
• Manage users and roles

In GitLab, Top-Level Groups are the main entity for organizing work in both SaaS and Self-Managed setups.

🧰 What it Contains

• Subgroups
• Projects
• Members & access roles
• Shared runners, CI/CD variables, templates

🔧 Use Cases

• Department or product-level structure
• Access control inheritance
• Centralized monitoring via dashboards
• Epics for cross-project planning

🔍 Scope

• All settings cascade downward to children
• Can contain unlimited subgroups/projects

🔷 4. GitLab Subgroup

✅ Definition

A Subgroup is a group nested inside a parent group, used for more granular organization and permission scoping.

🧰 What it Contains

• Projects
• More nested subgroups (up to 20 levels)
• Inherited members + directly assigned ones

🔧 Use Cases

• Separate teams/modules under a department
• Restrict access to sensitive projects
• Model client-facing vs internal delivery teams

🔍 Scope

• Inherits from parent group
• Permissions can be elevated per subgroup, but not reduced

🔷 5. GitLab Project

✅ Definition

A Project is the fundamental unit of work — where source code, CI/CD pipelines, issues, and collaboration tools reside.

🧰 What it Contains

• Git repository
• .gitlab-ci.yml for pipelines
• Issues, Merge Requests
• Wiki, Releases, Containers
• Security scans (SAST, DAST, Dependency Scanning)

🔧 Use Cases

• Hosting microservices or monoliths
• Executing DevSecOps workflows
• Managing documentation, assets
• Automating deployment pipelines

🔍 Scope

• Lives inside a group or subgroup (cannot be top-level on its own)
• Inherits permissions and variables from parent group

📊 Entity Comparison Table

🛠️ How to Create (Step-by-Step)

🟢 GitLab SaaS (Cloud)

1. Create a Top-Level Group (functions as your “Org”)
   • Go to: https://gitlab.com/groups/new
   • Enter: DevOpsSchool
   • Set visibility: Private or Internal
   • Click Create Group
2. Create Subgroups
   • Navigate to DevOpsSchool
   • Click New Subgroup
   • Name: Academics, Operations, Clients, etc.
3. Create Projects
   • Go inside a subgroup (e.g., Academics/SoftwareEngineering)
   • Click New Project
   • Choose Blank, Template, or Import
4. (Optional) Access Organization (if enabled)
   • Visit https://gitlab.com/-/organizations
   • Manage top-level groups under the org

🔵 Self-Managed CE/EE

1. Same flow as above using Top-Level Groups
2. Enable Organization UI (Enterprise only): sudo gitlab-rails console Feature.enable(:ui_for_organizations)

✅ Summary

• GitLab 18.0 introduces Organizations, but they are not yet fully user-facing except in select SaaS environments.
• Top-Level Groups remain the most important and practical unit for structuring your organization today.
• Use Subgroups for complex team layouts or access control needs.
• Every Project must live inside a Namespace (Group or User).
• Permissions cascade downward but can be elevated per scope.

Rajesh Kumar

I’m a DevOps/SRE/DevSecOps/Cloud Expert passionate about sharing knowledge and experiences. I have worked at Cotocus. I share tech blog at DevOps School, travel stories at Holiday Landmark, stock market tips at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow , and SEO strategies at Wizbrand.

Do you want to learn Quantum Computing?

Please find my social handles as below;

Rajesh Kumar Personal Website
Rajesh Kumar at YOUTUBE
Rajesh Kumar at INSTAGRAM
Rajesh Kumar at X
Rajesh Kumar at FACEBOOK
Rajesh Kumar at LINKEDIN
Rajesh Kumar at WIZBRAND

Rajesh Kumar DailyLogs