Day 1: GitLab Architecture, Core Features, and Account Setup

This chapter covers the foundational architecture, core components, and internal execution flows of GitLab. It contrasts GitLab's unified platform approach with traditional multi-tool DevOps pipelines, provides a step-by-step guide to setting up a GitLab account, and explores the built-in project management, security, and deployment features.

1. What is GitLab? The All-in-One DevOps Paradigm

Traditionally, software development and operations teams have relied on a fragmented ecosystem of specialized tools to manage the software development lifecycle (SDLC). This multi-tool approach introduces significant integration overhead, maintenance complexity, and data silos.

In contrast, GitLab is an all-in-one DevSecOps platform that consolidates these capabilities into a single application with a unified user interface, data store, and permission model.

The Unified Platform Advantage

Instead of configuring, securing, and maintaining separate integrations for every phase of the lifecycle, GitLab provides native, out-of-the-box solutions for:

• Source Code Management (SCM): Git-based repository hosting, branching, and merge requests.
• Continuous Integration & Continuous Delivery (CI/CD): Native, runner-based automation pipelines.
• Inbuilt Security Scanning: Static Application Security Testing (SAST), Secret Detection, Dependency Scanning, and Container Scanning.
• Project Management: Issue tracking, Kanban boards, work items, and milestones.
• Artifact & Package Registries: Built-in storage for Docker images, npm packages, Maven artifacts, and machine learning models.
• Monitoring & Analytics: Basic Prometheus integration, error tracking, alert management, and DevOps metrics.

2. Mental Model: Git vs. GitLab vs. GitHub

To build a solid foundation, it is essential to distinguish between the underlying version control tool and the platforms built around it.

Git

Git is a local, distributed version control system (VCS). It is a command-line tool that tracks changes in source code over time. It operates entirely on your local machine without requiring an internet connection.

• Core Commands: git init, git commit, git push, git pull, git branch.
• UI: None natively (command-line only).

GitLab

GitLab is a complete DevSecOps platform. It uses Git internally to manage repository files but wraps it in a massive ecosystem of web interfaces, databases, background workers, and automation engines.

• Target Audience: Developers, DevOps Engineers, Security Teams, and Project Managers.
• Key Focus: End-to-end automation, security compliance, and unified project tracking.

GitHub

GitHub is primarily a cloud-based hosting service for Git repositories. While it has expanded to include CI/CD (GitHub Actions) and project management features, it remains highly developer-centric. GitLab, by contrast, was built from the ground up to tightly integrate developer workflows with robust operations and security pipelines.

Feature Comparison Matrix

3. The 4-Layer Architecture of GitLab

To understand how GitLab processes user actions—such as loading a web page, pushing code, or triggering a pipeline—we must examine its internal architecture. GitLab is composed of multiple microservices and components organized into four logical layers.

The Core: GitLab Rails Application

At the center of GitLab is the GitLab Rails Application. Written in Ruby on Rails, this application handles the core business logic, web user interface, API endpoints, and user authentication. All other components either support or communicate with this Rails core.

4. Deep Dive: Entry Points & Routing (Layers 1 & 2)

Whenever a client (a web browser or a local Git CLI) interacts with GitLab, the request must pass through the entry and routing layers.

Layer 1: Entry Points

There are two primary protocols used to access GitLab:

