GitLab Premium

Installation system requirements ALL TIERSSELF-MANAGED
This page includes information about the minimum requirements you need to install and use GitLab.

Hardware requirements
Storage
The necessary hard drive space largely depends on the size of the repositories you want to store in GitLab but as a guideline you should have at least as much free space as all your repositories combined take up.

The Omnibus GitLab package requires about 2.5 GB of storage space for installation.

If you want to be flexible about growing your hard drive space in the future consider mounting it using logical volume management (LVM) so you can add more hard drives when you need them.

Apart from a local hard drive you can also mount a volume that supports the network file system (NFS) protocol. This volume might be located on a file server, a network attached storage (NAS) device, a storage area network (SAN) or on an Amazon Web Services (AWS) Elastic Block Store (EBS) volume.

If you have enough RAM and a recent CPU the speed of GitLab is mainly limited by hard drive seek times. Having a fast drive (7200 RPM and up) or a solid state drive (SSD) improves the responsiveness of GitLab.

Because file system performance may affect the overall performance of GitLab, we don’t recommend using cloud-based file systems for storage.
NFS for Git repository storage is deprecated. See our official Statement of Support for further information.
CPU
CPU requirements are dependent on the number of users and expected workload. Your exact needs may be more, depending on your workload. Your workload is influenced by factors such as - but not limited to - how active your users are, how much automation you use, mirroring, and repository/change size.

The following is the recommended minimum CPU hardware guidance for a handful of example GitLab user base sizes.

4 cores is the recommended minimum number of cores and supports up to 500 users
8 cores supports up to 1000 users
More users? Consult the reference architectures page
Memory
Memory requirements are dependent on the number of users and expected workload. Your exact needs may be more, depending on your workload. Your workload is influenced by factors such as - but not limited to - how active your users are, how much automation you use, mirroring, and repository/change size.

The following is the recommended minimum Memory hardware guidance for a handful of example GitLab user base sizes.

4 GB RAM is the required minimum memory size and supports up to 500 users
Our Memory Team is working to reduce the memory requirement.
8 GB RAM supports up to 1000 users
More users? Consult the reference architectures page
In addition to the above, we generally recommend having at least 2 GB of swap on your server, even if you currently have enough available RAM. Having swap helps to reduce the chance of errors occurring if your available memory changes. We also recommend configuring the kernel’s swappiness setting to a low value like 10 to make the most of your RAM while still having the swap available when needed.

Although excessive swapping is undesired and degrades performance, it is an extremely important last resort against out-of-memory conditions. During unexpected system load, such as OS updates or other services on the same host, peak memory load spikes could be much higher than average. Having plenty of swap helps avoid the Linux OOM killer unsafely terminating a potentially critical process, such as PostgreSQL, which can have disastrous consequences.
Database
PostgreSQL is the only supported database, which is bundled with the Omnibus GitLab package. You can also use an external PostgreSQL database. Support for MySQL was removed in GitLab 12.1.

PostgreSQL Requirements
The server running PostgreSQL should have at least 5-10 GB of storage available, though the exact requirements depend on the number of users.

We highly recommend using at least the minimum PostgreSQL versions (as specified in the following table) as these were used for development and testing:

GitLab version     Minimum PostgreSQL version
13.0    11
14.0    12.7
15.0    12.10
16.0    13.6

You must also ensure the following extensions are loaded into every GitLab database. Read more about this requirement, and troubleshooting.

Extension    Minimum GitLab version
pg_trgm    8.6
btree_gist    13.1
plpgsql    11.7

The following managed PostgreSQL services are known to be incompatible and should not be used:

GitLab version    Managed service
14.4+    Amazon Aurora (see 14.4.0)

Additional requirements for GitLab Geo
If you’re using GitLab Geo, we strongly recommend running Omnibus GitLab-managed instances, as we actively develop and test based on those. We try to be compatible with most external (not managed by Omnibus GitLab) databases (for example, AWS Relational Database Service (RDS)), but we can’t guarantee compatibility.

Operating system locale compatibility and silent index corruption
Changes to locale data in glibc means that PostgreSQL database files are not fully compatible between different OS releases.

To avoid index corruption, check for locale compatibility when:

Moving binary PostgreSQL data between servers.
Upgrading your Linux distribution.
Updating or changing third party container images.
Gitaly Cluster database requirements
Read more in the Gitaly Cluster documentation.

Exclusive use of GitLab databases
Databases created or used for GitLab, Geo, Gitaly Cluster, or other components should be for the exclusive use of GitLab. Do not make direct changes to the database, schemas, users, or other properties except when following procedures in the GitLab documentation or following the directions of GitLab Support or other GitLab engineers.

The main GitLab application currently uses three schemas:

The default public schema
gitlab_partitions_static (automatically created)
gitlab_partitions_dynamic (automatically created)
No other schemas should be manually created.

GitLab may create new schemas as part of Rails database migrations. This happens when performing a GitLab upgrade. The GitLab database account requires access to do this.

GitLab creates and modifies tables during the upgrade process, and also as part of standard operations to manage partitioned tables.

You should not modify the GitLab schema (for example, adding triggers or modifying tables). Database migrations are tested against the schema definition in the GitLab codebase. GitLab version upgrades may fail if the schema is modified.

Puma settings
The recommended settings for Puma are determined by the infrastructure on which it’s running. The GitLab Linux package defaults to the recommended Puma settings. Regardless of installation method, you can tune the Puma settings:

If you’re using the GitLab Linux package, see Puma settings for instructions on changing the Puma settings.
If you’re using the GitLab Helm chart, see the webservice chart.
Puma workers
The recommended number of workers is calculated as the highest of the following:

