Why Redis or Valkey decides part of your GitLab high availability design
If you are sizing self-managed GitLab, you will need to choose a Redis-compatible store early, because the layout you pick for high availability depends on it. The supported path for GitLab is Redis or Valkey run with Sentinel for high availability, so the decision is less about whether to run a store and more about which engine, which version and how many Sentinel instances. Inside GitLab, this store holds shared, fast-access state that the application and background workers use while serving requests and processing jobs, so a failed or unreachable store affects the whole instance, not one feature.
The decision matters most once you move past a single server. A single-node Linux package install bundles Redis, and that is a reasonable starting point for small instances. Multi-node layouts, such as the 3,000-user high availability design and the larger reference architectures, separate the store onto its own nodes and rely on Sentinel to promote a replica when the primary fails. At that point the engine, the version line and the Sentinel topology are part of the architecture document, and they affect upgrades, backups and failover testing. Confirm the exact Redis or Valkey version your target GitLab release supports in the GitLab documentation before you pick a line, because the store version must match what GitLab tests against.
Start by writing down three things: the reference architecture you are targeting, whether you will run the store on virtual machines or use a managed service, and who will own patching for that tier. Ask your GitLab support or implementation partner to confirm the supported engine and version for that release, and whether your licensing position allows the Redis line you are considering. Then plan the Sentinel quorum across at least three hosts and test a forced failover before go-live. Those checks decide whether the store supports your high availability goal, and they are easier to settle before the infrastructure is ordered.
Which store fits which situation
If your GitLab instance already runs Redis 7.2.x or an earlier release, the license question is the simplest of the four cases. The Redis licenses page places 7.2.x and earlier under BSD-3-Clause, and the Redis licensing FAQ says teams moving from these versions with unmodified Redis artifacts see no impact. Staying put is a valid choice, but the upgrade question returns at your next major platform change.
- License. BSD-3-Clause for 7.2.x and earlier. Confirm that your build is unmodified before relying on the no-impact statement.
- Migration effort. None for the store itself while you stay on the same line. Your work is confirming that the version you run is one GitLab supports for your release.
- Future moves. Redis 7.4.x through 7.8.x fall under RSALv2 or SSPLv1, so any upgrade past 7.2 changes the license posture. Treat that as a separate decision with its own review.
- Version support. Confirm in GitLab's installation and reference architecture documentation which Redis versions your GitLab release supports, and whether your installation method bundles its own Redis.
Record the output of the Redis version command on each node in the change plan, and check it again before every GitLab upgrade stop.
Valkey 7.2 is the option for teams that want to stay on a Redis-compatible line under a permissive license. Valkey is licensed under BSD-3-Clause, was forked from open-source Redis before the source-available change, and is an open community project under LF Projects, LLC. The Valkey migration guide describes moving from Redis OSS 7.2 and earlier as effectively an upgrade, because Valkey is compatible with those versions.
- License. BSD-3-Clause, with governance under the Linux Foundation through LF Projects. The server carries no source-available terms.
- Migration method. The guide documents copying an RDB snapshot, or replicating with REPLICAOF and then promoting the replica. Key-level MIGRATE suits moving selected keys only, and the cluster method does not apply because GitLab does not use Redis Cluster.
- Compatibility. Existing Redis client libraries connect without code changes, and the guide says Valkey reads and writes RDB and AOF files compatible with Redis OSS 7.2. Confirm any module your deployment relies on, because the guide documents RedisModule_ API compatibility, not a full list of modules.
- Version line. Valkey 7.2 is still maintained, with 7.2.14 published on July 21, 2026. Newer lines such as 9.1 are separate choices that need their own support check.
- Support statement. Protocol compatibility does not by itself confirm that GitLab supports Valkey, so ask GitLab for an explicit statement for your release.
Test the snapshot or replica method on a copy of production data before you schedule the cutover window.
Redis 8.0 changed the license model. According to the Redis licenses page, Redis Open Source 8.0 and later can be used under a license of your choice among RSALv2, SSPLv1 and AGPLv3, effective from the general availability release of Redis 8. Redis 8.0.0 was published on May 2, 2025. This line adds features such as JSON, time series, probabilistic structures and the query engine, which GitLab does not need, so the main reason to adopt it is the license option and continuity with the Redis line.
- License. You choose one of RSALv2, SSPLv1 or AGPLv3. Legal review should record which option applies to your deployment.
- Network service caveat. The Redis FAQ says teams offering modified Redis code as a network service must make the modified source available to that service's users. Unmodified use is a different case, so confirm the reading with counsel.
- Migration effort. Redis 8 is a major line change, and the Valkey migration guide does not cover it. Plan a test upgrade from your 7.2 data and confirm data file compatibility in your own environment.
- Supported versions. Confirm with GitLab whether your release supports Redis 8.x. Do not assume support from the version number.
- Enabled features. Leave optional modules off unless GitLab requires them, because each one adds configuration to review.
Get the license decision and GitLab's support statement in writing before the upgrade ticket is approved.
For a new GitLab deployment, the decision is among Redis 7.2 under BSD-3-Clause, Valkey under BSD-3-Clause, and Redis 8 or later under the license you select. The choice should follow your license policy, the versions GitLab supports at go-live, and your upgrade plan. Starting on a line that GitLab documents for your release is the lowest-risk path, because it avoids a store migration in the first year of operation.
- License policy. BSD-3-Clause options avoid source-available terms. Redis 8 offers AGPLv3 as one of its choices, which some policies accept.
- Version line. Confirm which Redis or Valkey lines GitLab's documentation lists for the release you install. Valkey 9.1 is the current stable line, while 7.2 remains maintained for teams that need an older line.
- Installation method. The Linux package bundles Redis, which may not match an external Valkey or Redis deployment. Check the installation documentation before you decide between bundled and external stores.
- Topology. Sentinel-based high availability needs at least three Sentinel instances, according to the Redis and Valkey Sentinel documentation. Redis Cluster is not part of the GitLab design, so plan around Sentinel.
- Architecture record. Keep the chosen version, license decision and Sentinel layout in the architecture record so that upgrades start from a known baseline.
Ask GitLab for the exact supported version list for your release before you order hosts or pull images.
How to set up Sentinel-based Redis or Valkey for GitLab
This sequence builds a primary, at least one replica and a three-or-more Sentinel quorum, connects GitLab to Sentinel, and proves that failover works before go-live. The result is a Redis or Valkey tier that survives loss of the primary without a manual change to GitLab.
Confirm the supported Redis or Valkey version
Check the GitLab release you plan to run against the Redis and Valkey guidance in GitLab's installation and reference architecture documentation, and record the exact Redis or Valkey version that release supports. Valkey is compatible with Redis OSS 7.2 and earlier open-source versions, while Redis 7.4 to 7.8 uses licenses that are not OSI-approved and writes data files that Valkey cannot read. Done when the platform owner has a signed version record tied to the upgrade plan.
Provision three or more Sentinel instances
The platform team deploys at least three Sentinel instances, as the Redis and Valkey Sentinel documentation recommends, and places them on hosts separate from the data nodes so one host failure does not remove the quorum. Install the same release line on every Sentinel host and open the Sentinel port between them and the data nodes. Done when each Sentinel responds to the matching CLI with the Sentinel info command and can reach the others.
Configure the primary and replicas
Install the chosen release on the primary and at least one replica, point the replica at the primary, and set a password on both. Bind each instance to a private interface and set persistence to match your recovery plan. Done when INFO replication on the primary lists the connected replica and the replica reports its master link as up.
Point each Sentinel at the primary
On every Sentinel host, define the monitored primary with a master name, its address and a quorum value you choose from the Sentinel documentation, and add the replication password and the failover timeouts your network needs. Start each Sentinel in turn so the configuration is written. Done when the Sentinel command that returns the master address by name gives the same primary address on all three hosts.
Set GitLab connection settings for Sentinel
In gitlab.rb on each GitLab node that uses Redis, add the Sentinel hosts, the master name and the authentication settings that your installation method requires, then confirm the exact key names against GitLab's Redis configuration documentation. Run gitlab-ctl reconfigure and review the output for errors. Done when the reconfigure run completes on every node and GitLab reports its services running and connected to Redis.
Verify failover with a controlled test
In a planned maintenance window, queue a few background jobs, then stop the Redis process on the primary on purpose. Watch Sentinel promote a replica, confirm the master address now points to the new primary on every Sentinel, and check that GitLab keeps serving requests and processing the queued jobs. Restart the old primary so it rejoins as a replica. Done when the test record shows the promotion, the GitLab behavior during failover and the replica state afterward.
Why Redis Cluster and serverless offerings fall outside the supported design
GitLab's high availability guidance for Redis uses Redis Sentinel, not Redis Cluster. Sentinel is the high availability option when you are not running Redis or Valkey Cluster, and it handles automatic failover by promoting a replica to primary. Redis Cluster is not supported for self-managed GitLab, so a design that shards Redis across cluster nodes is outside the documented architecture even if the software can run it. Plan for at least three Sentinel instances, as both the Redis and Valkey Sentinel documentation recommend, and keep them on separate failure domains so that one host loss does not remove quorum.
Serverless and fully managed Redis-compatible offerings are also not part of the documented GitLab design. The reference architectures describe Redis as a stateful component that runs on virtual machines or in a managed service, and the Cloud Native Hybrid pattern keeps stateful services out of Kubernetes. Before you choose a managed cloud Redis product, confirm in the reference architecture documentation whether that exact service type and its failover model are covered. Ask the provider how it exposes replication and Sentinel-compatible endpoints, because a managed service that hides those behaviors can change how GitLab detects and recovers from a primary failure.
Treat these support statements as a point-in-time reading. Check the current GitLab reference architecture page for the Redis topology, the supported Sentinel setup and any managed-service notes before you commit to a design, and record the GitLab version you validated against. If your team is considering Redis Cluster for scale, ask GitLab support or your implementation partner to confirm the sharding limits in writing before you build anything that depends on them.
Eviction policy settings that protect GitLab data
Redis and Valkey hold GitLab state that is not all disposable, so memory limits and eviction behavior can silently discard data that GitLab expects to find. The cards below cover the settings and risks that decide whether a memory spike causes a slowdown or a loss, and what to confirm against GitLab's documented guidance for your scale.
Set a deliberate maxmemory limit
The maxmemory key caps how much data the server holds before it starts evicting or refusing writes. Without a limit, a busy instance can grow until the operating system kills it or swaps heavily. Ask your GitLab sizing guidance for the memory each Redis role should receive at your user count, then set the limit to match that figure rather than to whatever the host happens to have free.
Choose the eviction policy with care
The maxmemory-policy key decides which keys Redis or Valkey removes when it reaches the limit. Policies that evict keys with a time-to-live only affect expiring data, while policies that touch any key can remove entries GitLab still needs. Confirm in GitLab's documentation which policy it expects for each Redis instance, and treat any deviation as a change to test in staging first.
Separate persistence from cache use
GitLab uses Redis for both transient cache and data that must survive a restart, such as queue state. Mixing both on one instance means a cache-sized eviction policy can remove job data. Ask GitLab whether your reference design assigns cache and persistence roles to separate instances, and confirm the persistence settings for each role with your GitLab version's configuration guide.
Keep memory headroom for growth
Redis needs memory beyond the dataset for replication buffers, forks used during snapshots and client output buffers. A limit set close to total host memory leaves no room for these during a failover or a large background save. Ask how much headroom GitLab recommends for your instance size and whether your monitoring alerts before the limit is reached, not after.
Monitor evictions and memory use
A rising count of evicted keys is an early sign that the limit is too low or the policy is removing data GitLab needs. Track the eviction counter, memory used against the limit and the rate of change alongside GitLab's Prometheus metrics. Set an alert for any nonzero eviction count on instances where eviction should never happen, and review the trend during load tests.
Align Sentinel with the primary configuration
Sentinel promotes a replica after a failure, and the new primary must carry the same memory limit, eviction policy and persistence settings as the old one. A replica configured differently can behave in unexpected ways after promotion. Review the Sentinel configuration whenever you change memory settings on the primary, and confirm the replica settings after each GitLab or Redis or Valkey upgrade.
Questions teams ask before building Redis or Valkey for GitLab
Can Valkey replace Redis for GitLab without code changes?
For client connections, usually yes, but the answer depends on the Redis version you run today. Valkey is compatible with Redis OSS 7.2 and earlier open-source Redis versions, and existing Redis client libraries connect to Valkey without code changes. Valkey also reads and writes RDB and AOF files compatible with Redis OSS 7.2. If your current Redis is 7.4 or later, the data files are not compatible, and the Valkey migration guide does not cover that path, so you need a different method. Before you choose, confirm which Redis and Valkey versions your target GitLab release supports in GitLab's documentation, because that support statement decides the version you deploy.
How much migration effort depends on your current Redis version?
Effort depends mainly on your current Redis version, data volume, topology and tolerance for write downtime. According to the Valkey migration guide, moving from Redis OSS 2.x through 7.2.x to Valkey 7.2 or later is effectively an upgrade. The guide documents four methods: copying an RDB snapshot, replicating with REPLICAOF and then promoting the replica, moving selected keys with MIGRATE, and adding Valkey nodes as replicas in a cluster. Each method has different cutover and rollback steps. Ask for a written inventory of current versions, data size, the cutover window, a rollback plan, and a rehearsal in a non-production environment before any production cutover.
Can you use Redis Cluster for GitLab high availability?
Plan for Sentinel-based high availability rather than Redis Cluster. Redis Sentinel provides high availability when you are not using Redis Cluster, including automatic failover that promotes a replica to master, and the Redis documentation says a robust deployment needs at least three Sentinel instances. Valkey Sentinel follows the same pattern, with at least three Sentinel instances recommended. GitLab's reference architectures use Redis Sentinel for their high availability layouts. Redis Cluster and serverless offerings are not supported for GitLab, so confirm the current support statement in GitLab's documentation for your release before you finalize the design.
What does your internal team need to run Redis or Valkey?
Your team needs Linux administration skills, configuration management, network segmentation and TLS for client and replication traffic, and monitoring for memory use, replication lag and failover events. Engineers also need to test Sentinel failover, restore from backups, and apply patches on a schedule they can keep. On the GitLab side, the team must know how the Redis connection settings are declared in the GitLab configuration file, and how a change to Redis affects GitLab services. Someone must own on-call response, because a stalled Redis tier can slow sign-in, background jobs and page loads across the instance.
Can our own team build Redis or Valkey for GitLab in-house?
Yes, if your team already has the Linux, networking and operations skills described above and time for a test cycle. Valkey is licensed under BSD-3-Clause, and Redis OSS 7.2.x and earlier remain under BSD-3-Clause as well. Licensing changes after that point: Redis 7.4.x to 7.8.x are under RSALv2 or SSPLv1, which are not OSI-approved, and Redis 8.0 and later can be used under a license you choose among RSALv2, SSPLv1 and AGPLv3. Have counsel review the license for the exact version you deploy. The hardest in-house work is usually rehearsing failover and migration, not the initial install.
How is the cost of a Redis or Valkey build for GitLab driven?
Cost has three parts: infrastructure, licensing and services. Infrastructure includes the virtual machines or managed compute in your cloud or data center, including at least three Sentinel instances, plus storage, networking and monitoring. Licensing depends on the product you choose: the BSD-3-Clause terms of Valkey and Redis 7.2 differ from the source-available terms of Redis 7.4 and later, while Redis Software and Redis Cloud are commercial products. Services are the scoped design, build, migration, failover testing, documentation and handover. Infrastructure and patching recur, while design and migration are usually one-time. A written quote should itemize each component, separate one-time from recurring costs, and state what is out of scope.
How long does a Redis or Valkey build take for GitLab?
Duration depends on scope, and no fixed timeline applies to every environment. The main drivers are the number of environments (development, staging and production), the high-availability layout with its Sentinel nodes, the migration method and data size, the change windows your organization allows, and how much failover and restore testing is required. A greenfield install with no migration usually moves faster than a migration from a Redis 7.4 or later data set that needs a different method. Ask for a written schedule with milestones for design, build, test, cutover and handover, along with the assumptions behind each milestone.
How DeployOpen works on this
DeployOpen treats the Redis or Valkey decision as part of the wider GitLab architecture, not a standalone install. We confirm the licence position, the GitLab release you will run, and the Sentinel topology before any build starts, then document the result so your team can operate it after handover.
How we scope
- Confirm the GitLab version and reference architecture, then choose Redis 7.2 or Valkey 7.2 against your licence and support requirements.
- Record the Sentinel layout, the number of Sentinel instances, and the network path between Rails, Sidekiq and the Redis nodes.
- Agree in writing whether migration from an existing Redis deployment is in scope, including the data migration method and rollback plan.
How we build
- Deploy the Redis or Valkey servers, replicas and Sentinel instances inside your infrastructure, following the chosen topology and host baseline.
- Set the eviction policy and memory limits against how GitLab uses Redis, and verify the values in the GitLab configuration on each node.
- Test failover by stopping the primary in a non-production environment and confirming that GitLab reconnects without manual changes to application settings.
How we hand over
- Deliver a runbook covering topology, configuration files, failover steps, version alignment and the upgrade stops that apply to your GitLab release.
- Document backup and restore steps for Redis data alongside the GitLab backup procedure, so recovery is tested as one plan.
- Walk your operations team through monitoring, alerting and routine checks, and record the decisions made during the build for audit and review.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer, covering Redis or Valkey version changes alongside GitLab releases.
- Re-test failover and eviction settings after GitLab upgrades, scaling changes or changes to the Sentinel layout.
- Confirm with your team which vendor release lines and security releases apply to your environment before scheduling any change.
