Sizing Sidekiq for self-managed GitLab

Sizing Sidekiq for self-managed GitLab starts with job volume

Sidekiq sizing starts with job volume and queue behavior, so plan it from the background work your instance generates before counting users. Sidekiq is the background job processor in GitLab. It runs work that should not hold up a web request, such as sending notifications, processing webhooks, updating caches and handling many housekeeping tasks. When Sidekiq falls behind, users see delays in emails, pipeline updates, mirror syncs and other effects that appear after an action, even while the web interface responds normally. The Linux package bundles Sidekiq with PostgreSQL and Redis on one server, which suits small installations. As load grows, a separate Sidekiq tier keeps background work from competing with Rails for CPU and memory.

Teams usually need dedicated Sidekiq nodes when queue wait times grow under normal load, when Rails web workers and Sidekiq compete for memory on the same host, or when CI activity and integrations push job volume up faster than headcount suggests. Pipelines, webhooks and repository mirroring can generate large bursts of jobs, so two instances with the same number of users can have very different Sidekiq needs. Before you add capacity, confirm what the queues look like in your environment. Identify which queues back up, how long jobs wait and whether the backlog clears between peaks. Collect this baseline from the monitoring data and logs of your running instance before you change node counts.

This page is a planning guide tied to GitLab's published reference architectures, which run from 1,000 users at 20 API requests per second up to 50,000 users at 1,000 requests per second. Those layouts give you a starting topology, including where Sidekiq sits at each size, and the sections that follow explain how to adjust it. Use the reference architecture as a baseline to validate. Your CI volume, integrations and object storage latency all shift the numbers. Ask any partner proposing a node count to show the queue measurements behind it, and confirm your current GitLab version and its upgrade requirements before you change the topology.

Choosing a Sidekiq layout by environment and scale

The Linux package is the simplest layout. Rails, Gitaly, PostgreSQL, Redis and Sidekiq run on one server, and the package manages them together. GitLab describes the Linux package as the most mature and scalable installation method, and it bundles Sidekiq, so there is no separate Sidekiq node decision at this stage. This layout fits small teams whose user count and API load stay within the single-node guidance. Sidekiq shares CPU, memory and disk with every other component, so a growing job backlog and web traffic compete for the same resources.

What it separates: only the service boundaries the package already manages, not separate hosts.
What it leaves shared: CPU, memory, disk, and the PostgreSQL and Redis instances that Sidekiq also depends on.
Where it stops fitting: when job queues slow web requests or the reverse, the layout needs dedicated nodes.
Upgrade effect: the whole instance is one upgrade and one restart window, which keeps the procedure simple.

Before you commit, confirm your expected user count and API request rate against the single-node guidance and the GitLab reference architectures table.

Per-process memory guidance above 10,000 users

Above 10,000 users, the number of Sidekiq processes on each node and the memory each process can take matter more than the total node count. Each Sidekiq process holds its own copy of the Rails application, so memory use grows with process count, and a node that runs too many processes can swap or be killed by the operating system under load. Start by taking the per-process memory values and the node sizing for the user band you are in from the current GitLab reference architectures page. The reference architectures cover 1,000 to 50,000 users, so a 10,000-user organization sits in the middle of that range and should not assume figures from the smaller or larger designs carry over unchanged.

Treat the published values as a starting baseline, then check them in your own environment. Confirm the processes-per-node setting you intend to use in the Sidekiq configuration, and compare the resident memory of each process under peak job load, not idle load, with the memory available on the node after the operating system and any co-located services take their share. Keep headroom for bursts from large imports, mass notifications and CI-heavy periods, and watch for memory growth over days, since a process that slowly climbs can look healthy at restart and fail later. Your monitoring should record per-process memory, queue depth and job latency together so a memory change can be tied to a workload change.

