GitLab Self-Managed Infrastructure and On-Premises Deployment

The implementation of a self-managed GitLab instance represents a strategic shift in how an organization handles its source code management, continuous integration, and DevOps orchestration. Unlike cloud-hosted solutions, an on-premises deployment grants the operator absolute sovereignty over the data residency, the hardware specifications, and the network perimeter. This architectural choice is often driven by stringent security requirements, the need for air-gapped environments, or the desire to integrate deeply with existing internal infrastructure. A self-managed instance is not merely a piece of software installed on a server; it is a complex ecosystem of interacting services, including application servers, job queues, persistent databases, and reverse proxies, all of which must be meticulously configured to ensure high availability and performance.

The complexity of a GitLab on-premises installation extends beyond the initial apt install command. It requires a deep understanding of the underlying Linux environment, specifically the management of system locales, the configuration of kernel parameters via sysctl, and the orchestration of networking components. When deployed within a cloud environment like Google Cloud Platform (GCP), the challenges expand to include DNS resolution strategies, the utilization of Internet Network Endpoint Groups (NEGs), and the configuration of Private Service Connect (PSC). The synergy between the software layer—comprising Puma, Sidekiq, and Gitaly—and the infrastructure layer—comprising VPCs, subnets, and load balancers—determines the overall stability and scalability of the DevOps pipeline.

Architectural Components and Service Interdependencies

The GitLab architecture is designed as a series of specialized components that handle specific types of traffic and data processing. This modularity allows the system to scale different parts of the application independently, although in a single-node installation, these all run on the same machine.

The primary entry point for web traffic and API requests is the Puma application server. Puma serves the web pages and handles the GitLab API. However, because some HTTP requests are too large or too long-lived for a standard application server to handle efficiently, GitLab utilizes GitLab Workhorse. Workhorse acts as a smart reverse proxy that handles large HTTP requests and serves static assets. By accessing the gitlab/public directory directly, Workhorse can bypass Puma entirely for static pages, avatar images, and pre-compiled assets, which significantly reduces the load on the application server. While the default communication between Puma and Workhorse occurs via a Unix domain socket, the system also supports forwarding requests via TCP for more flexible networking configurations.

For asynchronous processing, GitLab employs Sidekiq. Sidekiq serves as the job queue, managing background tasks such as email delivery, CI/CD pipeline triggers, and system maintenance. Sidekiq relies on Redis as a non-persistent database backend. Redis stores the metadata and the actual job information for the incoming queue. This ensures that the main application server remains responsive by offloading time-consuming tasks to the background.

Data persistence is handled by PostgreSQL, which stores all critical metadata, including user accounts, permissions, issue trackers, and merge request details. The actual Git repositories, however, are stored as bare repositories in a specific filesystem location defined in the configuration file. To manage these repositories, GitLab uses Gitaly. Gitaly is the service that allows GitLab to interact with the bare Git repositories. When a user accesses a repository via SSH, the GitLab Shell component manages the session and uses Gitaly to serve the Git objects, while communicating with Redis to submit necessary jobs to Sidekiq.

The networking layer is further reinforced by NGINX, which is bundled as a core service processor. NGINX provides the ingress port for all incoming HTTP requests and routes them to the appropriate internal sub-systems. For monitoring the health of these services, GitLab integrates Node Exporter, a Prometheus tool that provides critical metrics regarding the underlying machine's CPU, disk usage, and system load.

On-Premises Installation and Server Hardening

Deploying GitLab on a single node requires a systematic approach to server preparation. The process begins with the fundamental operating system configuration, typically on a Debian-based system. Before the application is installed, the server must be updated and the necessary dependencies must be present.

The mandatory dependencies for a successful installation include:

• curl for retrieving installation scripts.
• openssh-server to allow remote administrative access.
• ca-certificates to ensure secure SSL/TLS connections.
• perl for script execution.
• locales for system language support.

A critical step in the installation process is the configuration of the system language. The administrator must edit the /etc/locale.gen file to ensure that en_US.UTF-8 is uncommented. Following this modification, the sudo locale-gen command must be executed to regenerate the languages. Failure to do this can lead to character encoding issues within the GitLab interface and database.

The installation of the GitLab Enterprise Edition (EE) package follows a specific sequence:

1. The GitLab package repository is added to the system using a curl command that pipes a shell script into bash: curl --location "https://packages.gitlab.com/install/repositories/gitlab Omnibus/gitlab-ee/script.deb.sh" | sudo bash.
2. The package is then installed using the apt package manager. During this step, two critical environment variables must be defined: GITLAB_ROOT_PASSWORD for the initial administrator account and EXTERNAL_URL for the public-facing address of the instance.
3. The installation command is executed as follows: sudo GITLAB_ROOT_PASSWORD="strong password" EXTERNAL_URL="https://gitlab.example.com" apt install gitlab-ee.

