Linux package

The backup is created by the gitlab-backup command on the instance machine. The contents of the archive and the list of files stored separately are on the Overview page.

Creating a backup

A backup is taken with a single command:

sudo gitlab-backup create

The archive appears in the /var/opt/gitlab/backups/ directory under a name of the form <TIMESTAMP>_<DATE>_<ENGINE_VERSION>_gitlab_backup.tar. The version in the name is the version of the built-in engine, which differs from the version of the deckhouse-code package, so record the package version next to the archive when you take a backup:

# RED OS.
rpm -q deckhouse-code
# Ubuntu.
dpkg -l deckhouse-code

Archive retention

The retention time is set in the /etc/gitlab/gitlab.rb file in seconds:

# Seven days.
gitlab_rails['backup_keep_time'] = 604800

The change takes effect after sudo gitlab-ctl reconfigure. Archives older than backup_keep_time are deleted when the next backup is created.

Schedule

Regular backups are set up with a cron job, for example daily at 02:00:

echo '0 2 * * * root /opt/gitlab/bin/gitlab-backup create CRON=1' \
  | sudo tee /etc/cron.d/deckhouse-code-backup

Copying off the host

Regularly move fresh archives from the /var/opt/gitlab/backups/ directory to a separate server, for example with the rsync command. Copy the /etc/gitlab/gitlab-secrets.json and /etc/gitlab/gitlab.rb files together with the archive: without them the archive is not restored completely.

Restoring

Restoring replaces the instance data with the contents of the archive.

Preconditions

Before you start the restore, check that the conditions are met:

• The installed package is exactly the version on which the backup was taken (rpm -q deckhouse-code or dpkg -l deckhouse-code).
• The /etc/gitlab/gitlab.rb and /etc/gitlab/gitlab-secrets.json files from the original machine are in place. When moving to a new server, copy them before the restore and run sudo gitlab-ctl reconfigure.
• The certificates and keys from the /etc/gitlab/ssl/ directory are in place: gitlab.rb refers to them by path, and without these files gitlab-ctl reconfigure fails to start nginx.

Steps

<BACKUP_NAME> in the commands is the archive file name without the _gitlab_backup.tar suffix: for the 1784800000_2026_07_23_19.1.2_gitlab_backup.tar archive it is 1784800000_2026_07_23_19.1.2.

1. Copy the archive to the backup directory and hand the file over to the git user:

   sudo cp <BACKUP_NAME>_gitlab_backup.tar /var/opt/gitlab/backups/
   sudo chown git:git /var/opt/gitlab/backups/<BACKUP_NAME>_gitlab_backup.tar

2. Stop the services that write to the database; the other services keep running:

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

3. Restore the data from the archive:

   sudo gitlab-backup restore BACKUP=<BACKUP_NAME>

   The command asks for confirmation twice: before recreating the authorized_keys file and before dropping the current database tables. Answer yes both times.

4. Restart the instance and run the self-check:

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

5. Sign in to the web interface and clone a repository to make sure the data is in place.