Confirm three things with your GitLab support channel or in the current documentation before you commit to a layout: the per-process memory value for your chosen reference architecture, whether it changed in the release you plan to install, and whether your upgrade path to that release affects Sidekiq sizing. Record the answers alongside your load test results, because the same numbers will be needed when you add nodes or move to a new version.

How to plan and validate Sidekiq sizing step by step

This sequence takes an organization from its user count and API load to a Sidekiq layout it can defend. Each step produces a written decision or measured result, so the final configuration is tested before go-live rather than assumed from the install size.

Confirm the reference architecture band
The platform architecture team measures current and expected users, peak API requests per second from web and API logs, and CI concurrency. GitLab's reference architectures run from 1,000 users at 20 requests per second to 50,000 users at 1,000 requests per second, and the documentation recommends a high availability strategy at 3,000 or more users. Record one band with its user count, request rate, and HA requirement. Done when a named owner has signed off that band and the rest of the sizing refers to it.
Decide whether Sidekiq runs on separate nodes
Confirm in the documented layout for your band whether Sidekiq is a standalone component or shares a node with Rails. Separate nodes keep background job memory from competing with web worker memory, which makes per-node limits easier to reason about. Document the node roles in one diagram, showing which hosts run Sidekiq and which run the web tier. Done when each Sidekiq host has a single, written role and the diagram matches the band's reference layout.
Set process count and memory from the documentation
Take Sidekiq process counts and per-process memory from the reference architecture guidance for your band and your GitLab version, not from memory or older posts. The guidance changes for larger installations, including those above 10,000 users, so confirm the current values in the documentation before you commit. Calculate node memory as processes multiplied by per-process memory, plus room for the operating system and other services. Done when a sizing sheet lists node count, process count, and memory per node with its source page noted.
Configure Sidekiq for your install method
Apply the sizing in the configuration for your chosen install method. For Linux package installs, set node roles and Sidekiq settings in gitlab.rb, then run a reconfigure. For the Helm chart or Operator, set the equivalent values in version-controlled files, and for Cloud Native Hybrid, confirm that Sidekiq runs in Kubernetes while PostgreSQL, Redis and Gitaly stay outside the cluster. Done when gitlab-ctl reconfigure completes without errors and gitlab-ctl status shows the expected Sidekiq processes on each node.
Measure queue latency and memory before load
The platform team uses the Prometheus metrics that GitLab exposes, with the bundled or your own Grafana dashboards, to watch job queue size and latency, memory per Sidekiq process, and any process restarts. Capture a baseline on an idle or lightly loaded environment, then again during normal business hours once data is migrated. Agree alert thresholds with the application owners before go-live, and record them. Done when each Sidekiq node has a saved baseline and the thresholds are written in the runbook.
Validate with the GitLab Performance Tool before go-live
Run the k6-based GitLab Performance Tool against the environment at the request rate of your chosen band, with CI load that reflects real pipeline concurrency. Compare the results with the band's targets and with the thresholds from the previous step. Repeat the run after any change to node count, process settings, or GitLab version. Done when a test report with the configuration version, the load profile, and the observed queue latency and memory per node is filed, and the team has accepted the result.

What goes wrong when Sidekiq is undersized or shared

Sidekiq failures rarely look like Sidekiq failures. They show up as slow merge requests, stalled pipelines, restarted processes and database warnings, so the symptoms reach users before the queue does. The cards below cover the failure modes that most often follow from undersizing Sidekiq or running it on shared hardware.

Queue backlog builds silently

When jobs arrive faster than Sidekiq processes can run them, the backlog grows and work such as notifications, repository housekeeping and pipeline follow-up runs late. Users often notice first because merge requests and pipeline statuses lag behind their actions. Check queue depth and job latency over a normal week and over your peak CI period, and confirm which dashboards your monitoring stack exposes for Sidekiq before go-live.

Memory exhaustion and OOM kills

