GitLab Platform Foundations: GitLab.com, Self-Managed, Dedicated, Tiers, and Architecture: Guided Hands-On Workflow and Core Operations

1. Preflight and safety boundary

You need a GitLab.com account and Git installed. glab is optional. If glab is already authenticated, use it only for read-only inspection in this chapter. Do not create a personal access token here; Chapter 02 teaches credentials deliberately.

• Use a project name such as platform-foundations-lab.
• Prefer your personal namespace so the lab does not depend on current GitLab.com top-level-group limits or group billing.
• Use public visibility for the mandatory REST exercise, unless you have a reason not to publish even synthetic content. If public projects are disallowed by your account policy, keep it private and use the web/Git path only; the unauthenticated REST step becomes a supplied-response exercise.
• Do not place employer code, credentials, customer information, or production configuration in the lab.

2. Create the disposable project

In the current GitLab UI, use Create new → New project/repository → Create blank project. Enter platform-foundations-lab, select your personal namespace, choose Public for the default lab, and initialize the repository with a README. Initializing with a README is important because it creates a repository commit and therefore a default branch immediately.

Before selecting Create project, predict two state changes:

1. A GitLab project resource will be created at a namespace-qualified path.
2. Because README initialization is enabled, the project’s Git repository will contain at least one commit and a default branch, normally main unless a different default is configured at a higher level.

3. Inspect hosted state before cloning

Do not start by typing Git commands. First record the hosted state GitLab presents. The exact navigation grouping can move between releases; anchor your notes to resources rather than memorizing sidebar coordinates.

4. Prove the project with the public REST API

GitLab’s Projects API accepts either a numeric project ID or a URL-encoded project path. Replace YOUR_NAMESPACE before running the example. The slash between namespace and project becomes %2F.

# Bash / Git Bash / macOS / Linux
curl --silent --show-error \
  "https://gitlab.com/api/v4/projects/YOUR_NAMESPACE%2Fplatform-foundations-lab"

# Windows PowerShell / PowerShell 7: call curl.exe explicitly for curl flags
curl.exe --silent --show-error `
  "https://gitlab.com/api/v4/projects/YOUR_NAMESPACE%2Fplatform-foundations-lab"

Expect a JSON object shaped like this; IDs and URLs will differ:

{
  "name": "platform-foundations-lab",
  "path_with_namespace": "YOUR_NAMESPACE/platform-foundations-lab",
  "default_branch": "main",
  "visibility": "public",
  "namespace": {
    "kind": "user",
    "full_path": "YOUR_NAMESPACE"
  },
  "web_url": "https://gitlab.com/YOUR_NAMESPACE/platform-foundations-lab"
}

This is useful because it turns a visual observation into machine-readable evidence. It still does not prove your local Git state.

5. Clone and compare local Git state

git clone https://gitlab.com/YOUR_NAMESPACE/platform-foundations-lab.git
cd platform-foundations-lab

git remote -v
git branch --show-current
git rev-parse HEAD
git log --oneline --decorate -5
git status --short --branch

Verify that origin points to the project you just inspected, the current branch matches the GitLab default branch, and the local HEAD SHA matches the README commit shown by GitLab. If any identity differs, stop. You may be in the wrong directory, on the wrong branch, or connected to the wrong remote.

flowchart LR
UI[GitLab project\nnamespace + visibility + default branch] --> REM[Remote repository\nrefs/heads/main]
REM -->|git clone/fetch| LOC[Local clone\norigin/main + main + HEAD]
API[Projects API] --> UI
GLAB[glab repo view\noptional] --> UI

6. Make one controlled change and predict the result

Create a tiny file containing only synthetic learning notes. Before pushing, write down your prediction: a new commit will exist locally first; GitLab will not see it until the push succeeds.

printf '%s\n' \
  '# Platform Foundations Lab' \
  '' \
  '- Git owns commits and refs.' \
  '- GitLab owns project metadata and collaboration state.' \
  > platform-map.md

git add platform-map.md
git commit -m "docs: add platform boundary map"

git rev-parse HEAD
git status --short --branch

# Only after recording the local SHA:
git push origin HEAD

PowerShell alternative for file creation:

@(
  '# Platform Foundations Lab',
  '',
  '- Git owns commits and refs.',
  '- GitLab owns project metadata and collaboration state.'
) | Set-Content -Encoding utf8 platform-map.md

git add platform-map.md
git commit -m "docs: add platform boundary map"
git rev-parse HEAD
git push origin HEAD

After the push, GitLab’s branch/commit view should show the same SHA. This is causal verification: the Git object was created locally, transferred through Git transport, then became reachable by a branch ref in the hosted repository.

7. Optional glab read-only inspection

If glab is already configured, use its current context-aware commands. Do not display stored tokens.

glab auth status --hostname gitlab.com

glab repo view -F json

glab auth status determines context from the remote, GITLAB_HOST, or configuration; specifying --hostname gitlab.com removes ambiguity. The command has a --show-token option, but this course intentionally does not use it because terminal scrollback, screenshots, logs, and prompt history are all unnecessary exposure surfaces.

8. Four-surface verification

1. Web UI: project path, visibility, default branch, latest commit SHA.
2. Local Git: git remote -v, git branch --show-current, git rev-parse HEAD.
3. REST: path_with_namespace, default_branch, visibility, namespace.kind.
4. glab, optional: project view from the same repository context.

If all four identify the same host/project/branch/commit, you have much stronger evidence than “the page looked right.”

9. Challenge — choose the right control surface

Without copying a click path, decide where you would investigate each request:

• “Change the README text.” → repository content / Git change.
• “Make this project private.” → GitLab project setting and permission/tier/policy check.
• “Why does my laptop show an older commit?” → local Git fetch/branch state.
• “Why did no CI job start?” → GitLab pipeline creation/rules first, then runner execution if a job exists.
• “Which group owns this project?” → namespace/project metadata.

10. Cleanup and rollback

The safest default is to keep the project clearly marked disposable until you complete Lesson 5. If you must clean it now, verify that the project contains no valuable data. Archiving or deleting the hosted project is a GitLab platform action and does not merely remove your local clone.

Local rollback is separate: deleting the local directory affects only that clone. If you keep the project, you can re-clone it later.

Knowledge check

Summary

You created one disposable GitLab project, observed it before mutation, connected it to a local clone, created a commit, pushed it, and verified identity across multiple surfaces. The important habit is not the command sequence; it is predicting which resource changes and independently verifying the result.

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

• GitLab Docs — Default branch