Back up and restore GitLab

Your software or organization depends on the data in your GitLab instance. You need to ensure this data is protected from adverse events such as:

• Corrupted data
• Accidental deletion of data
• Ransomware attacks
• Unexpected cloud provider downtime

You can mitigate all of these risks with a disaster recovery plan that includes backups.

Back up GitLab

For detailed information on backing up GitLab, see Backup GitLab .

Restore GitLab

For detailed information on restoring GitLab, see Restore GitLab .

Migrate to a new server

You can use GitLab backup and restore to migrate your instance to a new server. This section outlines a typical procedure for a GitLab deployment running on a single server. If you’re running GitLab Geo, an alternative option is Geo disaster recovery for planned failover .

Prerequisites:

• Some time before your migration, consider notifying your users of upcoming scheduled maintenance with a broadcast message banner .
• Ensure your backups are complete and current. Create a complete system-level backup, or take a snapshot of all servers involved in the migration, in case destructive commands (like rm ) are run incorrectly.

Prepare the new server

To prepare the new server:

1. Copy the SSH host keys from the old server to avoid man-in-the-middle attack warnings. See Manually replicate the primary site’s SSH host keys for example steps.
2. Install and configure GitLab except incoming email :
3. Install GitLab.
4. Configure by copying /etc/gitlab files from the old server to the new server, and update as necessary. Read the Linux package installation backup and restore instructions for more detail.
5. If applicable, disable incoming email .

6. Block new CI/CD jobs from starting upon initial startup after the backup and restore. Edit /etc/gitlab/gitlab.rb and set the following:

   nginx['custom_gitlab_server_config'] = "location = /api/v4/jobs/request {\n    deny all;\n    return 503;\n  }\n"
   Reconfigure GitLab:
   
   sudo gitlab-ctl reconfigure
   Stop GitLab to avoid any potential unnecessary and unintentional data processing:
   
   sudo gitlab-ctl stop
   Configure the new server to allow receiving the Redis database and GitLab backup files:
   
   sudo rm -f /var/opt/gitlab/redis/dump.rdb
   sudo chown <your-linux-username> /var/opt/gitlab/redis /var/opt/gitlab/backups
   

Prepare and transfer content from the old server

Ensure you have an up-to-date system-level backup or snapshot of the old server.

Enable maintenance mode , if supported by your GitLab edition.

Block new CI/CD jobs from starting:

Edit /etc/gitlab/gitlab.rb , and set the following:

nginx['custom_gitlab_server_config'] = "location = /api/v4/jobs/request {\n    deny all;\n    return 503;\n  }\n"
Reconfigure GitLab:

sudo gitlab-ctl reconfigure

Disable periodic background jobs:

On the left sidebar, select Search or go to .

Select Admin Area .

On the left sidebar, select Monitoring > Background Jobs .

Under the Sidekiq dashboard, select Cron tab and then Disable All .

Wait for the currently running CI/CD jobs to finish, or accept that jobs that have not completed may be lost. To view jobs currently running, on the left sidebar, select Overviews > Jobs , and then select Running .

Wait for Sidekiq jobs to finish:

On the left sidebar, select Monitoring > Background Jobs .

Under the Sidekiq dashboard, select Queues and then Live Poll . Wait for Busy and Enqueued to drop to 0. These queues contain work that has been submitted by your users; shutting down before these jobs complete may cause the work to be lost. Make note of the numbers shown in the Sidekiq dashboard for post-migration verification.

Flush the Redis database to disk, and stop GitLab other than the services needed for migration:

sudo /opt/gitlab/embedded/bin/redis-cli -s /var/opt/gitlab/redis/redis.socket save && sudo gitlab-ctl stop && sudo gitlab-ctl start postgresql && sudo gitlab-ctl start gitaly
Create a GitLab backup:

sudo gitlab-backup create
Disable the following GitLab services and prevent unintentional restarts by adding the following to the bottom of /etc/gitlab/gitlab.rb:

alertmanager['enable'] = false
gitlab_exporter['enable'] = false
gitlab_pages['enable'] = false
gitlab_workhorse['enable'] = false
grafana['enable'] = false
logrotate['enable'] = false
gitlab_rails['incoming_email_enabled'] = false
nginx['enable'] = false
node_exporter['enable'] = false
postgres_exporter['enable'] = false
postgresql['enable'] = false
prometheus['enable'] = false
puma['enable'] = false
redis['enable'] = false
redis_exporter['enable'] = false
registry['enable'] = false
sidekiq['enable'] = false
Reconfigure GitLab:

sudo gitlab-ctl reconfigure
Verify everything is stopped, and confirm no services are running:

sudo gitlab-ctl status
Transfer the Redis database and GitLab backups to the new server:

sudo scp /var/opt/gitlab/redis/dump.rdb <your-linux-username>@new-server:/var/opt/gitlab/redis
sudo scp /var/opt/gitlab/backups/your-backup.tar <your-linux-username>@new-server:/var/opt/gitlab/backups

Restore data on the new server

Restore appropriate file system permissions:

sudo chown gitlab-redis /var/opt/gitlab/redis
sudo chown gitlab-redis:gitlab-redis /var/opt/gitlab/redis/dump.rdb
sudo chown git:root /var/opt/gitlab/backups
sudo chown git:git /var/opt/gitlab/backups/your-backup.tar
Restore the GitLab backup.
Verify that the Redis database restored correctly:
On the left sidebar, select Search or go to.
Select Admin Area.
On the left sidebar, select Monitoring > Background Jobs.
Under the Sidekiq dashboard, verify that the numbers
match with what was shown on the old server.
While still under the Sidekiq dashboard, select Cron and then Enable All
to re-enable periodic background jobs.
Test that read-only operations on the GitLab instance work as expected. For example, browse through project repository files, merge requests, and issues.
Disable Maintenance Mode, if previously enabled.
Test that the GitLab instance is working as expected.
If applicable, re-enable incoming email and test it is working as expected.
Update your DNS or load balancer to point at the new server.

Unblock new CI/CD jobs from starting by removing the custom NGINX configuration
you added previously:

# The following line must be removed
nginx['custom_gitlab_server_config'] = "location = /api/v4/jobs/request {\n    deny all;\n    return 503;\n  }\n"
Reconfigure GitLab:

sudo gitlab-ctl reconfigure
Remove the scheduled maintenance broadcast message banner.
Additional notes
This documentation is for GitLab Community and Enterprise Edition. We back up
GitLab.com and ensure your data is secure. You can’t, however, use these
methods to export or back up your data yourself from GitLab.com.
Issues are stored in the database, and can’t be stored in Git itself.
Related features
Geo
Disaster Recovery (Geo)
Migrating GitLab groups
Import and migrate projects

Help & feedback

Docs

Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.

Product

Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Join First Look to help shape new features.

Feature availability and product trials

View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.

Get Help

If you didn't find what you were looking for, search the docs .
If you want help with something specific and could use community support, post on the GitLab forum .
For problems setting up or using this feature (depending on your GitLab subscription).

Request support