GitLab Platform Foundations: GitLab.com, Self-Managed, Dedicated, Tiers, and Architecture: Concepts, Architecture, and Mental Model

1. The problem: one project, several kinds of state

A GitLab project can look like “a repository in a browser,” but that mental model becomes dangerous as soon as CI/CD, permissions, registries, approvals, environments, or administration enter the picture. Git knows about commits, trees, blobs, tags, branches as references, and remotes. GitLab stores and governs many additional objects around that Git repository: project metadata, members, issues and work items, merge requests, pipeline definitions and runs, job logs, runner registrations, releases, packages, container images, vulnerability findings, policies, audit events, and settings.

The first production skill is therefore classification. Before you change anything, ask: Is this state in Git, in the GitLab application, in a runner/executor, in a registry/object store, or in the infrastructure that operates GitLab itself? The answer determines which evidence to inspect, which permission is relevant, what can be rolled back, and which team owns the failure.

2. Git versus GitLab

A branch named main is a Git ref. “main is the default branch for this project” is GitLab metadata that points users and platform workflows toward a particular ref. A merge request compares Git refs, but the merge request discussion, approvals, reviewers, pipeline widgets, and merge policy are GitLab state.

3. Three offerings, three responsibility boundaries

flowchart LR
U[Developer / operator] --> APP[GitLab application resources]
APP --> REPO[Git repository]
APP --> META[MRs / issues / settings / CI metadata]
APP --> REG[Registry / artifacts]
APP --> RUN[Runner execution]
subgraph COM[GitLab.com]
C1[Shared SaaS platform operated by GitLab]
end
subgraph DED[GitLab Dedicated]
D1[Single-tenant SaaS infrastructure operated by GitLab]
end
subgraph SM[GitLab Self-Managed]
S1[Instance infrastructure operated by customer]
end
C1 --> APP
D1 --> APP
S1 --> APP

GitLab.com removes server installation and lifecycle work from the learner. It is the mandatory free-path platform for this chapter. GitLab Dedicated isolates a tenant and is managed by GitLab, with customer configuration boundaries that differ from full shell/database access. GitLab Self-Managed moves installation, upgrades, backups, storage, database, network, TLS, monitoring, and many recovery responsibilities to the organization operating it.

4. Offering is not tier

An offering answers “where and under whose operational responsibility does GitLab run?” A tier answers “which product entitlements are available?” GitLab currently names the tiers Free, Premium, and Ultimate. A Git repository is not “Ultimate”; the surrounding GitLab namespace/instance subscription determines whether a gated platform feature is available.

On GitLab.com, paid subscriptions are associated with top-level group namespaces rather than personal namespaces. That matters because the same user can work in different top-level groups with different entitlements. Therefore, “my account is Premium” is often too imprecise. Ask which top-level namespace the project belongs to and which subscription applies there.

5. Namespaces: the addressing and policy hierarchy

Namespaces organize projects and make paths unique. A personal namespace is based on a user identity. A group namespace can contain projects and subgroups, letting access and settings be organized hierarchically. Consider these example paths:

https://gitlab.com/learner-example/platform-lab
https://gitlab.com/acme-platform/payments/api

learner-example           -> personal namespace
acme-platform             -> top-level group namespace
acme-platform/payments    -> subgroup namespace
api                       -> project path inside the subgroup

The full path is more than decoration. APIs, clone URLs, membership inheritance, subscription scope, and many policies depend on it. Moving a project between namespaces can therefore change not only its URL but also the effective governance around it.

6. A project is a platform container around a repository

A GitLab project typically contains a Git repository, but the project is broader than the repository. It also owns or references settings and collaboration/automation resources. This distinction explains a common puzzle: deleting a local clone does not delete the GitLab project; changing the project description does not create a Git commit; and changing the default branch setting does not rewrite commit history.

7. Control plane versus data plane

This course uses a practical control-plane/data-plane analogy. GitLab metadata and policy decide what should happen and who may request it; Git repository content, artifacts, packages, images, runner workspaces, and external deployment targets carry the bytes being built or moved. The boundary is not mathematically perfect, but it is useful for diagnostics.

For example, a pipeline record can say a job succeeded, while the job’s actual execution occurred on a runner using an executor on a machine or cluster. A release record can point to assets, while the bytes may live in object storage or a registry. Treating every layer as “GitLab” hides trust boundaries that matter to DevOps.

8. Read-only inspection before mutation

Chapter 01 deliberately starts with observation. In a public project you can inspect useful project metadata without creating a token. If glab is already configured, it can add a second view; authentication setup itself belongs to Chapter 02.

# Cross-platform Git commands inside an existing clone
git remote -v
git branch --show-current
git rev-parse HEAD
git status --short --branch

# Optional: if glab is already installed/configured. Never add --show-token in course labs.
glab auth status --hostname gitlab.com
glab repo view -F json

# Public REST inspection: replace the URL-encoded namespace/project path.
curl --silent --show-error \
  "https://gitlab.com/api/v4/projects/learner-example%2Fplatform-foundations-lab"

In PowerShell, use curl.exe for the final command if you want curl-compatible flags. A successful Projects API response includes fields such as path_with_namespace, default_branch, visibility, and a namespace object. Those fields prove hosted project state; git rev-parse HEAD proves the checked-out commit in your local clone.

9. Why this matters in DevOps

Delivery failures often cross layers. A developer can push a valid commit but see no deployment because the pipeline rule excluded that source. A pipeline can be correct but wait forever because no trusted runner can accept the job. A project can be visible and healthy while the Self-Managed instance is degraded. A security control can exist in documentation but be unavailable because the project is in a different tier or offering.

The durable troubleshooting question is: which object is wrong, in which scope, and who controls it? That question is more valuable than memorizing the current sidebar label.

10. Mini-lab — classify ten observations

Choose any public GitLab project you are allowed to inspect. Do not change it. Record ten observations: full project path, namespace type, visibility, default branch, one commit SHA, clone URL, whether Issues/work items are exposed, whether CI/CD navigation is exposed, whether a container registry link is exposed, and the GitLab host. For each observation, label the owner layer: Git, GitLab project, namespace, CI/CD, registry, or offering/administration.

Verification: at least one Git fact must be independently confirmed from local Git or a repository view, and at least one GitLab project fact must be confirmed through the public Projects API. Cleanup: none; this is read-only.

Knowledge check

Summary

Git is the version-control engine; GitLab is a DevSecOps platform that surrounds Git repositories with namespaces, collaboration, CI/CD, registries, security controls, and administration. Offering, tier, namespace, project, runner, and infrastructure are different scopes. Treat them separately, inspect current state before mutation, and use exact resource identity—host, namespace, project, ref, pipeline, runner, or artifact—when diagnosing production behavior.

Official references

• GitLab Docs — Choose an offering and subscription tier
• GitLab Docs — GitLab Dedicated
• GitLab Docs — Namespaces
• GitLab Docs — Projects
• GitLab Docs — Groups
• GitLab Docs — Roles and permissions
• GitLab Docs — Projects REST API
• GitLab CLI — glab auth status
• GitLab CLI — glab repo view