Each Sidekiq process holds its own memory, so the total footprint grows with process count and with the size of the jobs it handles. When a host runs out of memory, the kernel may terminate a Sidekiq process mid-job, and jobs may then retry, duplicate or fail depending on their design. Confirm per-process memory on your largest job types, and check kernel logs for OOM events after load tests.

Sidekiq competing with Rails for CPU

Running Sidekiq on the same hosts as Puma or Workhorse means background jobs and web requests draw from one pool of CPU and memory. A burst of jobs then slows page loads and API responses, and a spike in web traffic delays background work in turn. Confirm that Sidekiq nodes are separate in your topology, and measure CPU contention on any host that still runs both.

Redis or PostgreSQL saturation from bursts

Sidekiq depends on Redis to hold its queues and on PostgreSQL for much of the work each job performs. A large burst of enqueued jobs can push connection counts and query load on both at once, which affects every other part of the instance. Ask how connection pools are sized per Sidekiq process and confirm how your Redis and database tiers behave under a controlled burst during load testing.

Upgrades changing job behavior

A GitLab upgrade can change the workers, arguments or queue routing that Sidekiq uses, and jobs queued under the old version may still be waiting when the new version starts. Plan for mixed versions during rolling upgrades and check the release notes for changes to background jobs before scheduling. Confirm your queue drain procedure and whether any custom integrations depend on specific job names.

Configuration options and when each fits

This table compares three ways to place Sidekiq: co-located with Rails on one node, on dedicated Sidekiq nodes, and in Kubernetes under the Cloud Native Hybrid architecture. Read each row against your user count, request rate and background job volume, then confirm the exact settings in the current GitLab documentation before you size hardware.

Option	Fits when	Trade-off	What to confirm
Single-node co-located Sidekiq	A small instance where the Linux package runs Rails, Sidekiq, PostgreSQL and Redis on one server, typically within the single-node range of the reference architectures.	Sidekiq competes with web requests and the database for CPU and memory, so a spike in background jobs can slow the UI and API.	Memory and CPU headroom for the Sidekiq worker in the Linux package on the node; the sidekiq and puma settings in gitlab.rb as documented for your version.
Dedicated Sidekiq nodes	Job volume grows, or the instance serves enough users that Rails and Sidekiq need separate memory budgets and independent scaling.	More servers to build, patch, monitor and back up, plus a need to point each node at the same database, Redis and object storage.	Which roles each node runs using the Linux package role settings in gitlab.rb; the concurrency and per-process memory limits in the current docs; that all nodes reach the same Redis and PostgreSQL endpoints.
Sidekiq in Kubernetes under Cloud Native Hybrid	You already operate Kubernetes and want Sidekiq scaled as workloads, with PostgreSQL, Redis, Gitaly and object storage kept outside the cluster.	Stateful services must run on VMs or managed services, and the cluster adds an operational layer for resource requests, limits and autoscaling.	The Helm chart values for the Sidekiq deployment and its replica and resource settings in the version you deploy; that stateful components sit outside the cluster as the reference architecture requires.
Separate queue groups on dedicated nodes	Some job types, such as CI-heavy or mail-related queues, must not wait behind others during peaks.	Queue routing adds configuration to review and test, and an idle node group still costs capacity.	The queue selector settings for each Sidekiq node group in gitlab.rb or the Helm values; how your version reports queue latency so you can confirm routing works.
Per-process memory limits	Memory use per Sidekiq process grows with job volume and you need to keep workers from exhausting the host.	Limits that are too tight cause restarts and retried jobs; limits that are too loose let one node run out of memory.	The memory-related Sidekiq settings and their defaults in the current documentation; the per-process guidance for your user count, which changes above 10,000 users.
Monitoring Sidekiq queues	Any placement option, because job backlog is the first signal that Sidekiq is undersized.	Metrics must be exported and watched, or backlog builds unnoticed until users report slow pipelines or notifications.	The Sidekiq metrics endpoint and Prometheus scrape settings for your version; alert thresholds you set for queue size and job latency.

