- Software delivery
- Components
-
Adapting existing and introducing new components
- Simplified component overview
- Component diagram
- Component legend
- Component list
-
Component details
- Alertmanager
- Certificate management
- Consul
- Database migrations
- Elasticsearch
- Gitaly
- Praefect
- GitLab Geo
- GitLab Exporter
- GitLab agent
- GitLab Pages
- GitLab Runner
- GitLab Shell
- GitLab Workhorse
- Grafana
- Jaeger
- Logrotate
- Mattermost
- MinIO
- NGINX
- Node Exporter
- Patroni
- PgBouncer
- PgBouncer Exporter
- PostgreSQL
- PostgreSQL Exporter
- Prometheus
- Redis
- Redis Exporter
- Registry
- Sentry
- Sidekiq
- Puma
- LDAP Authentication
- Outbound Email
- Inbound Email
- GitLab by request type
- System layout
- Troubleshooting
- GitLab.com
GitLab architecture overview
Software delivery
There are two software distributions of GitLab:
- The open source Community Edition (CE).
- The open core Enterprise Edition (EE).
GitLab is available under different subscriptions.
New versions of GitLab are released from stable branches, and the main
branch is used for
bleeding-edge development.
For more information, visit the GitLab Release Process.
Both distributions require additional components. These components are described in the
Component details section, and all have their own repositories.
New versions of each dependent component are usually tags, but staying on the main
branch of the
GitLab codebase gives you the latest stable version of those components. New versions are
generally released around the same time as GitLab releases, with the exception of informal security
updates deemed critical.
Components
A typical install of GitLab is on GNU/Linux, but growing number of deployments also use the Kubernetes platform. The largest known GitLab instance is on GitLab.com, which is deployed using our official GitLab Helm chart and the official Linux package.
A typical installation uses NGINX or Apache as a web server to proxy through GitLab Workhorse and into the Puma application server. GitLab serves web pages and the GitLab API using the Puma application server. It uses Sidekiq as a job queue which, in turn, uses Redis as a non-persistent database backend for job information, metadata, and incoming jobs.
By default, communication between Puma and Workhorse is via a Unix domain socket, but forwarding
requests via TCP is also supported. Workhorse accesses the gitlab/public
directory, bypassing the
Puma application server to serve static pages, uploads (for example, avatar images or attachments),
and pre-compiled assets.
The GitLab application uses PostgreSQL for persistent database information (for example, users,
permissions, issues, or other metadata). GitLab stores the bare Git repositories in the location
defined in the configuration file, repositories:
section.
It also keeps default branch and hook information with the bare repository.
When serving repositories over HTTP/HTTPS GitLab uses the GitLab API to resolve authorization and access and to serve Git objects.
The add-on component GitLab Shell serves repositories over SSH. It manages the SSH keys within the
location defined in the configuration file, GitLab Shell
section.
The file in that location should never be manually edited. GitLab Shell accesses the bare
repositories through Gitaly to serve Git objects, and communicates with Redis to submit jobs to
Sidekiq for GitLab to process. GitLab Shell queries the GitLab API to determine authorization and access.
Gitaly executes Git operations from GitLab Shell and the GitLab web app, and provides an API to the GitLab web app to get attributes from Git (for example, title, branches, tags, or other metadata), and to get blobs (for example, diffs, commits, or files).
You may also be interested in the production architecture of GitLab.com.
Adapting existing and introducing new components
There are fundamental differences in how the application behaves when it is installed on a traditional Linux machine compared to a containerized platform, such as Kubernetes.
Compared to our official installation methods, some of the notable differences are:
- Official Linux packages can access files on the same file system with different services. Shared files are not an option for the application running on the Kubernetes platform.
- Official Linux packages by default have services that have access to the shared configuration and network. This is not the case for services running in Kubernetes, where services might be running in complete isolation, or only accessible through specific ports.
In other words, the shared state between services needs to be carefully considered when architecting new features and adding new components. Services that need to have access to the same files, need to be able to exchange information through the appropriate APIs. Whenever possible, this should not be done with files.
Since components written with the API-first philosophy in mind are compatible with both methods, all new features and services must be written to consider Kubernetes compatibility first.
The simplest way to ensure this, is to add support for your feature or service to the official GitLab Helm chart or reach out to the Distribution team.
Refer to the process for adding new service components for more details.
Simplified component overview
This is a simplified architecture diagram that can be used to understand the GitLab architecture.
A complete architecture diagram is available in our component diagram below.
Component diagram
Component legend
- ✅ - Installed by default
- ⚙ - Requires additional configuration
- ⤓ - Manual installation required
- ❌ - Not supported or no instructions available
- N/A - Not applicable
Component statuses are linked to configuration documentation for each component.
Component list
Component | Description | Omnibus GitLab | GitLab Environment Toolkit (GET) | GitLab chart | minikube Minimal | GitLab.com | Source | GDK | CE/EE |
---|---|---|---|---|---|---|---|---|---|
Certificate Management | TLS Settings, Let’s Encrypt | ✅ | ✅ | ✅ | ⚙ | ✅ | ⚙ | ⚙ | CE & EE |
Consul | Database node discovery, failover | ⚙ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | EE Only |
Database Migrations | Database migrations | ✅ | ✅ | ✅ | ✅ | ✅ | ⚙ | ✅ | CE & EE |
Elasticsearch | Improved search within GitLab | ⤓ | ⚙ | ⤓ | ⤓ | ✅ | ⤓ | ⚙ | EE Only |
Gitaly | Git RPC service for handling all Git calls made by GitLab | ✅ | ✅ | ✅ | ✅ | ✅ | ⚙ | ✅ | CE & EE |
GitLab Exporter | Generates a variety of GitLab metrics | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | CE & EE |
GitLab Geo | Geographically distributed GitLab site | ⚙ | ⚙ | ❌ | ❌ | ✅ | ❌ | ⚙ | EE Only |
GitLab Pages | Hosts static websites | ⚙ | ⚙ | ❌ | ❌ | ✅ | ⚙ | ⚙ | CE & EE |
GitLab agent | Integrate Kubernetes clusters in a cloud-native way | ⚙ | ⚙ | ⚙ | ❌ | ❌ | ⤓ | ⚙ | EE Only |
GitLab self-monitoring: Alertmanager | Deduplicates, groups, and routes alerts from Prometheus | ⚙ | ⚙ | ✅ | ⚙ | ✅ | ❌ | ❌ | CE & EE |
GitLab self-monitoring: Grafana | Metrics dashboard | ✅ | ✅ | ⚙ | ⤓ | ✅ |