It is essential to include https in the EXTERNAL_URL to allow the system to automatically issue a Let's Encrypt certificate. Once the installation is complete, the administrator can access the instance using the username root and the password specified during the installation.

Google Cloud Platform Integration and Networking

When deploying GitLab on-premises but within a cloud environment like GCP, the networking architecture becomes significantly more complex, particularly when using Private Service Connect (PSC) and Internet Network Endpoint Groups (NEGs).

In a scenario where a GitLab instance is hosted on-premises and needs to be accessed via a Google Cloud Load Balancer, an Internet NEG is utilized. The Internet NEG defines an external backend for the load balancer, using a Fully Qualified Domain Name (FQDN) that denotes the on-premises GitLab instance. The Backend Service then acts as a bridge, connecting the load balancer to the Internet NEG.

A critical aspect of this configuration is the handling of source IP addresses. When packets are sent from a proxy to a backend VM or endpoint, they carry a source IP address originating from the proxy-only subnet. This is vital for security auditing and routing.

Validation of this connectivity often requires a dedicated GCE instance. For example, to validate DNS resolution to an instance such as gitlabonprem.com, a GCE instance can be created using the following command:

bash gcloud compute instances create gce-dns-lookup \ --project=$projectid \ --machine-type=e2-micro \ --image-family debian-11 \ --no-address \ --image-project debian-cloud \ --zone us-central1-a \ --subnet=producer-psc-fr-subnet

To test the connectivity, the administrator must access the VM via Identity-Aware Proxy (IAP) using:

bash gcloud compute ssh gce-dns-lookup --project=$projectid --zone=us-central1-a --tunnel-through-iap

Initially, a ping gitlabonprem.com command is expected to fail with the error ping: gitlabonprem.com: Name or service not known. This failure indicates that a Private DNS zone must be created for gitlabonprem.com to resolve the FQDN within the VPC.

Tiered Features and Enterprise Capabilities

GitLab's pricing and feature set are divided into tiers, with the Ultimate tier providing advanced security and governance tools that are unavailable in the Free and Premium versions.

The following table details the availability of key components across the GitLab ecosystem:

The Ultimate tier specifically enhances the Security Analysis (SAST) and Container Scanning capabilities. While Free and Premium tiers output results as JSON-formatted artifact files, the Ultimate tier integrates these findings directly into the GitLab UI. This includes vulnerability reports, dependency lists, and inline displays within merge requests. Ultimate also allows for the customization of rulesets for Secret Detection and SAST, as well as the management of CVE allowlists for Container Scanning. Furthermore, it enables the requirement of security approvals for merge requests that impact the security posture of the project.

Support for paid plans is governed by Service Level Agreements (SLAs) based on the impact of the request. Emergency (Severity 1) issues receive 24/7 support, whereas other levels are handled on a 24/5 basis.

Storage and Monitoring Infrastructure

A production-ready GitLab installation requires a robust strategy for object storage and system monitoring.

GitLab requires S3-compatible object storage for storing CI artifacts, Large File Storage (LFS) objects, uploads, and container registry images. The system is compatible with any provider offering a full S3 API. Common choices include:

• Amazon S3
• Google Cloud Storage
• Azure Blob Storage
• Self-hosted S3-compatible solutions (e.g., MinIO)

For monitoring, GitLab incorporates several tools to ensure the stability of the distributed system. Prometheus is used for time-series data and metrics collection. Grafana provides the visualization layer for these metrics via dashboards. For distributed tracing, Jaeger is integrated to view traces generated by the GitLab instance, which is critical for debugging microservices-based latency issues.

Log management is handled by a bundled version of Logrotate. Given that GitLab consists of numerous services, each generating its own logs, Logrotate ensures that the disk space is not exhausted by old log files, maintaining system availability.

Conclusion

The deployment of GitLab on-premises is a sophisticated engineering effort that balances the flexibility of open-source software with the rigidity of enterprise-grade security and networking. The architecture relies on a tightly coupled set of services—Puma for the web, Sidekiq for background jobs, Redis for caching, and PostgreSQL for persistence—all orchestrated behind an NGINX and Workhorse proxy. When this setup is extended into a cloud environment like GCP, the reliance on Internet NEGs and Private Service Connect highlights the necessity of precise DNS and subnet configuration to ensure that traffic reaches the on-premises destination.

The transition from a basic installation to an Ultimate-tier deployment transforms GitLab from a simple version control system into a comprehensive security and governance platform. The ability to track vulnerabilities over time and enforce security approvals in merge requests provides a level of oversight that is essential for regulated industries. Ultimately, the success of a self-managed GitLab instance depends on the administrator's ability to manage the underlying Linux environment, optimize the Gitaly storage layer, and maintain a rigorous monitoring stack using Prometheus and Grafana.

Sources

1. Google Codelabs: Looker PSC Internet NEG
2. GitLab Architecture Documentation
3. GitLab Pricing
4. GitLab Single Node Installation Tutorial