gitlab-backup

Create a full backup (default strategy)

$ sudo gitlab-backup create

$ sudo gitlab-backup create STRATEGY=[copy]

$ sudo gitlab-backup restore BACKUP=[backup_id]

$ sudo gitlab-backup restore BACKUP=[backup_id] SKIP=[db,uploads,...]

gitlab-backup create [STREAMING_STRATEGY=tar|none] [BACKUP_STRATEGY=copy|incremental] [--skip=db,repositories,...] [--trace] [-v|--verbose] [-h|--help]

--skip=MODEL
    Comma-separated list of components to exclude: db, repositories, uploads, builds, artifacts, lfs_objects, registry, packages, terraform_state, pages.

--trace
    Enable detailed trace logging for debugging.

-v, --verbose
    Increase output verbosity.

-h, --help
    Display help and exit.

STREAMING_STRATEGY=tar|none
    Output format: tar for compressed archive (default), none for directory streaming.

BACKUP_STRATEGY=copy|incremental
    copy stops services briefly (default); incremental backs up live without stops.

The gitlab-backup command is a utility provided by GitLab for generating full or partial backups of a GitLab installation. It captures essential data including the database, Git repositories, uploads, CI/CD artifacts, LFS objects, container registry images, packages, and Terraform state files. Backups are stored as timestamped .tar files in /var/opt/gitlab/backups/ by default, ensuring data integrity for disaster recovery or migrations.

By default, it uses the 'copy' strategy, which briefly stops GitLab services (like Puma and PostgreSQL) to ensure consistency. The 'incremental' strategy allows backups without stopping services, ideal for large instances but requiring more setup. Users can skip specific components via --skip to create targeted backups, reducing size and time. Designed for Omnibus installations, it runs as the 'git' user and respects permissions set by GITLAB_BACKUP_ARCHIVE_PERMISSIONS. Always verify backups before relying on them, as restore requires gitlab-backup restore.

Requires sufficient disk space (can exceed instance size); runs as 'git' user; 'copy' strategy interrupts services briefly; incremental needs prior full backup and GitLab 14.0+; verify backups post-creation.

Backups saved to /var/opt/gitlab/backups/gitlab-backup-<timestamp>.tar; configurable via GITLAB_BACKUP_DIR env var.

Use gitlab-backup restore BACKUP=<timestamp> to restore; stops all services first.

Introduced in early GitLab versions (pre-8.0) for Omnibus; gained incremental strategy in GitLab 14.0 (2021); expanded skip options with features like container registry (11.0+), packages (11.0+), LFS (10.0+).

gitlab-ctl(8), gitlab-rake(8), tar(1), rsync(1)