# Перенесення self-hosted GitLab на новий сервер

> Перенесення self-hosted GitLab на новий сервер: команда gitlab-backup, перенесення секретів gitlab-secrets.json, відновлення і перенесення Container Registry.

## Способи перенесення self-hosted GitLab

Self-hosted GitLab переносять двома способами: офіційним механізмом резервного копіювання `gitlab-backup` або повним копіюванням каталогів Omnibus-інсталяції. Перший спосіб підходить для переїзду між версіями GitLab, другий — для перенесення «як є» на ідентичну версію.

Перед перенесенням зафіксуйте версію пакета: `gitlab-ce` або `gitlab-ee` однієї версії мають стояти і на старому, і на новому сервері до відновлення бекапу.

## Резервне копіювання через gitlab-backup create

Команда створює архів із репозиторіями, базою даних і вкладеннями, але не включає конфігурацію і секрети:

```
gitlab-backup create BACKUP=2026_09_29
ls /var/opt/gitlab/backups/
```

Файл архіву виду `2026_09_29_16.5.0_gitlab_backup.tar` скопіюйте на новий сервер через scp або rsync.

## Перенесення секретів і gitlab.rb

Без файлу `/etc/gitlab/gitlab-secrets.json` відновлений GitLab не зможе розшифрувати токени CI/CD, паролі користувачів 2FA і змінні середовища. Перенесіть обидва файли конфігурації разом із бекапом:

```
scp /etc/gitlab/gitlab-secrets.json root@newserver:/etc/gitlab/
scp /etc/gitlab/gitlab.rb root@newserver:/etc/gitlab/
```

На новому сервері застосуйте конфігурацію командою `gitlab-ctl reconfigure` до відновлення бекапу.

## Відновлення на новому сервері

Зупиніть сервіси запису даних, залишивши працювати лише базу і Redis, і відновіть архів:

```
gitlab-ctl stop puma
gitlab-ctl stop sidekiq
gitlab-backup restore BACKUP=2026_09_29
gitlab-ctl restart
```

Перевірте вивід команди на помилки відновлення прав доступу — типова проблема, якщо каталог `/var/opt/gitlab/backups` скопійовано без збереження власника `git:git`.

## Перенесення Container Registry і артефактів CI/CD

Образи Container Registry не входять у штатний бекап при зберіганні на локальному диску понад певний обсяг. Перенесіть каталог реєстру окремо:

```
rsync -avz /var/opt/gitlab/gitlab-rails/shared/registry/ root@newserver:/var/opt/gitlab/gitlab-rails/shared/registry/
```

Якщо GitLab запущений у Docker-контейнерах, порядок перенесення самих контейнерів і томів описано в статті про [перенесення Docker-контейнерів між серверами](https://www.zevshost.net/uk/kb/migratsia-docker-konteynerov/). Для великих каталогів реєстру використовуйте методи зі статті про [синхронізацію серверів через rsync](https://www.zevshost.net/uk/kb/rsync-sinhronizatsiya-serverov/) — це дозволить докопіювати дані без повторної повної передачі.

## Перевірка після перенесення

Виконайте діагностику служб і порівняйте кількість проєктів і користувачів:

```
gitlab-rake gitlab:check SANITIZE=true
gitlab-rails runner "puts Project.count"
```

Перевірте клонування одного репозиторію по SSH і HTTPS, запуск CI-пайплайну і вхід хоча б одного користувача з увімкненим 2FA — це найчастіше джерело проблем при перенесенні без секретів.

## Підсумок: чек-лист перенесення GitLab

- Переконайтеся, що версія GitLab на новому сервері збігається з вихідною.
- Створіть бекап через `gitlab-backup create` і перенесіть архів.
- Скопіюйте `gitlab-secrets.json` і `gitlab.rb` до відновлення.
- Відновіть бекап і перенесіть каталог Container Registry окремо.
- Перевірте клонування репозиторію, CI-пайплайн і вхід із 2FA.

Після перемикання DNS на новий сервер пройдіться по загальному [чек-листу перевірки після міграції](https://www.zevshost.net/uk/kb/migratsia-proverka-posle/).

---

Джерело: https://www.zevshost.net/uk/kb/migratsia-gitlab-self-hosted/