Skip to content

Обновление Gitlab

Инструкция по обновлению GitLab

Введение

Цель документа

Этот документ содержит пошаговую инструкцию для безопасного и последовательного обновления GitLab Community Edition (CE), установленного на сервере с Ubuntu через Omnibus-пакет.

Инструкция составлена на основе реального опыта обновления и включает в себя решения для всех потенциальных проблем, возникших в процессе.

Фаза 1: Подготовка (самый важный этап)

Перед началом обновления необходимо выполнить следующие подготовительные шаги. Не пропускайте их!

Шаг 1.1: Создание и копирование резервной копии

Это обязательный шаг для защиты ваших данных.

  1. Запустите сессию screen, чтобы процесс не прервался из-за разрыва SSH-соединения:

    screen -S gitlab-backup

  2. Запустите создание бэкапа:

    sudo gitlab-backup create

    Процесс может быть долгим. После его завершения убедитесь, что в директории /var/opt/gitlab/backups/ появился .tar файл с бэкапом.

  3. (Рекомендуется) Скопируйте бэкап на локальный компьютер. Для максимальной безопасности рекомендуется скопировать созданный архив с резервной копией с VDS на ваш локальный компьютер.

    1. Узнайте точное имя файла бэкапа на сервере. Следующая команда выведет имя самого свежего файла в директории с бэкапами: 
      ls -t /var/opt/gitlab/backups/ | head -n 1
    2. Скачайте файл с помощью scp. Откройте PowerShell на вашем локальном компьютере (Windows) и выполните команду по следующему шаблону: 
      # Шаблон
scp <имя_пользователя_на_сервере>@<IP_адрес_сервера>:/var/opt/gitlab/backups/<имя_файла_бэкапа.tar> <локальный_путь_для_сохранения>

# Пример
scp root@192.168.1.10:/var/opt/gitlab/backups/1752740631_2025_07_17_17.5.5_gitlab_backup.tar C:\backups\gitlab\

    Теперь, имея локальную копию, вы можете быть уверены в сохранности данных, даже если с сервером что-то случится.

Шаг 1.2: Проверка и освобождение дискового пространства

Обновление GitLab требует значительного свободного места на диске для скачивания (более 1.3 ГБ) и распаковки пакета.

  1. Проверьте доступное место:

    df -h

    Убедитесь, что на корневом разделе (/) или на /var достаточно свободного места (рекомендуется иметь не менее 5 ГБ).

  2. Очистите кэш пакетов apt. Это самый быстрый и безопасный способ освободить место перед обновлением:

    sudo apt-get clean

  3. (При необходимости) Удалите старые резервные копии GitLab. Если места все еще недостаточно, его можно освободить, удалив старые бэкапы.

    1. Посмотрите список существующих бэкапов и их размеры: 
      ls -lh /var/opt/gitlab/backups/
    2. Удалите ненужные старые файлы. Внимание: убедитесь, что у вас есть свежая и скопированная резервная копия (см. Шаг 1.1), прежде чем удалять старые. 
      # Пример удаления конкретного файла
sudo rm /var/opt/gitlab/backups/1752740631_2025_07_17_17.5.5_gitlab_backup.tar

Шаг 1.3: Определение правильного пути обновления

GitLab нельзя обновлять сразу до последней версии. Необходимо следовать официальному пути обновления, проходя через обязательные промежуточные версии ("required upgrade stops").

  1. Узнайте вашу текущую версию:

    cat /opt/gitlab/embedded/service/gitlab-rails/VERSION

  2. Определите маршрут обновления. Перейдите на официальный сайт GitLab Upgrade Path Tool, введите вашу текущую версию и выберите "CE". Сайт покажет вам точную последовательность версий для обновления.

Фаза 2: Процесс обновления

Выполняйте установку строго последовательно для каждой версии из маршрута, который вы получили на предыдущем шаге.

Шаг 2.1: Последовательная установка

Для каждой промежуточной версии из вашего маршрута (например, 17.3.7-ce.0) выполните следующие команды:

  1. Установите конкретную версию:

    # Пример для версии 17.3.7
sudo apt-get install gitlab-ce=17.3.7-ce.0

  2. Проверьте статус после установки. Убедитесь, что все сервисы запустились корректно, прежде чем переходить к следующей версии.

    # Проверка статуса сервисов
sudo gitlab-ctl status

# Проверка установленной версии
cat /opt/gitlab/embedded/service/gitlab-rails/VERSION

Повторяйте эти два пункта для каждой версии в вашем маршруте обновления.

После установки последней версии из вашего маршрута, зайдите в веб-интерфейс GitLab и убедитесь, что все работает корректно, а уведомление о необходимости обновления исчезло.

Поздравляем, ваш GitLab обновлен!

Фаза 3: Решение известных проблем (Troubleshooting)

Здесь собраны решения для ошибок, с которыми можно столкнуться в процессе.

Проблема 1: Ошибка apt update из-за лишнего репозитория

  • Симптом: При выполнении sudo apt update появляется ошибка 403 Forbidden для репозитория gitlab-ee.
  • Причина: В системе одновременно подключены репозитории для Community Edition (CE) и Enterprise Edition (EE).
  • Решение:
    1. Найдите лишний файл конфигурации: ls -l /etc/apt/sources.list.d/. Он будет называться примерно gitlab_gitlab-ee.list.
    2. Удалите его: sudo rm /etc/apt/sources.list.d/gitlab_gitlab-ee.list.
    3. Повторите sudo apt update.

Проблема 2: Обновление прерывается из-за нехватки места

  • Симптом: В процессе установки появляется ошибка No space left on device.
  • Решение: Вернитесь к Шагу 1.2 и убедитесь, что вы освободили достаточно места. Очистите кэш apt и, при необходимости, удалите старые ненужные бэкапы из /var/opt/gitlab/backups/.

Проблема 3: Обновление прерывается из-за таймаута базы данных

  • Симптом: На этапе pre-installation script появляется ошибка PG::QueryCanceled: ERROR: canceling statement due to statement timeout.
  • Причина: Автоматическое создание бэкапа перед установкой не укладывается в отведенное время.
  • Решение:
    1. Создайте "файл-флаг", чтобы пропустить автоматический бэкап. Это безопасно, так как вы уже сделали полный бэкап на Шаге 1.1. 
      sudo touch /etc/gitlab/skip-auto-backup
    2. Повторите команду установки sudo apt-get install ... для нужной версии. Обновление должно пройти без ошибки с бэкапом.
    3. Важно! После того, как вы успешно завершите все этапы обновления до финальной версии, обязательно удалите созданный файл, чтобы будущие обновления работали в штатном режиме: 
      sudo rm /etc/gitlab/skip-auto-backup