{"id":49461,"date":"2025-05-26T12:31:41","date_gmt":"2025-05-26T12:31:41","guid":{"rendered":"https:\/\/www.devopsschool.com\/blog\/?p=49461"},"modified":"2026-02-21T07:28:45","modified_gmt":"2026-02-21T07:28:45","slug":"gitlab-hierarchy-organization-namespace-group-project","status":"publish","type":"post","link":"https:\/\/www.devopsschool.com\/blog\/gitlab-hierarchy-organization-namespace-group-project\/","title":{"rendered":"GitLab Hierarchy: Organization, Namespace, Group &amp; Project"},"content":{"rendered":"\n<p>Here&#8217;s a <strong>comprehensive, up-to-date tutorial<\/strong> on <strong>GitLab 18.0<\/strong> entity structure as of <strong>May 2026<\/strong>, covering:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>GitLab <strong>Organization<\/strong><\/li>\n\n\n\n<li>GitLab <strong>Namespaces<\/strong><\/li>\n\n\n\n<li>GitLab <strong>Groups<\/strong><\/li>\n\n\n\n<li>GitLab <strong>Subgroups<\/strong><\/li>\n\n\n\n<li>GitLab <strong>Projects<\/strong><\/li>\n<\/ul>\n\n\n\n<p>This includes definitions, scopes, use cases, comparisons, and tutorial instructions for setup across both <strong>GitLab SaaS (cloud)<\/strong> and <strong>Self-Managed (CE\/EE)<\/strong> environments.<\/p>\n\n\n\n<hr class=\"wp-block-separator has-alpha-channel-opacity\">\n\n\n\n<h2 class=\"wp-block-heading\">\ud83d\udccc Introduction<\/h2>\n\n\n\n<p>GitLab&#8217;s entity model defines <strong>how users organize<\/strong>, <strong>secure<\/strong>, and <strong>collaborate<\/strong> across codebases, projects, and teams. Understanding this structure ensures scalable DevOps practices in both <strong>SaaS (GitLab.com)<\/strong> and <strong>Self-Managed<\/strong> instances.<\/p>\n\n\n\n<hr class=\"wp-block-separator has-alpha-channel-opacity\">\n\n\n\n<h2 class=\"wp-block-heading\">\ud83d\udd37 1. GitLab <strong>Organization<\/strong><\/h2>\n\n\n\n<figure class=\"wp-block-image size-full\"><img loading=\"lazy\" decoding=\"async\" width=\"636\" height=\"512\" src=\"https:\/\/www.devopsschool.com\/blog\/wp-content\/uploads\/2025\/05\/image-15.png\" alt=\"\" class=\"wp-image-49462\" srcset=\"https:\/\/www.devopsschool.com\/blog\/wp-content\/uploads\/2025\/05\/image-15.png 636w, https:\/\/www.devopsschool.com\/blog\/wp-content\/uploads\/2025\/05\/image-15-300x242.png 300w\" sizes=\"auto, (max-width: 636px) 100vw, 636px\" \/><\/figure>\n\n\n\n<h3 class=\"wp-block-heading\">\u2705 Definition<\/h3>\n\n\n\n<p>In GitLab 18.0, an <strong>Organization<\/strong> is a <strong>new, top-level administrative abstraction<\/strong>, currently available in <strong>GitLab SaaS only (cloud)<\/strong>. It acts as a logical container for <strong>top-level groups<\/strong>, enabling centralized governance and billing.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">\u26a0\ufe0f Availability<\/h3>\n\n\n\n<figure class=\"wp-block-table\"><table class=\"has-fixed-layout\"><thead><tr><th>Platform<\/th><th>Availability<\/th><\/tr><\/thead><tbody><tr><td>GitLab SaaS (cloud)<\/td><td>\u2705 Available (preview; limited UI)<\/td><\/tr><tr><td>Self-Managed CE\/EE<\/td><td>\ud83d\udd12 Not available by default; optional via <code>ui_for_organizations<\/code> feature flag (admin only)<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n<h3 class=\"wp-block-heading\">\ud83e\uddf0 What it Contains<\/h3>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Top-Level Groups<\/li>\n\n\n\n<li>Users (org-wide membership management)<\/li>\n\n\n\n<li>Billing settings<\/li>\n\n\n\n<li>Audit logs<\/li>\n\n\n\n<li>(Roadmap: Org-wide SAML\/SCIM, policies)<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">\ud83d\udd27 Use Cases<\/h3>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Central billing and licensing<\/li>\n\n\n\n<li>Multi-group user identity control<\/li>\n\n\n\n<li>Enterprise-wide policy enforcement<\/li>\n\n\n\n<li>Sharding (via GitLab Cells architecture)<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">\ud83d\udd0d Scope<\/h3>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Logical boundary<\/strong> above top-level groups<\/li>\n\n\n\n<li>Not used for CI\/CD execution or repository directly<\/li>\n<\/ul>\n\n\n\n<hr class=\"wp-block-separator has-alpha-channel-opacity\">\n\n\n\n<h2 class=\"wp-block-heading\">\ud83d\udd37 2. GitLab <strong>Namespace<\/strong><\/h2>\n\n\n\n<figure class=\"wp-block-image size-full\"><img loading=\"lazy\" decoding=\"async\" width=\"687\" height=\"558\" src=\"https:\/\/www.devopsschool.com\/blog\/wp-content\/uploads\/2025\/05\/image-16.png\" alt=\"\" class=\"wp-image-49463\" srcset=\"https:\/\/www.devopsschool.com\/blog\/wp-content\/uploads\/2025\/05\/image-16.png 687w, https:\/\/www.devopsschool.com\/blog\/wp-content\/uploads\/2025\/05\/image-16-300x244.png 300w\" sizes=\"auto, (max-width: 687px) 100vw, 687px\" \/><\/figure>\n\n\n\n<h3 class=\"wp-block-heading\">\u2705 Definition<\/h3>\n\n\n\n<p>A <strong>namespace<\/strong> is a container for GitLab entities such as <strong>projects<\/strong> or <strong>groups<\/strong>. All projects belong to exactly one namespace, which defines the project\u2019s path and access scope.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">\ud83d\udd01 Types<\/h3>\n\n\n\n<figure class=\"wp-block-table\"><table class=\"has-fixed-layout\"><thead><tr><th>Namespace Type<\/th><th>Purpose<\/th><th>Example<\/th><\/tr><\/thead><tbody><tr><td>User<\/td><td>Private space for an individual user<\/td><td><code>gitlab.com\/alice\/myapp<\/code><\/td><\/tr><tr><td>Group<\/td><td>Shared space for a team\/org<\/td><td><code>gitlab.com\/devops-team\/myapp<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n<h3 class=\"wp-block-heading\">\ud83d\udd27 Use Cases<\/h3>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Defines URL structure of projects<\/li>\n\n\n\n<li>Manages project ownership<\/li>\n\n\n\n<li>Scopes CI\/CD variables, runners, permissions<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">\ud83d\udd0d Scope<\/h3>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Always associated with <strong>projects<\/strong><\/li>\n\n\n\n<li>Can be visualized in hierarchy trees (<code>namespace\/project<\/code>)<\/li>\n<\/ul>\n\n\n\n<hr class=\"wp-block-separator has-alpha-channel-opacity\">\n\n\n\n<h2 class=\"wp-block-heading\">\ud83d\udd37 3. GitLab <strong>Group<\/strong><\/h2>\n\n\n\n<h3 class=\"wp-block-heading\">\u2705 Definition<\/h3>\n\n\n\n<p>A <strong>Group<\/strong> is a primary organizational unit used to:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Host multiple projects<\/li>\n\n\n\n<li>Share permissions<\/li>\n\n\n\n<li>Define CI\/CD settings<\/li>\n\n\n\n<li>Manage users and roles<\/li>\n<\/ul>\n\n\n\n<p>In GitLab, <strong>Top-Level Groups<\/strong> are the <strong>main entity<\/strong> for organizing work in both SaaS and Self-Managed setups.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">\ud83e\uddf0 What it Contains<\/h3>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Subgroups<\/li>\n\n\n\n<li>Projects<\/li>\n\n\n\n<li>Members &amp; access roles<\/li>\n\n\n\n<li>Shared runners, CI\/CD variables, templates<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">\ud83d\udd27 Use Cases<\/h3>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Department or product-level structure<\/li>\n\n\n\n<li>Access control inheritance<\/li>\n\n\n\n<li>Centralized monitoring via dashboards<\/li>\n\n\n\n<li>Epics for cross-project planning<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">\ud83d\udd0d Scope<\/h3>\n\n\n\n<ul class=\"wp-block-list\">\n<li>All settings cascade downward to children<\/li>\n\n\n\n<li>Can contain unlimited subgroups\/projects<\/li>\n<\/ul>\n\n\n\n<hr class=\"wp-block-separator has-alpha-channel-opacity\">\n\n\n\n<h2 class=\"wp-block-heading\">\ud83d\udd37 4. GitLab <strong>Subgroup<\/strong><\/h2>\n\n\n\n<h3 class=\"wp-block-heading\">\u2705 Definition<\/h3>\n\n\n\n<p>A <strong>Subgroup<\/strong> is a group <strong>nested inside a parent group<\/strong>, used for more granular organization and permission scoping.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">\ud83e\uddf0 What it Contains<\/h3>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Projects<\/li>\n\n\n\n<li>More nested subgroups (up to 20 levels)<\/li>\n\n\n\n<li>Inherited members + directly assigned ones<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">\ud83d\udd27 Use Cases<\/h3>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Separate teams\/modules under a department<\/li>\n\n\n\n<li>Restrict access to sensitive projects<\/li>\n\n\n\n<li>Model client-facing vs internal delivery teams<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">\ud83d\udd0d Scope<\/h3>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Inherits from parent group<\/li>\n\n\n\n<li>Permissions can be elevated per subgroup, but not reduced<\/li>\n<\/ul>\n\n\n\n<hr class=\"wp-block-separator has-alpha-channel-opacity\">\n\n\n\n<h2 class=\"wp-block-heading\">\ud83d\udd37 5. GitLab <strong>Project<\/strong><\/h2>\n\n\n\n<h3 class=\"wp-block-heading\">\u2705 Definition<\/h3>\n\n\n\n<p>A <strong>Project<\/strong> is the fundamental unit of work \u2014 where source code, CI\/CD pipelines, issues, and collaboration tools reside.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">\ud83e\uddf0 What it Contains<\/h3>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Git repository<\/li>\n\n\n\n<li><code>.gitlab-ci.yml<\/code> for pipelines<\/li>\n\n\n\n<li>Issues, Merge Requests<\/li>\n\n\n\n<li>Wiki, Releases, Containers<\/li>\n\n\n\n<li>Security scans (SAST, DAST, Dependency Scanning)<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">\ud83d\udd27 Use Cases<\/h3>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Hosting microservices or monoliths<\/li>\n\n\n\n<li>Executing DevSecOps workflows<\/li>\n\n\n\n<li>Managing documentation, assets<\/li>\n\n\n\n<li>Automating deployment pipelines<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">\ud83d\udd0d Scope<\/h3>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Lives inside a group or subgroup (cannot be top-level on its own)<\/li>\n\n\n\n<li>Inherits permissions and variables from parent group<\/li>\n<\/ul>\n\n\n\n<hr class=\"wp-block-separator has-alpha-channel-opacity\">\n\n\n\n<h2 class=\"wp-block-heading\">\ud83d\udcca Entity Comparison Table<\/h2>\n\n\n\n<figure class=\"wp-block-table\"><table class=\"has-fixed-layout\"><thead><tr><th>Feature<\/th><th>Organization<\/th><th>Namespace<\/th><th>Group<\/th><th>Subgroup<\/th><th>Project<\/th><\/tr><\/thead><tbody><tr><td>GitLab.com (SaaS)<\/td><td>\u2705 Preview<\/td><td>\u2705 Core concept<\/td><td>\u2705 Primary unit<\/td><td>\u2705 Supported<\/td><td>\u2705 Core unit<\/td><\/tr><tr><td>Self-Managed<\/td><td>\ud83d\udd12 Feature-flag<\/td><td>\u2705 Core concept<\/td><td>\u2705 Primary unit<\/td><td>\u2705 Supported<\/td><td>\u2705 Core unit<\/td><\/tr><tr><td>User-Creatable<\/td><td>\ud83d\udd12 Limited (SaaS)<\/td><td>\u2705 Implicit on create<\/td><td>\u2705 Yes<\/td><td>\u2705 Yes<\/td><td>\u2705 Yes<\/td><\/tr><tr><td>Visibility Control<\/td><td>Org-wide roadmap<\/td><td>Inherited<\/td><td>Public\/Internal\/Priv<\/td><td>Public\/Internal\/Priv<\/td><td>Public\/Internal\/Priv<\/td><\/tr><tr><td>Role Management<\/td><td>Admins (future)<\/td><td>User\/Group based<\/td><td>Guest to Owner<\/td><td>Inherit \/ Elevate<\/td><td>Guest to Maintainer<\/td><\/tr><tr><td>Contains<\/td><td>Groups<\/td><td>Projects<\/td><td>Subgroups, Projects<\/td><td>Subgroups, Projects<\/td><td>Code, Pipelines, Issues<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n<hr class=\"wp-block-separator has-alpha-channel-opacity\">\n\n\n\n<h2 class=\"wp-block-heading\">\ud83d\udee0\ufe0f How to Create (Step-by-Step)<\/h2>\n\n\n\n<h3 class=\"wp-block-heading\">\ud83d\udfe2 GitLab SaaS (Cloud)<\/h3>\n\n\n\n<ol class=\"wp-block-list\">\n<li><strong>Create a Top-Level Group<\/strong> (functions as your \u201cOrg\u201d)\n<ul class=\"wp-block-list\">\n<li>Go to: <code>https:\/\/gitlab.com\/groups\/new<\/code><\/li>\n\n\n\n<li>Enter: <code>DevOpsSchool<\/code><\/li>\n\n\n\n<li>Set visibility: <code>Private<\/code> or <code>Internal<\/code><\/li>\n\n\n\n<li>Click <strong>Create Group<\/strong><\/li>\n<\/ul>\n<\/li>\n\n\n\n<li><strong>Create Subgroups<\/strong>\n<ul class=\"wp-block-list\">\n<li>Navigate to <code>DevOpsSchool<\/code><\/li>\n\n\n\n<li>Click <strong>New Subgroup<\/strong><\/li>\n\n\n\n<li>Name: <code>Academics<\/code>, <code>Operations<\/code>, <code>Clients<\/code>, etc.<\/li>\n<\/ul>\n<\/li>\n\n\n\n<li><strong>Create Projects<\/strong>\n<ul class=\"wp-block-list\">\n<li>Go inside a subgroup (e.g., <code>Academics\/SoftwareEngineering<\/code>)<\/li>\n\n\n\n<li>Click <strong>New Project<\/strong><\/li>\n\n\n\n<li>Choose <code>Blank<\/code>, <code>Template<\/code>, or <code>Import<\/code><\/li>\n<\/ul>\n<\/li>\n\n\n\n<li><strong>(Optional) Access Organization (if enabled)<\/strong>\n<ul class=\"wp-block-list\">\n<li>Visit <code>https:\/\/gitlab.com\/-\/organizations<\/code><\/li>\n\n\n\n<li>Manage top-level groups under the org<\/li>\n<\/ul>\n<\/li>\n<\/ol>\n\n\n\n<hr class=\"wp-block-separator has-alpha-channel-opacity\">\n\n\n\n<h3 class=\"wp-block-heading\">\ud83d\udd35 Self-Managed CE\/EE<\/h3>\n\n\n\n<ol class=\"wp-block-list\">\n<li><strong>Same flow as above using Top-Level Groups<\/strong><\/li>\n\n\n\n<li><strong>Enable Organization UI (Enterprise only)<\/strong>: <code>sudo gitlab-rails console Feature.enable(:ui_for_organizations)<\/code><\/li>\n<\/ol>\n\n\n\n<hr class=\"wp-block-separator has-alpha-channel-opacity\">\n\n\n\n<h2 class=\"wp-block-heading\">\u2705 Summary<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>GitLab 18.0 introduces Organizations<\/strong>, but they are <strong>not yet fully user-facing<\/strong> except in select SaaS environments.<\/li>\n\n\n\n<li><strong>Top-Level Groups<\/strong> remain the most important and practical unit for structuring your organization today.<\/li>\n\n\n\n<li>Use <strong>Subgroups<\/strong> for complex team layouts or access control needs.<\/li>\n\n\n\n<li>Every <strong>Project<\/strong> must live inside a <strong>Namespace<\/strong> (Group or User).<\/li>\n\n\n\n<li>Permissions cascade downward but can be elevated per scope.<\/li>\n<\/ul>\n\n\n\n<hr class=\"wp-block-separator has-alpha-channel-opacity\">\n\n\n\n<p><\/p>\n","protected":false},"excerpt":{"rendered":"<p>Here&#8217;s a comprehensive, up-to-date tutorial on GitLab 18.0 entity structure as of May 2026, covering: This includes definitions, scopes, use cases, comparisons, and tutorial instructions for setup across both GitLab&#8230; <\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"","sticky":false,"template":"","format":"standard","meta":{"_joinchat":[],"footnotes":""},"categories":[2],"tags":[],"class_list":["post-49461","post","type-post","status-publish","format-standard","hentry","category-uncategorised"],"_links":{"self":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/49461","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/comments?post=49461"}],"version-history":[{"count":2,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/49461\/revisions"}],"predecessor-version":[{"id":58985,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/49461\/revisions\/58985"}],"wp:attachment":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/media?parent=49461"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/categories?post=49461"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/tags?post=49461"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}