Gitlab – Backup / Update Steps

Sept 19 2026 Update


# Your upgrade path
# You are:
# 19.0.0 → 19.2.5 → 19.4.
# GitLab 19's required stops are 19.2, 19.5, 19.8, 19.11. Therefore 19.2.x is mandatory, but 19.1.x is not. 

rpm -E %rhel

sudo cat /opt/gitlab/embedded/service/gitlab-rails/VERSION

sudo dnf install -y dnf-plugins-core

sudo dnf clean all

sudo dnf --showduplicates list gitlab-ee | \
egrep '19\.2\.6-ee\.0\.el9|19\.3\.2-ee\.0\.el9|19\.4\.0-ee\.0\.el9'

sudo dnf update -y --exclude=gitlab-ee


mkdir -p ~/gitlab-upgrade-19
cd ~/gitlab-upgrade-19

sudo dnf download gitlab-ee-19.2.6-ee.0.el9
sudo dnf download gitlab-ee-19.3.2-ee.0.el9
sudo dnf download gitlab-ee-19.4.0-ee.0.el9

ls -lh *.rpm


bash ~/backups/run_gitlab_backup_all.sh

bash ~/backups/run_gitlab_healthcheck.sh


# ============================================================
# 19.2.6 — REQUIRED STOP
# ============================================================

cd ~/gitlab-upgrade-19

sudo dnf install -y ./gitlab-ee-19.2.6-ee.0.el9.x86_64.rpm

# Post install checks

sudo gitlab-ctl reconfigure

sudo gitlab-ctl status

sudo gitlab-rake gitlab:check SANITIZE=true

sudo cat /opt/gitlab/embedded/service/gitlab-rails/VERSION

sudo gitlab-rake gitlab:background_migrations:list

sudo gitlab-psql -c "SELECT job_class_name, table_name, column_name, job_arguments FROM batched_background_migrations WHERE status NOT IN(3, 6);"
# this must  return 0
sudo gitlab-rake db:migrate:status | tail -n 20

sudo gitlab-rake gitlab:doctor:secrets

# ============================================================
# DO NOT CONTINUE UNTIL THE QUERY ABOVE RETURNS ZERO ROWS
# ============================================================


# ============================================================
# 19.3.2 — EXTRA CONSERVATIVE HOP
# ===========================================================

# Pre Install 
bash ~/backups/run_gitlab_backup_all.sh

bash ~/backups/run_gitlab_healthcheck.sh

# Install

sudo dnf install -y ./gitlab-ee-19.3.2-ee.0.el9.x86_64.rpm

# Post install checks

sudo gitlab-ctl reconfigure

sudo gitlab-ctl status

sudo gitlab-rake gitlab:check SANITIZE=true

sudo cat /opt/gitlab/embedded/service/gitlab-rails/VERSION

sudo gitlab-rake gitlab:background_migrations:list

sudo gitlab-psql -c "SELECT job_class_name, table_name, column_name, job_arguments FROM batched_background_migrations WHERE status NOT IN(3, 6);"

sudo gitlab-rake db:migrate:status | tail -n 20

sudo gitlab-rake gitlab:doctor:secrets
# ============================================================
# DO NOT CONTINUE UNTIL THE QUERY ABOVE RETURNS ZERO ROWS
# ============================================================


# ============================================================
# 19.4.0 — MCP TARGET
# ============================================================
# Pre Install 
bash ~/backups/run_gitlab_backup_all.sh

bash ~/backups/run_gitlab_healthcheck.sh

# 3x check - 
sudo gitlab-psql -c "SELECT job_class_name, table_name, column_name, job_arguments FROM batched_background_migrations WHERE status NOT IN(3, 6);"

# Install
sudo dnf install -y ./gitlab-ee-19.4.0-ee.0.el9.x86_64.rpm

# Post Install
sudo gitlab-ctl reconfigure

sudo gitlab-ctl status

sudo gitlab-rake gitlab:check SANITIZE=true

sudo cat /opt/gitlab/embedded/service/gitlab-rails/VERSION

sudo gitlab-rake gitlab:background_migrations:list

sudo gitlab-psql -c "SELECT job_class_name, table_name, column_name, job_arguments FROM batched_background_migrations WHERE status NOT IN(3, 6);"

# want 0 rows

sudo gitlab-rake db:migrate:status | tail -n 20

bash ~/backups/run_gitlab_healthcheck.sh

sudo gitlab-rake gitlab:doctor:secrets


# That is much nicer because once we've done the backup and started the maintenance, we are no longer depending on GitLab's package server, DNS, repo metadata, or Internet connectivity between hops.
# I'd actually add downloading the RPMs to your PRE UPDATE CHECKS, before backups. Then the sequence becomes:
verify machine → download all required RPMs → backup → upgrade one RPM at a time → verify each stop.

# After each hop, confirm GitLab is serving and migrations are done:

sudo gitlab-rake gitlab:background_migrations:status
sudo gitlab-rake db:migrate:status | tail -n 20

Issues with ngixn