2
A combination of CPU and memory resource availability (see how this is configured automatically for the Linux package).
Take for example the following scenarios:

A node with 2 cores / 8 GB memory should be configured with 2 Puma workers.

A node with 4 cores / 4 GB memory should be configured with 2 Puma workers.

A node with 4 cores / 8 GB memory should be configured with 4 Puma workers.

So, the highest from 2 and 4 is 4.

You can increase the number of Puma workers, provided enough CPU and memory capacity is available. A higher number of Puma workers usually helps to reduce the response time of the application and increase the ability to handle parallel requests. You must perform testing to verify the optimal settings for your infrastructure.

Puma threads
The recommended number of threads is dependent on several factors, including total memory, and use of legacy Rugged code.

If the operating system has a maximum 2 GB of memory, the recommended number of threads is 1. A higher value results in excess swapping, and decrease performance.
If legacy Rugged code is in use, the recommended number of threads is 1.
In all other cases, the recommended number of threads is 4. We don’t recommend setting this higher, due to how Ruby MRI multi-threading works.
Puma per worker maximum memory
By default, each Puma worker is limited to 1.2 GB of memory. You can adjust this memory setting and should do so if you must increase the number of Puma workers.

Redis
Redis stores all user sessions and the background task queue.

The requirements for Redis are as follows:

Redis 6.0 is required from GitLab 16.0 and later.
Redis Cluster mode is not supported. Redis Standalone must be used.
Storage requirements for Redis are minimal, about 25 kB per user on average.
Sidekiq
Sidekiq processes the background jobs with a multithreaded process. This process starts with the entire Rails stack (200 MB+) but it can grow over time due to memory leaks. On a very active server (10,000 billable users) the Sidekiq process can use 1 GB+ of memory.

Prometheus and its exporters
Prometheus and its related exporters are enabled by default to enable in depth monitoring of GitLab. With default settings, these processes consume approximately 200 MB of memory.

If you would like to disable Prometheus and it’s exporters or read more information about it, check the Prometheus documentation.

GitLab Runner
We strongly advise against installing GitLab Runner on the same machine you plan to install GitLab on. Depending on how you decide to configure GitLab Runner and what tools you use to exercise your application in the CI environment, GitLab Runner can consume significant amount of available memory.

Memory consumption calculations, that are available above, are not valid if you decide to run GitLab Runner and the GitLab Rails application on the same machine.

It’s also not safe to install everything on a single machine, because of the security reasons, especially when you plan to use shell executor with GitLab Runner.

We recommend using a separate machine for each GitLab Runner, if you plan to use the CI features. The GitLab Runner server requirements depend on:

The type of executor you configured on GitLab Runner.
Resources required to run build jobs.
Job concurrency settings.
Because the nature of the jobs varies for each use case, you must experiment by adjusting the job concurrency to get the optimum setting.

For reference, the SaaS runners on Linux are configured so that a single job runs in a single instance with:

1 vCPU.
3.75 GB of RAM.
Supported web browsers
With GitLab 13.0 (May 2020) we have removed official support for Internet Explorer 11.
GitLab supports the following web browsers:

Mozilla Firefox
Google Chrome
Chromium
Apple Safari
Microsoft Edge
For the listed web browsers, GitLab supports:

The current and previous major versions of browsers.
The current minor version of a supported major version.
We don’t support running GitLab with JavaScript disabled in the browser and have no plans of supporting that in the future because we have features such as issue boards which require JavaScript extensively.
Security
After installation, be sure to read and follow guidance on maintaining a secure GitLab installation.

In GitLab 13.7 and later, the Maximum Users value found in self-managed instances of GitLab reflects the maximum daily active user count recorded in the instance during the current license period.

Prior to GitLab 13.7, the Maximum Users value found in self-managed instances of GitLab reflects the maximum daily active user count recorded in the instance for the period of 1 year prior to the expiration date of the license. Since most GitLab subscriptions are annual, this means the Maximum User count in these cases is simply the highest number of active users at any one time during that subscription. However, for non-standard contract lengths (8 months, 14 months, 24 months), the Maximum Users count is not reflective of the entire subscription term, but rather for the 12 months prior to the expiration date.

The seats for your license are generic and are not specific to a user. GitLab does
not use a named license model.

The seats you buy can be distributed however you choose. If a user leaves your
organization, you can remove or block that user to free the seat. This seat can
then be used by another user.

Note that this may result in a user over license if your maximum users has been reached.

You can add users to your subscription any time during the subscription period. The cost of additional users added during the subscription period will be prorated from the date of purchase through the end of
the subscription period.

To do this:

Log into your account via the Customers Portal
Select Manage Purchases from the menu.
Select the Add more seats button.
Enter the amount of additional users (E.g. You currently have 10 users and want to add 5 more users, enter 5).
Select Proceed to checkout.
Review the Subscription Summary. Note you will only be charged for the net additional users.
Update or add the desired payment information.
Select Purchase Seats

The following will be emailed to you:

A confirmation of purchase and payment receipt. You can also access this information in the Customers Portal under View invoices.
For self-managed instances on legacy or offline licensing, you will receive a new license key. Upload this license to your instance to use it.

Maxmimum Users will be reset once the current license is expired and a new license with a new service period is uploaded. See Maximum Users.

Users over license can be reset either:

During the current license service period by Adding more seats to the subscription so that your total Users in License meet or exceed your current Maximum Users
By paying for True-Up Users at your renewal. During your renewal, you can pay for the overage from your prior subscription period, these are called "True-Up Users".