gitlab-backup

Create and restore GitLab instance backups

TLDR

Create a full GitLab backup

$ sudo gitlab-backup create

Create a backup, skipping selected components

$ sudo gitlab-backup create SKIP=db,uploads,registry

Create an incremental backup

$ sudo gitlab-backup create INCREMENTAL=yes PREVIOUS_BACKUP=[backup_id]

Restore from a backup file

$ sudo gitlab-backup restore BACKUP=[timestamp_version]

Restore selected components only

$ sudo gitlab-backup restore BACKUP=[timestamp] SKIP=registry,uploads

SYNOPSIS

gitlab-backup command [VAR=value ...]

gitlab-backup creates and restores backups of a GitLab Omnibus or source installation. A backup bundles the database, Git repositories, uploads, CI artifacts, container registry, Pages content, and other components into a single tar archive named TIMESTAMP_VERSION_gitlab_backup.tar.Backups are written to the directory configured by gitlab_rails['backup_path'] (default /var/opt/gitlab/backups). The configuration files (gitlab.rb, secrets.json) are not included and must be backed up separately.

PARAMETERS

SKIP components

Comma-separated list of components to omit. Valid values: db, repositories, uploads, builds, artifacts, lfs, registry, pages, terraform_state, packages, ci_secure_files.

BACKUP id

Identifier (timestamp_version) of the backup to restore. Required for restore.

STRATEGY value

Use copy to copy data to a tmp dir before tarring (safer for active sites); default streams directly.

INCREMENTAL yes

Create an incremental backup (requires existing PREVIOUS_BACKUP).

PREVIOUS_BACKUP id

Backup ID to base the incremental backup on.

GITLAB_BACKUP_MAX_CONCURRENCY N

Maximum number of concurrent processes for repository backups.

GZIP_RSYNCABLE yes

Use gzip's --rsyncable mode so backups deduplicate efficiently with rsync.

SUBCOMMANDS

create

Create a backup archive of the GitLab instance.

restore

Restore a GitLab instance from a previously created backup.

CAVEATS

Run as root (typically via sudo). Restore requires the same GitLab major.minor version as the backup. Stop puma and sidekiq before a restore (gitlab-ctl stop puma sidekiq). Configuration files (/etc/gitlab/gitlab.rb, /etc/gitlab/gitlab-secrets.json) are not included in the backup tarball — back them up separately or restore will fail to decrypt secrets.

HISTORY

gitlab-backup is a wrapper around the gitlab:backup:create and gitlab:backup:restore Rake tasks, introduced in GitLab 12.2 (August 2019) as the recommended interface for Omnibus installations.