Как безопасно обновить self-managed GitLab: обязательные остановки, бэкапы и откат

21 октября 2026 года GitLab закрыл уязвимость CVE-2026-110264 с максимальной оценкой CVSS 10.0, и многим администраторам self-managed GitLab пришлось срочно обновляться. Для кого-то это была пятиминутная установка патча, а кто-то обнаружил, что сервер отстал на два-три мажорных релиза и прыгнуть сразу на свежую версию нельзя. Разбираем, как обновлять GitLab так, чтобы обновление не превратилось в аварию: как устроены релизы, что такое обязательные остановки, что подготовить заранее и как откатиться, если что-то пошло не так.

Как GitLab выпускает версии

Версии GitLab нумеруются по схеме мажорная.минорная.патч, например 19.5.1. Минорный релиз выходит каждый месяц, в третий четверг. Мажорный — раз в год, обычно в мае; GitLab 20.0 запланирован на май 2027 года. Патч-релизы выходят дважды в месяц по средам: за неделю до минорного релиза и через неделю после. Критические уязвимости закрываются внеплановыми патчами, как это было с CVE-2026-110264.

Исправления безопасности GitLab переносит в текущую стабильную версию и две предыдущие ежемесячные — то есть сейчас это 19.5, 19.4 и 19.3. Исправления обычных ошибок получает только текущая версия. Отсюда простое правило: если ваш GitLab старше трёх последних минорных версий, следующий патч безопасности может до вас не дойти. В случае с CVE-2026-110264 GitLab сделал исключение и выпустил исправления вплоть до 18.11, но рассчитывать на это каждый раз не стоит.

Обязательные остановки: почему нельзя прыгнуть сразу на последнюю версию

При обновлении GitLab выполняет миграции базы данных, и часть из них рассчитана на то, что предыдущие уже завершены. Поэтому в документации есть понятие required upgrade stops — версии, через которые обязательно нужно пройти. Начиная с GitLab 17.5 они стоят на минорных версиях x.2, x.5, x.8 и x.11. Для 18-й ветки это 18.2, 18.5, 18.8 и 18.11, для 19-й — 19.2, 19.5, 19.8 и 19.11. У более старых веток список свой и иногда зависит от конфигурации: например, отдельные остановки нужны только инсталляциям с большим числом пользователей или пакетов.

Порядок такой: обновиться до первой обязательной остановки после текущей версии, дождаться завершения фоновых миграций, перейти к следующей остановке — и так до целевой версии. Точный маршрут для своей версии удобно посчитать в Upgrade Path tool от команды поддержки GitLab. Например, с 18.4 до 19.5 путь выглядит как 18.5 → 18.8 → 18.11 → 19.2 → 19.5, и на каждом шаге нужно дождаться окончания миграций.

Подготовка: что сделать до обновления

1. Узнать текущую версию. Её видно в разделе Admin и на странице /help под администратором; на сервере с Linux-пакетом — ещё и в выводе sudo gitlab-rake gitlab:env:info.
2. Прочитать upgrade notes для каждой версии на маршруте. Там описаны изменения, которые требуют действий: удалённые настройки, новые требования к окружению, долгие миграции.
3. Проверить фоновые миграции. В интерфейсе: Admin → Monitoring → Background migrations, вкладки Queued и Finalizing должны быть пустыми, а в Failed не должно быть записей. В консоли на GitLab 18.9 и новее — sudo gitlab-rake gitlab:background_migrations:list, на 18.8 и старше — sudo gitlab-rake gitlab:background_migrations:status. С 19.5 появилась команда sudo gitlab-rake gitlab:background_migrations:wait, которая ждёт окончания миграций и подходит для скриптов. Команду finalize для проверки не используйте: это инструмент ремонта упавших миграций.
4. Сделать резервную копию. sudo gitlab-backup create для Linux-пакета или docker exec -t <контейнер> gitlab-backup create для Docker. Важно: бэкап не включает конфигурацию. Файлы /etc/gitlab/gitlab-secrets.json и /etc/gitlab/gitlab.rb нужно сохранить отдельно и хранить не рядом с бэкапом. Без gitlab-secrets.json GitLab не сможет расшифровать данные в базе — переменные CI/CD, токены, настройки двухфакторной аутентификации. Стоит сохранить и TLS-сертификаты, и SSH-ключи хоста.
5. Проверить PostgreSQL. GitLab 18 требует PostgreSQL не ниже 16.5, GitLab 19 — не ниже 17. Если база внешняя (например, managed-сервис в облаке), обновлять её придётся отдельно и заранее.
6. Проверить раннеры. Мажорная и минорная версии GitLab Runner должны совпадать с версией GitLab. Обратная совместимость между минорными версиями гарантируется, но новые функции могут требовать свежий раннер. GitLab рекомендует обновлять раннеры до целевой версии вместе с сервером.
7. Отрепетировать на копии. Лучший способ узнать, сколько займут миграции и где всё сломается, — прогнать обновление на клоне продакшена. Там же стоит проверить восстановление из бэкапа: бэкап, который ни разу не восстанавливали, — это надежда, а не план.

