GitLab Backup and Restore

A backup is a saved copy of your GitLab data that you can bring back after a failure. Disk crashes, human mistakes, and failed updates all happen eventually. A tested backup turns a crisis into a routine task.

Think of a photo album stored in two places. A fire at home destroys one copy, and the second copy keeps every memory safe. Backups follow the same idea for code, issues, and settings.

Who Needs This Topic

Administrators of self-managed servers own backups. GitLab.com handles server backups for its customers. Users on GitLab.com protect their own work by exporting a project under Settings → General → Advanced → Export project.

What a Backup Contains

  INCLUDED in gitlab-backup                NOT included (save separately)
  ┌───────────────────────────┐           ┌─────────────────────────────┐
  │ Database (issues, users)  │           │ /etc/gitlab/gitlab.rb       │
  │ Git repositories          │           │ /etc/gitlab/gitlab-secrets  │
  │ Uploads and attachments   │           │   .json                     │
  │ CI artifacts and logs     │           │ SSL certificates            │
  │ Container registry data   │           │ SSH host keys               │
  │ Package registry files    │           └─────────────────────────────┘
  └───────────────────────────┘

The secrets file holds the keys that decrypt stored tokens and variables. A restore without that file leaves CI variables and two-factor settings unreadable.

Create a Data Backup

sudo gitlab-backup create

The command writes a tar file into /var/opt/gitlab/backups. The file name carries a timestamp and the GitLab version.

1767225600_2026_01_01_17.8.1_gitlab_backup.tar

Back Up Configuration Files

sudo gitlab-ctl backup-etc

The archive lands in /etc/gitlab/config_backup. Copy it to a different machine. Store configuration backups apart from data backups, because the secrets file combined with the data grants full access.

Skip Parts of a Backup

The SKIP option leaves out large or unneeded areas.

sudo gitlab-backup create SKIP=registry,artifacts

Schedule Daily Backups

A cron job runs the backup at night. Open the root crontab with sudo crontab -e and add one line.

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

The CRON=1 flag silences progress output unless an error occurs.

Keep Old Backups Under Control

Set a retention time in seconds inside /etc/gitlab/gitlab.rb.

gitlab_rails['backup_keep_time'] = 604800

The value above keeps seven days of backups. Apply the change with sudo gitlab-ctl reconfigure.

Store Copies Off the Server

  The 3-2-1 Rule
  ┌─────────────────────────────────────────────┐
  │ 3 copies of the data                        │
  │ 2 different storage types                   │
  │ 1 copy in a different location              │
  └─────────────────────────────────────────────┘

  Server disk ──► Network drive ──► Cloud storage bucket

GitLab can upload backups to object storage after creation. Teams use cloud buckets with encryption and restricted access.

Restore from a Backup

Restoring needs a working GitLab installation of the exact same version as the backup. Place the backup file in /var/opt/gitlab/backups and follow the steps.

Step 1: Restore Configuration Files

Copy gitlab.rb and gitlab-secrets.json from your configuration backup into /etc/gitlab. Apply them.

sudo gitlab-ctl reconfigure

Step 2: Stop Services That Write Data

sudo gitlab-ctl stop puma
sudo gitlab-ctl stop sidekiq

Step 3: Run the Restore

Use the timestamp portion of the file name, without the _gitlab_backup.tar ending.

sudo gitlab-backup restore BACKUP=1767225600_2026_01_01_17.8.1

The tool asks for confirmation before it replaces existing data.

Step 4: Restart and Check

sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart
sudo gitlab-rake gitlab:check SANITIZE=true

Sign in, open a few projects, and confirm that issues, files, and pipelines look correct.

Restore Flow at a Glance

  Fresh server with same GitLab version
        ↓
  Copy config files and secrets
        ↓
  Stop puma and sidekiq
        ↓
  gitlab-backup restore
        ↓
  Restart services and run checks
        ↓
  Verify projects, users, pipelines

Common Restore Problems

Problem	Cause	Fix
Version mismatch error	Backup and server run different GitLab versions	Install the matching version first
CI variables fail to decrypt	The secrets file is missing	Restore gitlab-secrets.json and reconfigure
Permission denied on backup file	Wrong owner	Set the owner to the git user
Not enough disk space	Backup extraction needs room	Free space or mount a larger disk

Backup Habits That Protect You

• Test a full restore on a spare server every quarter.
• Back up before every upgrade.
• Encrypt backup files that leave the server.
• Monitor backup jobs and alert on failures.
• Write down the restore steps and store them outside GitLab.