1. Disable the manual Nginx service
You don't want two different Nginx managers fighting. Since you're done with the PHP stuff, kill the standalone one:
bash
sudo systemctl stop nginx
sudo systemctl disable nginx
Use code with caution.

2. Hand the keys back to GitLab
Open your GitLab config:
bash
sudo nano /etc/gitlab/gitlab.rb
Use code with caution.

Find and fix these specific lines (make sure they aren't commented out with #):
nginx['enable'] = true
external_url 'https://spiffydesign.com' (Make sure this has https)
Link your Let's Encrypt certs so GitLab can handle the SSL:
ruby
nginx['ssl_certificate'] = "/etc/letsencrypt/live/://spiffydesign.com"
nginx['ssl_certificate_key'] = "/etc/letsencrypt/live/://spiffydesign.com"
Use code with caution.

3. Reconfigure to apply the "GitLab Way"
This will regenerate the correct internal Nginx config and ignore that messy nginx.conf you were editing:
bash
sudo gitlab-ctl reconfigure
Use code with caution.

4. Verify
Check the status again. You should finally see nginx in the list:
bash
sudo gitlab-ctl status
Use code with caution.

Why this happened: When you updated to 18.8.4, the update expected the web server to be ready, but because nginx['enable'] = false was set in your gitlab.rb, GitLab updated the code but never "turned on the lights" for the web interface.

To update your GitLab instance to version 17.6, follow these steps:

Review the Release Notes: Familiarize yourself with the new features, bug fixes, and any deprecations in version 17.6.

GitLab
check rhel
```
[spiffy-root@spiffydesign ~]$ rpm -E %rhel
9
```
Cool — RHEL/Alma 9 means you want the .el9 builds.

Install targets (in order)
1. gitlab-ee-18.5.5-ee.0.el9
2. gitlab-ee-18.8.4-ee.0.el9
Backup Your Data: Before proceeding, ensure you have a complete backup of your GitLab instance to prevent data loss.

Making and Verifying Backups

Backing up your GitLab instance is crucial to safeguard your data against potential loss due to hardware failures, software issues, or other unforeseen events. The backup process involves saving your repositories, databases, configuration files, and other essential components. Here’s a comprehensive guide to backing up your GitLab instance:

1. Backup GitLab Data:

GitLab provides a built-in command-line tool to back up your entire instance, including:

Database: Contains user-generated content such as issues, merge requests, comments, permissions, and credentials.
Git Repositories: All project repositories, including wikis and design repositories.
Attachments: Files uploaded to issues, merge requests, and comments.
CI/CD Job Output Logs and Artifacts: Logs and artifacts generated by CI/CD pipelines.
LFS Objects: Large File Storage objects.
Container Registry Images: Docker images stored in the integrated container registry.
GitLab Pages Content: Static websites hosted with GitLab Pages.
Packages: Packages stored in GitLab’s package registries.
Snippets: Code snippets shared within GitLab.
Group Wikis: Wikis associated with groups.
Project-Level Secure Files: Secure files at the project level.
External Merge Request Diffs: Diffs stored externally.

To create a backup, execute the following command:


sudo gitlab-backup create

This command generates a backup archive in the default backup directory, typically /var/opt/gitlab/backups.

GitLab Docs

2. Backup Configuration Files:

The backup command does not include GitLab’s configuration files, which are essential for restoring your instance. Manually back up the following files:

/etc/gitlab/gitlab.rb: Contains your GitLab configuration settings.
/etc/gitlab/gitlab-secrets.json: Holds your database encryption key and other sensitive information.

To back up these files, copy them to a secure location:


sudo cp /etc/gitlab/gitlab.rb /etc/gitlab/gitlab-secrets.json /path/to/backup/location/
                                                              /home/spiffy-root/backups/gitlab/{date}

GitLab Docs

3. Backup Object Storage (If Applicable):

If your GitLab instance uses object storage for items like LFS objects, uploads, or artifacts, ensure that these are backed up separately. The built-in backup command does not include data stored in external object storage. Consult your object storage provider’s documentation for backup procedures.

GitLab Docs

4. Automate Regular Backups:

To maintain up-to-date backups, automate the backup process using cron jobs. For example, to schedule a daily backup at 2 AM, add the following line to the root user’s crontab:


0 2 * * * /opt/gitlab/bin/gitlab-backup create CRON=1

The CRON=1 environment variable suppresses progress output, making it suitable for cron jobs.

How-To Geek

5. Secure and Verify Backups:

Storage: Store backups in a secure, offsite location to protect against data loss due to hardware failures or disasters.
Verification: Regularly test your backups by performing restoration on a separate environment to ensure data integrity and the effectiveness of your backup process.

By following these steps, you can ensure that your GitLab instance is backed up comprehensively, allowing for effective restoration in case of data loss or system failure.

Show less

Check for Background Migrations: Ensure all background migrations have completed before upgrading.

GitLab Docs
Determine Your Upgrade Path: If you’re upgrading from an older version, you might need to follow a specific upgrade path.

GitLab Pages
Upgrade GitLab: Use the appropriate method based on your installation:
- Omnibus Package:
  - For Debian/Ubuntu:
```
sudo apt update && sudo apt install gitlab-ee
```
  - For RHEL/CentOS:
```
sudo yum install gitlab-ee
```
  - For SUSE:
```
sudo zypper install gitlab-ee
```
  dnf
  
  To upgrade your GitLab installation on RHEL 8 or 9 using dnf, follow these steps:
  1. Update the Package Repository:
    
    Ensure your package repository information is up to date:
```
sudo dnf update
```
  2. Install the Latest GitLab Package:
    
    Proceed to install the latest version of GitLab:
```
sudo dnf install gitlab-ee
```
    Note: If you’re using GitLab Community Edition, replace gitlab-ee with gitlab-ce.
  3. Reconfigure GitLab:
    
    After installation, reconfigure GitLab to apply the new settings:
```
sudo gitlab-ctl reconfigure
```
  Important Considerations:
  - Backup: Before upgrading, ensure you have a complete backup of your GitLab instance, including repositories, databases, and configuration files.
  - Upgrade Path: If you’re upgrading from an older version, consult the GitLab Upgrade Paths to determine if intermediate upgrades are necessary.
  - Post-Upgrade Checks: After upgrading, verify that all services are running correctly:
```
sudo gitlab-ctl status
sudo gitlab-rake gitlab:check
```
  By following these steps, you can successfully upgrade your GitLab instance on RHEL 8 or 9 using dnf.To upgrade your GitLab installation on RHEL 8 or 9 using dnf, follow these steps:
  1. Update the Package Repository:
    
    Ensure your package repository information is up to date:
```
sudo dnf update
```
  2. Install the Latest GitLab Package:
    
    Proceed to install the latest version of GitLab:
```
sudo dnf install gitlab-ee
```
    Note: If you’re using GitLab Community Edition, replace gitlab-ee with gitlab-ce.
  3. Reconfigure GitLab:
    
    After installation, reconfigure GitLab to apply the new settings:
```
sudo gitlab-ctl reconfigure
```
  Important Considerations:
  - Backup: Before upgrading, ensure you have a complete backup of your GitLab instance, including repositories, databases, and configuration files.
  - Upgrade Path: If you’re upgrading from an older version, consult the GitLab Upgrade Paths to determine if intermediate upgrades are necessary.
  - Post-Upgrade Checks: After upgrading, verify that all services are running correctly:
```
sudo gitlab-ctl status
sudo gitlab-rake gitlab:check
```
  By following these steps, you can successfully upgrade your GitLab instance on RHEL 8 or 9 using dnf.
  
  GitLab Docs
- Docker:
```
docker pull gitlab/gitlab-ee:17.6.0
```
  GitLab Docs
- Source Installation: Follow the source upgrade instructions.
  
  GitLab Docs
Post-Upgrade Checks: After upgrading, verify that all services are running correctly and that your data is intact.

Feb 11 2026 Update



PRE UPDATE CHECKS:

# check rhel
rpm -E %rhel

# confirm current GitLab version
sudo cat /opt/gitlab/embedded/service/gitlab-rails/VERSION
# or
sudo gitlab-rake gitlab:env:info | egrep 'GitLab information|Version'

# (optional but helpful) confirm the exact package strings exist in your configured repo
sudo dnf clean all
sudo dnf --showduplicates list gitlab-ee | egrep '18\.5\.5-ee\.0\.el9|18\.8\.4-ee\.0\.el9' || true

# Update Code base

sudo dnf update

#BACKUP STEPS:
# gitlab-backup create writes into /var/opt/gitlab/backups/ by default. So copy that tar to your safe location too.

sudo gitlab-backup create

# copy the actual backup tar(s) somewhere safe
sudo ls -lah /var/opt/gitlab/backups/
sudo cp -a /var/opt/gitlab/backups/*_gitlab_backup.tar /path/to/backup/location/

# copy config + secrets
sudo cp -a /etc/gitlab/gitlab.rb /etc/gitlab/gitlab-secrets.json /path/to/backup/location/

ALSO SEE: ~/backups/run_gitlab_backup.sh  - used AFTER you run sudo gitlab-backup create
or: run_gitlab_backup_all.sh - does it all makes backup and moves it.
~/backups/run_gitlab_healthcheck.sh 


UPDATE STEPS:

# STOP 1: 18.4.1 -> 18.5.5
sudo dnf install -y gitlab-ee-18.5.5-ee.0.el9
sudo gitlab-ctl reconfigure
sudo gitlab-ctl status
sudo gitlab-rake gitlab:check

# After each hop, confirm GitLab is serving and migrations are done:

sudo gitlab-rake gitlab:background_migrations:status
sudo gitlab-rake db:migrate:status | tail -n 20

# STOP 2: 18.5.5 -> 18.8.4
sudo dnf install -y gitlab-ee-18.8.4-ee.0.el9
sudo gitlab-ctl reconfigure
sudo gitlab-ctl status
sudo gitlab-rake gitlab:check

Does sudo gitlab-ctl status show nginx as “run” now?

Sept 19 2026 Update

Issues with ngixn

Making and Verifying Backups

dnf

Feb 11 2026 Update

Related Posts