The safe way to update a self-hosted GitLab server is to treat the change as a database-and-application migration, not a package install. Identify the exact source and target versions, follow every required upgrade stop, let background migrations finish, create and rehearse a version-matched restore, pause writers and CI/CD activity, then verify the application before reopening traffic. A single-node installation requires downtime; a carefully designed multi-node deployment may use a sequential, load-balanced procedure, but only when its architecture and release span support it.
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
What a safe GitLab update must protect
GitLab upgrades can change database schemas, application code, background jobs, secrets handling and integrations at the same time. A successful package or container update is not enough: repositories, web requests, Sidekiq, runners, the container registry, Geo, search and external services must remain coherent.
As an Amazon Associate I earn from qualifying purchases.
Recommended Free Tools
| Decision axis | Why it changes the runbook |
|---|---|
| Topology | Single-node installations cannot keep serving traffic during the upgrade. Multi-node installations can sometimes drain and replace nodes sequentially. |
| Availability target | A downtime procedure is simpler and gives migrations an undisturbed environment. Zero downtime adds load-balancer, compatibility and rollback constraints. |
| Installation method | Linux packages, Docker, Helm, the Operator and source installations expose different upgrade controls, backup locations and migration steps. |
| Upgrade span | A patch update may be direct; minor and major jumps can require specific intermediate versions and completed background migrations. |
| Migration behavior | Foreground migrations block startup or requests, while background migrations can continue after the service is available and must be monitored before the next stop. |
| Rollback capability | Schema changes require a database restore from the exact version and edition being restored, plus matching secrets and configuration. |
Inventory the installation before choosing a date
Write down the current state before touching any package, image or chart. The record becomes both the change plan and the evidence you need if recovery is required.
Record versions and components
- Exact GitLab version and edition, including the patch level.
- Installation method: Linux package, Docker, Helm chart, Operator or source.
- Number of application, database and supporting nodes, and which nodes are behind the load balancer.
- Whether PostgreSQL, Redis, Gitaly or PgBouncer are external, managed or colocated.
- Geo sites, runners, Kubernetes agents, container registry usage and search integrations.
- Operating-system version and architecture, available disk space, database capacity and maintenance access.
- Any custom configuration, reverse proxy, object storage, TLS termination, firewall rule or secret-management integration.
Read the release and maintenance requirements
Check GitLab’s release policy, maintenance policy, version-specific upgrade notes, operating-system compatibility guidance, Geo requirements, required upgrade stops and health-check instructions for the exact target. Do not schedule from a generic “latest” button: the valid path depends on the source version, target version, edition and topology.
#1 Best Overall
Clone production for a rehearsal
Build a production-like test environment with the same installation method, database major version, external services, runners and integrations. Exercise the proposed path there, including a restore and the checks you will use in production. A rehearsal reveals disk, permissions, migration-duration and compatibility problems while the original service is still available.
Calculate the supported upgrade path
Use GitLab’s upgrade-path tool and the release notes for both endpoints. Some major.minor releases are mandatory stops because they contain fixes or migration logic needed by later releases. Skipping a stop can leave schema changes or background jobs in an unsupported state.
How to move through stops
- Confirm the exact source version and edition.
- Generate the path to the target version, noting every required major.minor stop.
- Choose the latest patch release in each required major.minor line rather than the first patch release, unless the version-specific notes say otherwise.
- At the first stop, complete the upgrade and keep the instance under observation.
- Check background migration status and wait until all migrations required at that stop are complete.
- Only then proceed to the next stop, repeating the same process through the target.
Background migrations may continue after the application starts. “The service is up” is not the same as “the stop is complete”; continuing early can make the next release encounter unfinished work.
Build a rollback plan that can actually restore service
A rollback plan is a tested sequence, not a statement that a package can be downgraded. GitLab’s rollback guidance requires a database backup made under the exact same version and edition you intend to restore. Migrations may have changed the schema, so an older application binary alone cannot reverse them.
What to preserve
| Item | Purpose | Handling |
|---|---|---|
| GitLab database backup | Restores data to the pre-upgrade schema. | Create it with the installation’s documented backup procedure and label it with source version, edition and timestamp. |
| Secrets file and encryption keys | Allows encrypted credentials, tokens and protected data to be read after restoration. | Store securely outside the host being upgraded and verify that the recovery operator can retrieve it. |
| GitLab and service configuration | Recreates URLs, storage, database, Redis, Gitaly, SMTP, registry and proxy settings. | Capture configuration files and relevant environment or chart values, with permissions preserved. |
| Node or instance snapshots | Speeds recovery of multi-node installations and supporting services. | Snapshot every required node or service consistently; a snapshot of only the Rails node is not a complete rollback. |
| Upgrade artifacts | Permits installation of the exact prior release. | Keep the prior package, container image, chart or source checkout available in the maintenance environment. |
Rehearse the restore
- Provision a production-like recovery environment.
- Install the exact prior GitLab version and edition.
- Restore the database backup, secrets and configuration.
- Start dependent services and GitLab using the documented order for your deployment.
- Run the health checks, sign in with an administrative account, open a repository, clone and push a test change, inspect Sidekiq and validate integrations that matter to your users.
- Record elapsed time, commands, permissions and any manual repair. The result is your recovery runbook and a realistic outage estimate.
Docker-specific database backup
For a Docker installation, GitLab documents a database-only backup before an upgrade when repository and other large data are preserved separately. Run:
docker exec -t <container name> gitlab-backup create SKIP=artifacts,repositories,registry,uploads,builds,pages,lfs,packages,terraform_statePreserve the secrets file as well. The skipped data still needs its own protection and a documented restore path; this command is not a complete backup of an installation that has no separate copies of those objects.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsChoose downtime or a zero-downtime sequence
| Situation | Supported choice | Operational implication |
|---|---|---|
| Single-node GitLab | Downtime | Stop application writers and take the instance offline while services and migrations are upgraded. |
| Multi-node GitLab, compatible release span and HA controls | Downtime or sequential zero downtime | Downtime is simpler. Zero downtime requires draining, load balancing, compatible nodes and close monitoring. |
| Upgrade across multiple minor releases | Downtime | GitLab requires taking the instance offline for this span; do not assume rolling replacement is safe. |
| Distributed architecture with uncertain compatibility | Downtime | Use the conservative procedure until the exact architecture and release notes establish a supported rolling path. |
GitLab cautions that distributed zero-downtime behavior depends on the exact architecture. Monthly releases can introduce background migrations, so a load balancer alone does not make every upgrade safe to roll node by node.
Prepare the maintenance window
Freeze activity that writes to GitLab
- Pause CI/CD pipelines and scheduled jobs.
- Prevent new deployments and automation from creating issues, merge requests, packages or registry writes.
- Stop or drain application writers before database migrations in a downtime procedure.
- Tell users when the service becomes read-only or unavailable and define the communication channel for progress and rollback.
- Confirm that the backup, restore rehearsal, prior release artifacts and administrator credentials are reachable from the maintenance environment.
Runner trace updates can fail while the instance is being upgraded. Pausing jobs prevents noisy failures and reduces writes competing with migrations.
Capture a baseline
Before stopping traffic, record the current results of sudo gitlab-rake gitlab:check and sudo gitlab-rake gitlab:doctor:secrets. Note database background migration status, Sidekiq queue depth, runner connectivity, repository access, registry behavior, Geo health and search status. A baseline distinguishes pre-existing faults from upgrade regressions.
Execute the upgrade for each deployment method
Linux package installations
Follow the generated path and the package release notes, installing one required stop at a time. On a single node, stop or drain the application, apply the package, allow migrations to run, monitor background migrations and keep the service closed until verification is complete.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →For a multi-node downtime procedure, GitLab’s documented sequence is to shut down the application, upgrade Consul, Gitaly, Rails, PostgreSQL, Redis and PgBouncer, then start and verify the application. Adapt the sequence to the services that actually exist in your topology; an external managed service may have its own maintenance process.
Docker installations
Pin the target image rather than relying on an unchanging “latest” tag. Stop or drain writers according to the chosen downtime or rolling procedure, preserve the secrets file, run the documented backup, then start the target image and monitor migrations. Keep the prior image available until post-upgrade checks pass. Do not delete volumes, networks or configuration while troubleshooting; they may be needed for recovery.
Helm deployments
Use the chart’s version-specific upgrade procedure, migration jobs, maintenance mode and post-migration checks. Review the chart values and image tag together: changing one without understanding the other can produce a mismatched application. During a major database upgrade, GitLab says migrations may need to be disabled temporarily and explicitly re-enabled afterward. If that exception applies, document the exact setting, the reason, the step that re-enables migrations and the check proving they resumed.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Operator-managed deployments
The default zero-downtime path updates one minor version at a time. A downtime path requires a maintenance window and a backup. Let the Operator reconcile each stage and verify status before applying the next version; do not stack several minor upgrades in one change simply because the custom resource accepts the value.
Source installations
Use the source installation’s documented dependency, database migration and asset-build procedure for each required stop. Pin the source revision and dependency set used in the rehearsal, stop writers before schema migrations and retain the prior checkout for rollback. Source deployments have fewer packaging guardrails, so the written plan must explicitly identify every process manager, worker, asset and configuration change.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Verify the upgraded service before reopening traffic
Keep maintenance mode or drained traffic in place while checks run. Start with GitLab’s recommended commands:
sudo gitlab-rake gitlab:check
sudo gitlab-rake gitlab:doctor:secretsAlso check the database’s background migration status and confirm that all migrations required for the current stop are complete. Do not proceed to another stop or declare success while migration work remains.
Application and data checks
- Sign in through the web UI and confirm administrator and ordinary-user access.
- Open existing projects, browse files and issues, create a temporary branch, clone a repository and push a test commit if policy permits.
- Make a test web request and API request; verify authentication, redirects, TLS and rate-limit behavior.
- Inspect Sidekiq queues for growing or permanently failing jobs.
- Confirm runners can register, receive a small test job and upload its trace.
- Read and write a test artifact, package or registry object if those features are enabled.
- Check external PostgreSQL, Redis, Gitaly and PgBouncer connectivity, including connection-pool saturation and error logs.
- Validate Geo replication, Kubernetes agents and search integrations used by the installation.
- Review application, worker, database, proxy and orchestration logs for migration errors, secret failures, permission problems and repeated retries.
Reopen traffic in stages
- Keep one administrative path available while fixing any check failure.
- Restore load-balancer membership or remove maintenance mode only after the checks pass.
- Resume a small class of CI jobs and observe traces, queues and resource use.
- Resume normal schedules and user traffic, watching error rates and background migration status.
Roll back a failed upgrade
Roll back when verification finds an unrecoverable data, authentication, migration or integration problem and the forward fix is not safer within the maintenance window. Preserve logs and the failed environment state before changing it.
- Keep the upgraded service out of rotation and stop its application, workers and writers.
- Install the exact prior GitLab version and edition from the retained package, image, chart or source revision.
- Restore the version-matched database backup prepared for this change.
- Restore the secrets file, encryption keys and configuration files, then verify ownership and permissions.
- Start dependent services and GitLab in the deployment’s documented order.
- Run the health checks, test repository and web access, inspect Sidekiq and validate the integrations that were part of the baseline.
- Reopen traffic only after the restored instance matches the baseline closely enough for users and automation.
- Record the failure, the restore duration and the evidence needed to correct the upgrade path before another attempt.
Never treat a binary downgrade without a database restore as a rollback for a migration that changed the schema. The backup is what reverses those schema changes.
Common failure modes and the safest response
| Symptom | Likely class of problem | Response |
|---|---|---|
| The next required stop refuses to start | A background migration from the previous stop is still running. | Keep traffic controlled, inspect migration status and wait for completion before continuing. |
| Runners show failed or missing traces | Jobs continued while the instance was being upgraded. | Keep CI paused, inspect runner and Sidekiq errors, then run a small test job after verification. |
| Encrypted values or tokens cannot be read | Secrets or encryption keys were not restored with the database. | Stop writes, restore the matching secrets and configuration, and rerun the secrets check. |
| Repositories open but pushes or clones fail | Gitaly connectivity, permissions, proxy rules or storage mounts differ from the baseline. | Compare service endpoints, credentials, mounts and logs before accepting user traffic. |
| Web UI works but jobs or packages fail | Sidekiq, runners, object storage, registry or external services are unhealthy. | Test each integration separately; do not infer overall health from a successful login. |
| A rolling upgrade produces inconsistent behavior | The architecture or release span does not support the assumed zero-downtime sequence. | Drain traffic, use the documented downtime path or restore the last working state, then redesign the sequence from the exact release notes. |
| Helm migration work is absent | Migrations were disabled for a major database change and not re-enabled. | Apply the documented re-enable step, confirm migration jobs run and wait for completion before normal traffic. |
When an update is ready to be called complete
The change is complete only when the target version is installed, every required stop has been finished, background migrations are complete, health checks pass, secrets validate, repositories and critical integrations work, CI/CD has successfully run a test job and the rollback artifacts remain available. Close the maintenance record with the final version, timestamps, operator, commands, migration status, observed issues and the next backup or upgrade review date.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Free tools Windows power users keep installed
One-click scans. No signup required.