1. HTTPS (Ports 80 / 443):

   • Used primarily for accessing the GitLab Web UI via a browser.
   • Can also be used for Git operations (e.g., git clone https://...), though this requires entering credentials or personal access tokens.
   • Unencrypted HTTP requests on port 80 are automatically redirected to HTTPS on port 443.

2. SSH (Port 22):

   • A secure, encrypted tunnel used exclusively by developers for command-line Git operations (git push, git pull).
   • Authenticated using public/private SSH key pairs.
   • Performance Note: SSH connections bypass the overhead of HTTP headers and session state checks, making Git operations significantly faster than HTTPS.

Layer 2: Routing Components

Once a request reaches the server, it is routed by one of two components:

• Nginx:

  • Acts as the reverse proxy and ingress point for all HTTP/HTTPS traffic.
  • Handles SSL/TLS decryption.
  • Blocks malicious or malformed web traffic.
  • Serves static assets (images, CSS, JavaScript) directly from disk to reduce load on the application servers.
  • Forwards dynamic requests to the application layer.

• GitLab Shell:

  • Acts as the ingress point for all SSH traffic.
  • Authenticates the incoming SSH key against authorized keys stored in the database.
  • Verifies user permissions for the target repository.
  • Hands off the actual Git read/write operations to the storage layer.

5. Deep Dive: Application Logic (Layer 3)

The application layer processes requests, coordinates data retrieval, and manages background automation.

GitLab Workhorse

The GitLab Workhorse is a reverse proxy written in Go. It acts as a buffer between Nginx/GitLab Shell and the Rails application servers.

• The Problem: Ruby on Rails processes are heavy and single-threaded. If a user uploads a 2 GB file or downloads a large build artifact, the Rails process would be blocked for the duration of the transfer, causing the entire UI to freeze for other users.
• The Solution: GitLab Workhorse intercepts all requests. It handles large file uploads, artifact downloads, and long-polling Git HTTP operations. Once the heavy lifting is complete, it passes a lightweight metadata request to the Rails application. This ensures the web interface remains fast and responsive.

Puma (Live Request Handler)

Puma is a fast, multi-threaded Ruby web server that hosts the GitLab Rails application.

• Role: Handles live, synchronous requests.
• Examples: Loading a project page, calling an API endpoint, submitting a form, or rendering a merge request diff.
• Behavior: Puma processes the request immediately and returns an instant response to the user's browser.

Sidekiq (Background Job Processor)

Sidekiq is a background job processor for Ruby.

• Role: Handles asynchronous, background tasks.
• Examples: Triggering a CI/CD pipeline after a code push, sending email notifications, processing webhooks, or calculating repository statistics.
• Behavior: Instead of making the user wait for a heavy task to finish, Puma offloads the task to a queue. Sidekiq picks up the job from the queue and executes it in the background.

6. Deep Dive: Storage & Git Operations (Layer 4)

The storage layer is responsible for persisting data, caching sessions, and managing the physical Git repositories.

Redis (In-Memory Data Store)

Redis is an extremely fast, in-memory key-value database. Because it stores data in RAM, lookups operate at $O(1)$ time complexity.

• Use Cases:
  • Session Storage: Tracks logged-in user sessions.
  • Page Caching: Caches frequently accessed database queries.
  • Job Queues: Acts as the message broker and queue manager between Puma and Sidekiq.

PostgreSQL (Relational Database)

PostgreSQL is the main, permanent database for GitLab. It stores all structured, relational data.

• Stored Data: User profiles, project metadata, issues, merge request comments, pipeline execution records, permissions, and audit logs.
• Note: PostgreSQL never stores the actual source code files or Git repositories. It only stores the metadata about them.

Gitaly (Git Storage Service)

Gitaly is a specialized Git RPC service written in Go.

• Role: It is the only component in the entire GitLab architecture allowed to read from and write to the physical Git repository files on disk.
• Why Gitaly?: In older versions of GitLab, the Rails application made direct system calls to the local Git binary on shared NFS (Network File System) storage. This was slow, prone to file locking issues, and did not scale. Gitaly abstracts Git operations behind a high-performance gRPC API, allowing repository storage to scale independently of the application servers.

7. Step-by-Step Execution Flows

To see how these components interact, let's trace two common real-world scenarios.

Flow A: Accessing the GitLab Web UI via Browser (HTTPS)

When a user opens their browser and navigates to their GitLab project dashboard, the request flows vertically through the architecture:

Flow B: Pushing Code from Terminal (SSH)

When a developer runs git push origin main from their local terminal, the interaction triggers background automation:

8. Practical Guide: Setting Up Your GitLab Account & First Project

Follow these steps to set up a free GitLab SaaS account and initialize your first project.

Step 1: Registration

1. Navigate to gitlab.com.
2. Click Sign In and select the Register Now option.
3. Fill in your details:
   • First Name / Last Name
   • Username (e.g., devops_engineer_demo)
   • Email Address (Use a valid email for verification)
   • Password (Ensure it meets security complexity requirements)
4. Click Continue.

Step 2: Email Verification

1. Check your inbox for a verification code from GitLab.
2. Enter the 6-digit code (e.g., 202939) into the verification prompt.
3. Click Verify email address.

Step 3: Initial Profile Configuration

Select your role and intent to help GitLab customize your initial dashboard:

• Role: Select DevOps Engineer or Developer.
• Registration Objective: Select I want to explore GitLab to see if it is worth switching to.
• Usage Scope: Select Just me (for personal learning) or My company or team.
• Click Continue.

Step 4: Creating Your First Project

GitLab organizes work using Groups (namespaces) and Projects (repositories).

1. Enter a project name (e.g., demo-devops-project).
2. GitLab will automatically generate a project URL and path.
3. Choose whether the project should be Public (visible to anyone) or Private (restricted to authorized members).
4. Click Create project.

9. Exploring the GitLab UI: Project Management & Planning Features

Every GitLab project contains a suite of built-in project management tools. This eliminates the need for external ticketing systems like Jira.

Issues

Issues are the fundamental unit of planning in GitLab. They are used to track bugs, feature requests, and tasks.

• Creating an Issue: Navigate to Plan > Issues and click New Issue.
• Assignees: Assign the issue to a developer or DevOps engineer.
• Collaboration: Use the markdown-enabled description and comment section to log updates (e.g., "20% task completed"), upload screenshots, and tag team members.

Work Items & Tasks

For more granular tracking, GitLab supports Work Items.

• Tasks: Sub-units of work that can be created inside an issue. For example, if the main issue is "Update Feedback Page", the sub-tasks might be "Add feedback button" and "Write unit tests for feedback form".
• Incidents: Specialized work items created when a production alert is triggered. These are used by operations teams to track outages and resolution steps.

Issue Boards (Kanban)

Issue Boards provide a visual representation of your team's workflow.

• By default, boards contain columns like Open and Closed.
• You can create custom lists based on labels (e.g., To Do, In Progress, Under Review).
• Workflow: Drag and drop cards across columns to update their status instantly.

Milestones

A Milestone is a way to group issues and merge requests into a cohesive, time-boxed deliverable (similar to a Sprint in Agile methodologies).

• Configuration: Set a Start Date and a Due Date (e.g., a 2-week sprint).
• Tracking: GitLab automatically calculates and displays a completion percentage bar based on the number of closed issues assigned to that milestone.

10. Exploring the GitLab UI: Code, Build, Secure, and Deploy

The core of the DevSecOps lifecycle is managed through these four primary sections in the left-hand sidebar:

Code (Source Code Management)

• Repository: View the project's file directory, commit history, branches, and tags.
• Merge Requests (MRs): The GitLab equivalent of a GitHub Pull Request. This is where code reviews happen, and where automated CI/CD pipelines run to validate changes before they are merged into the main branch.

Build (Continuous Integration)

• Pipelines: View active and historical pipeline runs.
• Jobs: Inspect individual execution steps within a pipeline.
• Editor: A built-in YAML editor with real-time linting to write and modify your .gitlab-ci.yml configuration file.

Secure (Inbuilt Security Scanning)

Unlike other platforms that require complex third-party security integrations, GitLab includes native security scanners:

• SAST (Static Application Security Testing): Scans source code for known vulnerabilities and security flaws before compilation.
• Secret Detection: Scans commits to prevent developers from accidentally pushing API keys, passwords, or certificates to the repository.
• Dependency Scanning: Analyzes external libraries and packages imported by your application to ensure they do not contain known vulnerabilities.

Deploy (Continuous Delivery & Registries)

• Container Registry: A private, built-in Docker registry to store and version your container images.
• Package Registry: Supports hosting packages for npm, Maven, NuGet, PyPI, and more.
• Model Registry: A specialized registry designed to store, version, and manage machine learning models.

11. Exploring the GitLab UI: Operate, Monitor, Analyze, and AI Agents

The final stages of the lifecycle focus on infrastructure operations, application monitoring, performance analytics, and AI assistance.

Operate (Infrastructure as Code & Environments)

• Environments: Track where your code is deployed (e.g., Development, Staging, Production).
• Kubernetes Integration: Connect Kubernetes clusters directly to your project to enable cloud-native deployments.
• Terraform States: GitLab can act as a secure, remote backend for your Terraform state files, complete with state locking.

Monitor (Observability)

• Error Tracking: Aggregates application runtime errors so developers can debug issues directly from GitLab.
• Alerts & Incidents: Configures webhooks from external monitoring systems (like Prometheus or Datadog). If a metric breaches a threshold, GitLab generates an alert and can automatically escalate it to an incident.

Analyze (DevOps Metrics)

• Value Stream Analytics: Measures the time it takes for an idea to go from planning to production.
• CI/CD Analytics: Displays pipeline success rates, average execution durations, and deployment frequencies to help identify bottlenecks.

AI (GitLab Duo & Agents)

GitLab integrates artificial intelligence directly into the workflow:

• AI Agents: Specialized, pre-built virtual assistants configured for specific tasks:
  • CI Expert Agent: Helps write and debug complex .gitlab-ci.yml pipelines.
  • Security Analyst Agent: Explains vulnerabilities found during scans and suggests remediation code.
  • Data Analyst Agent: Helps interpret project metrics and trends.
• Sessions: A dedicated interface to interact with these AI agents and maintain a conversational history of your development queries.

Summary and Key Takeaways

• Unified Platform: GitLab is an all-in-one DevSecOps platform that replaces fragmented toolchains (such as GitHub + Jenkins + Jira + Nexus) with a single application, UI, and database.
• Git vs. GitLab: Git is the local command-line version control tool. GitLab is the enterprise platform that manages Git repositories and automates the surrounding software lifecycle.
• Puma vs. Sidekiq: Puma handles live, synchronous web requests (e.g., loading pages, API calls), while Sidekiq processes asynchronous background tasks (e.g., running pipelines, sending emails).
• GitLab Workhorse: This Go-based reverse proxy offloads heavy file transfers and artifact downloads, preventing the Rails application from blocking.
• Gitaly: Gitaly is the exclusive gRPC service responsible for reading and writing physical Git repository files on disk, ensuring high-performance storage operations.
• Redis & PostgreSQL: Redis is an in-memory database used for session caching and job queuing, while PostgreSQL is the permanent relational database storing all metadata (excluding repository files).
• Inbuilt Security: GitLab provides native security scanning (SAST, Secret Detection, Dependency Scanning) out of the box, shifting security left in the development cycle.
• Native Project Management: Features like Issues, Work Items, Kanban Boards, and Milestones allow teams to plan and track their work directly alongside their code.