How to Efficiently Back Up GitLab 17.8: Pure Repos and Full Instance Strategies

Backing up GitLab is essential for business continuity, disaster recovery, and quick migration. Depending on the scenario, you may need a pure Git repository for easy migration or a full application backup that includes GitLab‑specific metadata.

Why Back Up as a Pure Git Repository?

Pure Git backups are advantageous when you only need the code and want a format compatible with standard Git tools.

Convenient Migration: Easy to move to other Git platforms such as GitHub or a self‑hosted Gitea instance.

Standard Tool Compatibility: Works seamlessly with ordinary Git commands for inspection, analysis, or restoration.

Fast Access and Recovery: Restoring code from a bare repository is much quicker than extracting it from a full GitLab backup.

Note: A pure Git backup does not contain GitLab‑specific metadata such as issues, merge requests, wiki pages, CI/CD pipeline history, or user comments.

Method 1: Using git clone --mirror to Get a Pure Git Repository

This is the most straightforward way to obtain a bare repository.

Steps:

Obtain the repository URL: Find the HTTP or SSH URL of the GitLab project you want to back up.

Run the clone command: Execute the following on your backup server or local machine:

git clone --mirror <GitLab repository URL> /path/to/your/backup/repo.git

<GitLab repository URL>

can be HTTP(S) (requires username/password or a personal access token for private repos) or SSH (requires a configured SSH key). /path/to/your/backup/repo.git is the local directory where the bare repository will be stored; the .git suffix is conventional for bare repos.

Example (SSH):

git clone --mirror [email protected]:mygroup/myproject.git /backups/gitlab/mygroup/myproject.git

After execution, /backups/gitlab/mygroup/myproject.git contains a complete, clean mirror of the project.

Advantages: Simple, requires only standard Git tools, produces a standard bare repository that is easy to use and migrate.

Disadvantages: Does not include GitLab‑specific data (issues, MRs, CI configuration, etc.) and must be run individually for each repository; scripting is needed for bulk operations.

Practical Tips:

Automate the process with a script that reads a project list via the GitLab API and loops the git clone --mirror command.

Run the script regularly; re‑executing the command updates the mirror incrementally.

Store the backups off‑site or in object storage for added safety.

Method 2: Using GitLab’s Built‑In Rake Task for Application Backup (Repository + Partial Config)

For a more comprehensive backup that includes most GitLab metadata, GitLab recommends its built‑in Rake task.

Backup command (GitLab 17.8): sudo gitlab-rake gitlab:backup:create Execution environment: Run as root or a user with sufficient privileges on the GitLab server.

Backup contents:

Database (issues, merge requests, users, permissions, CI/CD settings, etc.)

Git repositories (stored in the configured data directory)

Uploaded files

CI/CD artifacts

LFS objects

The resulting file is a .tar archive placed in the backup path defined in gitlab.rb (default /var/opt/gitlab/backups).

Advantages: Provides a near‑complete snapshot of the GitLab instance, officially supported and tested.

Disadvantages: The archive is not a ready‑to‑use bare Git repository; restoration requires a GitLab instance of the same version and type, and root access is needed.

Practical Tips:

Add the command to a cron job for daily or more frequent automated backups.

Configure gitlab.rb to set gitlab_rails['backup_path'] to a dedicated disk or mount point.

Enable automatic upload of backup archives to remote storage (S3, Google Cloud, etc.) via gitlab.rb settings.

Set gitlab_rails['backup_keep_time'] to purge old backups and save space.

Backing Up GitLab‑Specific Configuration Files

Critical configuration files are stored in: /etc/gitlab/gitlab.rb: Core Omnibus configuration. /etc/gitlab/gitlab-secrets.json: Contains encryption keys; loss renders 2FA users unable to log in and destroys CI/CD secret variables.

Certificate files (e.g., under /etc/gitlab/ssl) if HTTPS is configured.

GitLab provides a command to back up these files: sudo gitlab-ctl backup-etc The command packages /etc/gitlab into a .tar archive, stored by default in /etc/gitlab/config_backup/.

Practical Tips:

Include this command in your automated backup workflow.

Store the resulting configuration archive (and the Rake backup) in off‑site or cloud storage.

Safeguard gitlab-secrets.json; it is essential for restoring the GitLab instance.

Combining Methods: Building a More Robust Backup Strategy

For critical repositories that need rapid restoration or frequent Git‑only operations, run git clone --mirror on a high‑frequency schedule.

Use the GitLab Rake task for daily or periodic full‑instance backups as the primary disaster‑recovery mechanism.

Regularly back up the configuration directory ( /etc/gitlab) with gitlab-ctl backup-etc.

Upload all backup artifacts (bare repository mirrors, Rake .tar archives, configuration backups) to secure off‑site or cloud storage.

Test restoration regularly: Periodic drills ensure backups are valid and recovery procedures are well understood.

Conclusion

In GitLab 17.8, the quickest way to obtain a pure Git repository is git clone --mirror, which backs up only the code. For a comprehensive backup that includes repositories and GitLab‑specific metadata, use sudo gitlab-rake gitlab:backup:create. Remember to also back up core configuration files with sudo gitlab-ctl backup-etc, especially gitlab-secrets.json. A layered, automated backup strategy with regular restoration tests is the key to keeping your GitLab data safe.