Обновление: Linux-пакет, Docker и Helm

Linux-пакет (Omnibus). Менеджер пакетов по умолчанию ставит самую свежую версию, поэтому при обновлении через остановки версию нужно указывать явно: sudo apt update && sudo apt install gitlab-ee=<версия>-ee.0 для Debian и Ubuntu или sudo dnf install gitlab-ee-<версия>-ee.0.el9 для RHEL-совместимых систем; для Community Edition — gitlab-ce. Перед установкой новой версии пакет сам делает резервную копию базы, но собственный полный бэкап это не заменяет. На время обновления можно включить режим обслуживания и приостановить CI/CD.

Docker. Контейнер останавливают и удаляют (docker stop gitlab, docker rm gitlab), скачивают образ нужной версии (docker pull gitlab/gitlab-ee:<версия>-ee.0) и запускают заново с теми же томами для конфигурации, логов и данных. При первом запуске GitLab сам применит миграции. С Docker Compose — меняют тег образа в docker-compose.yml и выполняют docker compose pull и docker compose up -d. Тег latest для продакшена — плохая идея: так легко перепрыгнуть обязательную остановку.

Helm-чарт в Kubernetes. Версии чарта нумеруются не так, как версии GitLab, — соответствие нужно смотреть в таблице version mappings. Текущие значения выгружают командой helm get values gitlab > gitlab.yaml, затем выполняют helm upgrade gitlab gitlab/gitlab --version <версия чарта> -f gitlab.yaml. Документация чарта советует идти по одной минорной версии за раз: пропуск релизов может выполнить изменения схемы базы в неправильном порядке.

Можно ли без простоя

Обновление без простоя GitLab поддерживает только для многоузловых инсталляций с балансировщиком и отказоустойчивыми Consul, PostgreSQL и Redis. Обновляться в этом режиме нужно строго на одну минорную версию за раз, а компоненты — в определённом порядке: сначала Consul, PostgreSQL, PgBouncer и Redis, потом Gitaly и Praefect, в конце Rails и Sidekiq. Компоненты без отказоустойчивости всё равно обновляются с остановкой. Для GitLab на одном сервере простой неизбежен: заложите окно обслуживания и предупредите команду. Длительность зависит от объёма базы и миграций — именно поэтому полезна репетиция на копии.

Проверки после обновления

• sudo gitlab-rake gitlab:check — общая проверка конфигурации и сервисов.
• sudo gitlab-rake gitlab:doctor:secrets — проверяет, что зашифрованные данные в базе расшифровываются текущими секретами.
• Вручную: вход пользователей, список проектов и задач, git clone и git push, запуск пайплайна, работа раннеров, загрузка и скачивание образов из реестра.
• Фоновые миграции новой версии: перед следующим шагом маршрута они должны завершиться.
• Свежий бэкап конфигурации: gitlab-secrets.json может измениться после обновления.

Если нужно откатиться

Откатить GitLab простой переустановкой старого пакета нельзя: миграции уже изменили базу. Для отката нужен бэкап базы, сделанный на той же версии и редакции, на которую вы возвращаетесь. Порядок для Linux-пакета: остановить Puma и Sidekiq, удалить текущий пакет, установить прежнюю версию, выполнить sudo gitlab-ctl reconfigure и восстановить бэкап. Поэтому бэкап делают непосредственно перед каждым шагом маршрута, а не один раз в начале.

Коротко

1. Обновляйтесь регулярно: если держаться в пределах трёх последних минорных версий, патчи безопасности ставятся за минуты.
2. Если отстали — считайте маршрут в Upgrade Path tool и проходите все обязательные остановки, дожидаясь фоновых миграций.
3. Перед каждым шагом — бэкап, отдельно gitlab-secrets.json и gitlab.rb.
4. Следите за версиями PostgreSQL и раннеров.
5. Репетируйте на копии и держите план отката.

Мы сопровождаем self-managed GitLab и CI/CD для проектов клиентов. Посчитаем маршрут обновления, прогоним его на копии, обновим продакшен с резервной копией и планом отката, проверим раннеры и пайплайны — и настроим регулярные обновления, чтобы следующий критический патч ставился за минуты, а не за выходные.

Источники: политика выпуска и поддержки версий GitLab, upgrade paths, планирование обновления, фоновые миграции, резервное копирование, системные требования, GitLab Runner, обновление Linux-пакета, обновление в Docker, обновление Helm-чарта, обновление без простоя, откат версии.