Security and operational considerations for Sidekiq nodes

Sidekiq nodes hold credentials to your database, Redis and object storage, and they process every background job your instance runs. The four areas below decide whether a larger Sidekiq fleet stays contained, current and observable as job volume grows. Check each one against your own network and change calendar before you size the fleet.

Network placement relative to Redis and PostgreSQL

Sidekiq nodes must reach Redis and PostgreSQL directly, so their placement defines how far a compromised or misconfigured worker can reach. Keep Redis and PostgreSQL on a private segment that only Rails, Sidekiq and Gitaly nodes can address, and block direct access from user-facing networks. Confirm the port rules with your network team, then test that a Sidekiq node can reach only the services it needs. Each added Sidekiq node is another client that must be allowed through those rules.

Least-privilege access to secrets in gitlab.rb

The gitlab.rb file holds database passwords, Redis credentials, the secrets keys and object storage access keys. Every Sidekiq node reads this file, so each copy of it is a copy of your secrets. Restrict file ownership to root, limit read access on the file and backups, and make sure Sidekiq nodes receive only the values they use. Review which node roles need the encryption keys, and rotate credentials when a node is retired.

Patching in step with the release cadence

GitLab ships a minor release on the third Thursday of each month and patch releases twice a month, and it backports security fixes to the previous two monthly releases. Sidekiq nodes must run the same GitLab version as the rest of the instance, so every node in the fleet needs to move in the same window. Plan a repeatable patch schedule, and confirm which upgrade stop applies before you skip any version.

Queue health monitoring

Sidekiq problems usually show up as growing queues, not as errors in the user interface. Track queue depth and job latency per queue, and watch for jobs that repeatedly fail or retry. Alert when latency rises after a deploy or when a node stops processing jobs. Confirm which Prometheus metrics your installed version exposes, and set thresholds from your own baseline rather than from a generic number.

Logs for job and node investigation

Sidekiq logs record job starts, completions, failures and retries, which are the first evidence when a queue stalls or a job runs against the wrong data. Ship these logs from every Sidekiq node to your central log platform with the node name attached, so you can tell which worker handled a job. Set retention to match your incident and audit requirements, and confirm which log files contain job arguments that may include personal data.

Hardening checks before scale-out

Adding Sidekiq nodes multiplies the places where settings can drift. Before you add capacity, verify that every node uses the same configuration, that outbound access and sign-up settings match your policy, and that the operating system baseline is applied. Work through the hardening guidance gradually, record which controls you adopted, and retest after each GitLab upgrade. Ask your implementation partner to document the checks as a repeatable runbook.

Questions teams ask before sizing Sidekiq

What drives the cost of sizing Sidekiq for self-managed GitLab?

The cost follows the number of environments, the size of the instance, and how much of the work is measurement versus change. The largest drivers are how many users and CI jobs the instance serves, how many Rails, Sidekiq and stateful nodes are already running, and whether the team needs a written sizing model or just a set of node settings. Sizing work usually splits into analysis of current queue and memory data, a proposed node layout, and validation under load. Each part is priced from the written scope, so ask for each activity to be listed separately, along with who runs the load tests and whether any changes to production are included. Recurring costs appear only if you later want retainer-based review as job volume grows.

How long does a Sidekiq sizing and validation exercise take?

Duration depends on how much data already exists and how many environments must be validated. An instance with several months of metrics and a clear queue history needs less discovery than one where monitoring was never enabled. Validation adds time because load tests need a production-like environment, a change window for any tuning, and a second pass if the first results show queue latency or memory pressure. Ask for the timeline to be tied to deliverables: data review, proposed topology, configuration changes, test results and a rollback plan. DeployOpen agrees timelines in the written scope before work starts, so the exact duration comes from that scope rather than a generic estimate.

What does the work need from our team?

The work needs read access to GitLab's metrics and logs, including Sidekiq queue and job data, plus host-level memory and CPU figures for the nodes that run Rails and Sidekiq. You also need a non-production environment that resembles production in topology and data volume, and agreed change windows for applying configuration and restarting services. Someone who owns the GitLab administration account should be available to approve changes and explain any custom jobs, integrations or webhooks that generate load. Confirm in advance how long your monitoring history is retained, because short retention limits what can be concluded about peak job volume.

Can our internal team size Sidekiq without outside help?

Yes, many teams can do it with the right data and a clear method, especially if they already run GitLab in production and have monitoring in place. The harder parts are interpreting queue behavior under peak CI load, separating Sidekiq memory from Rails memory on shared hosts, and running a validation that proves the change did not create new bottlenecks. An internal team should be able to answer whether it has the metrics, the test environment and the time to repeat tests after each change. If any of those are missing, an outside review can cover the gap, but the decision remains with your team because the instance and its change process are yours.

When is it worth splitting Sidekiq onto its own nodes?

A split is worth considering when Sidekiq competes with Rails for CPU and memory, when queue latency rises during busy periods, or when job types with very different resource profiles need isolation. Separating the roles lets you tune process counts and memory limits for background work without affecting web and API response times. The trade-off is more hosts to patch, monitor and back up, plus more configuration to keep consistent across the fleet. Reference architectures published by GitLab describe node roles by user count and request rate, so use them as the baseline and check your own queue and memory data before adding nodes.

How do we know if our Sidekiq memory settings are wrong?

Warning signs include jobs that wait longer than expected in queues, processes restarting because of memory limits, and host memory pressure that appears only when CI or scheduled work peaks. Check the per-process memory trend over several business cycles rather than a single snapshot, and compare it against the concurrency you have configured. A safe way to verify a change is to apply it in a non-production copy, replay a representative load, and confirm that queue latency and memory stay within the limits you set for the review. Keep the previous configuration available so you can roll back during the change window.

What should we ask for in a written quote for this work?

Ask for a scope that lists the data sources you will provide, the environments that will be tested, the deliverables and the acceptance criteria. Confirm whether the quote includes configuration changes on your production instance or only recommendations your team applies. Ask how load tests are run and which results you will receive, and whether a rollback procedure is part of the handover. Also confirm what happens if the first validation does not meet the targets, and whether a second test cycle is priced separately. A clear list of exclusions, such as hardware purchases or changes to Gitaly and PostgreSQL, prevents surprises later.

How DeployOpen scopes and delivers Sidekiq sizing

DeployOpen plans, implements, tests, documents and supports self-hosted GitLab inside your own infrastructure. For Sidekiq sizing, we start from your user count, CI load and job mix, then agree a written scope before any build work begins.

How we scope

Review your user count, API request rate, CI concurrency and current Sidekiq queue behavior before proposing any node layout.
Confirm which GitLab edition, install method and reference architecture your team is already using or planning to adopt.
Agree in writing which Sidekiq nodes, memory settings and separation from Rails nodes are in scope, with engagements being fixed-scope.

How we build

Configure Sidekiq processes and per-process memory on dedicated nodes, separated from Rails, in your own cloud accounts, data centers or air-gapped network.
Test queue depth, job latency and memory use under representative load before changing production settings.
Record each setting change, its reason and the rollback steps so the sizing can be reviewed when job volume changes.

How we hand over

Deliver a written sizing document covering node roles, process counts, memory limits and the signals that should trigger a resize.
Walk your platform and operations engineers through the configuration, monitoring points and upgrade considerations for Sidekiq.
Confirm with your team that the handover materials match the running environment before the engagement closes.

How we support

Offer ongoing support, upgrades and testing as a retainer if you want DeployOpen to revisit Sidekiq sizing as load grows.
Review Sidekiq settings again when you plan a GitLab upgrade, since required upgrade stops can change the platform you run.
Ask for a quote built from the written scope, since DeployOpen does not publish a price list.

Sizing Sidekiq for self-managed GitLab