GitLab self-hosted на отечественном железе

Инструкция по развёртыванию GitLab self hosted (Omnibus) на отечественном сервере с настройкой runners, встроенного registry и бэкапов. Примерное время выполнения — 2–6 часов в зависимости от сети и размера репозиториев.

• ОС: Ubuntu 22.04 LTS (релиз 2022) или Debian 12 Bookworm, systemd обязателен;
• CPU: минимум 4 виртуальных CPU; рекомендовано 8 CPU для команды >10 разработчиков;
• ОЗУ: минимум 8 ГБ; рекомендовано 16–32 ГБ для продакшена;
• Диск: минимум 100 ГБ под /var/opt/gitlab; рекомендовано 1 ТБ с быстрыми дисками для registry;
• Сеть: порты 22 (SSH), 80/443 (HTTP/HTTPS), при внешнем registry — 5050 или 5005 в зависимости от конфигурации;
• Подключение на уровне инфраструктуры: доступ к DNS, возможность настроить LetsEncrypt или свои сертификаты.

Зачем self-hosted GitLab?

gitlab self hosted даёт полный контроль над хранением кода, политиками доступа и интеграцией с локальными системами учёта и CI. Это критично для организаций с требованиями к локальному хранению данных, соответствию регуляциям и интеграции с внутренними CI/CD инструментами.

При развёртывании self-hosted вы контролируете обновления, резервное копирование и сетевые границы, что позволяет интегрировать GitLab с существующей системой мониторинга, SSO и прокси у провайдера оборудования.

Шаг 1: установка Omnibus

Команды ниже показывают создание репозитория пакетов GitLab CE (Community Edition) и установку версии 16.4.0-ce.0 (релиз 2025). Подходящая команда для Ubuntu 22.04.

sudo apt-get update
sudo apt-get install -y curl ca-certificates gnupg
curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash
sudo apt-get install -y gitlab-ce=16.4.0-ce.0

Пояснение: скрипт регистрирует apt-репозиторий и добавляет GPG-ключ. Мы фиксируем пакет до 16.4.0 для предсказуемости обновлений. Установка пакета обычно занимает 2–5 минут на современном CPU.

Ожидаемый успешный вывод (сокращённый):

Preparing to unpack .../gitlab-ce_16.4.0-ce.0_amd64.deb ...
Setting up gitlab-ce (16.4.0-ce.0) ...
Running handlers complete
GitLab Reconfigured!
  Success: GitLab is running.

Типовая ошибка: "Port 80 is already in use". Причина — nginx/apache уже слушает 80/443.

Решение: остановите конфликтующие сервисы либо настройте GitLab на другие порты в /etc/gitlab/gitlab.rb (параметры external_url и nginx['listen_port']), затем выполните sudo gitlab-ctl reconfigure.

Проверка статуса сервисов:

sudo gitlab-ctl status

Ожидаемый вывод (сокращённый):

run: nginx: (pid 1234) 1s
run: postgresql: (pid 2345) 2s
run: redis: (pid 3456) 2s
run: sidekiq: (pid 4567) 2s
run: gitaly: (pid 5678) 1s

Если сервисы не стартуют, проверьте логи: sudo gitlab-ctl tail. Частая ошибка — недостаток памяти (OOM). Устранение: увеличить swap или RAM, остановить ненужные процессы, затем перезапустить sudo gitlab-ctl restart.

Шаг 2: runners

Установите GitLab Runner 16.4 (релиз 2025). На хосте с Docker рекомендуется использовать Docker executor.

# Установка GitLab Runner
sudo curl -L --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64
sudo chmod +x /usr/local/bin/gitlab-runner
sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash || true
sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
sudo gitlab-runner start

Пояснение: установка бинарником исключает зависимость от пакетного менеджера и даёт версию, которую вы контролируете. Образ Docker executor: gitlab/gitlab-runner:alpine — размер ~60–80 МБ при сжатии.

Регистрация runner (пример):

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.example.com/" \
  --registration-token "PROJECT_OR_GROUP_TOKEN" \
  --executor "docker" \
  --description "docker-runner-1" \
  --docker-image "docker:24.0" \
  --tag-list "docker,self-hosted" \
  --run-untagged="true" \
  --locked="false"

Ожидаемый вывод при успешной регистрации:

Registering runner... succeeded                     runner=xxxxxx
Runner registered successfully. Feel free to start it, but if there is no runner configured yet, it will not pick up jobs.

Частая ошибка: "invalid token" или "401 Unauthorized". Причина — неверный registration token.

Фикс: получите токен на странице проекта или группы: Settings → CI/CD → Runners → Registration token. Для глобального runner используйте токен группы/instance.

Проверка статуса runner:

sudo gitlab-runner verify --delete

Ожидаемый вывод:

Verifying runner... succeeded=1 status=ok

Типичная ошибка при Docker executor: "Cannot connect to the Docker daemon". Решение: убедитесь, что сервис Docker запущен и пользователь имеет доступ к сокету /var/run/docker.sock, либо настройте привилегированный режим.

Шаг 3: registry

Omnibus GitLab включает интегрированный Container Registry. Внесите изменения в /etc/gitlab/gitlab.rb и укажите внешний адрес registry. В примере мы делаем registry на поддомене registry.example.com и используем Let's Encrypt или свои сертификаты.

# /etc/gitlab/gitlab.rb (фрагмент)
external_url 'https://gitlab.example.com'
registry_external_url 'https://registry.example.com'
registry['enable'] = true
registry_nginx['ssl_certificate'] = "/etc/gitlab/ssl/registry.example.com.crt"
registry_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/registry.example.com.key"

Если используете LetsEncrypt встроенный в Omnibus, добавьте:

letsencrypt['enable'] = true
letsencrypt['contact_emails'] = ['admin@example.com']

После изменений выполните:

sudo gitlab-ctl reconfigure

Ожидаемый вывод (сокращённый):

Recipe: registry::enable
  * service[registry] action enable
  * service[registry] action start
  - start service service[registry]
GitLab Reconfigured!
  Success: Registry is running.

Типичная ошибка: «certificate verify failed» при пуше образа. Причина — неправильно установленные сертификаты либо отсутствие доверия на клиенте.

Шаги устранения: проверьте сертификаты на хосте GitLab (/etc/gitlab/ssl/), убедитесь, что цепочка сертификатов полная. На клиентах добавьте CA в доверенные хранилища или используйте доверенный внешний CA. Для тестирования временно можно использовать TLS=false только на изолированном тестовом стенде (не рекомендуется для продакшена).

Пример пуша в registry (docker login и push):

docker login registry.example.com
# Введите имя пользователя GitLab и Personal Access Token с scope write_registry
docker tag my-app:latest registry.example.com/group/project:1.0
docker push registry.example.com/group/project:1.0

Ожидаемый вывод при успешном push (обрывок):

Login Succeeded
The push refers to repository [registry.example.com/group/project]
...
Layer already exists
Pushed tag for rev [sha256:...]

Шаг 4: бэкапы

Omnibus GitLab сохраняет бэкапы данных в /var/opt/gitlab/backups. Бэкап включает репозитории, загрузки, базы данных и артефакты. Конфигурация и секреты сохраняются отдельно.

Создать ручной бэкап:

sudo gitlab-rake gitlab:backup:create STRATEGY=copy
# или без STRATEGY для default
# Резервные копии сохраняются в /var/opt/gitlab/backups

Ожидаемый вывод:

Created backup: 1687654321_2025_06_01_12.7.0_gitlab_backup.tar
Backup finished

Сделать бэкап конфигурации и SSL:

sudo gitlab-ctl backup-etc

Ожидаемый вывод:

Backing up /etc/gitlab to /etc/gitlab.orig.1687654321
Backed up configuration

Автоматизация: добавьте Cron или systemd timer. Пример cron для ежедневного бэкапа в 03:00 и удаления файлов старше 14 дней:

0 3 * * * /usr/bin/gitlab-rake gitlab:backup:create CRON=1
15 3 * * * find /var/opt/gitlab/backups -type f -mtime +14 -delete

Восстановление из бэкапа (важно: версия GitLab на момент восстановления должна совпадать с версией бэкапа):

# Остановите сервисы GitLab
sudo gitlab-ctl stop puma sidekiq unicorn
# Поместите файл бэкапа в /var/opt/gitlab/backups
sudo gitlab-rake gitlab:backup:restore BACKUP=1687654321_2025_06_01_12.7.0
sudo gitlab-ctl start

Частая ошибка: "Backup version mismatch" или "No such file or directory". Причина — файл бэкапа не в каталоге /var/opt/gitlab/backups или несоответствие версий.

Устранение: убедитесь, что tar-файл присутствует, совпадает версия GitLab (например, 16.4). Если необходим перенос между версиями, выполните миграцию по шагам через промежуточные версии согласно официальной документации. Также проверьте права: владельцем должна быть пользователь git или root, и файл должен быть читаемым.

Какие системные требования?

Минимальная конфигурация для пилотного проекта (2025): 4 vCPU, 8 ГБ RAM, 100 ГБ HDD, Ubuntu 22.04. Для продакшен-среды рекомендовано 8 vCPU, 16–32 ГБ RAM, NVMe-диск ёмкостью 1 ТБ и быстрые RAID для registry.

Порты: Git-over-SSH 22, HTTP 80, HTTPS 443. Внутренние сервисы GitLab используют порты для PostgreSQL и Redis, но они обычно доступны по сокетам или петлям. Для отдельного внешнего registry используйте 5050 или специальный поддомен и настройте firewall/iptables.

Мониторинг: планируйте минимум 0.5–2 GB логов в сутки на среднюю команду; настройте ротацию логов и мониторинг дискового пространства. Для CI/CD учитывайте нагрузку на runner: один Docker build может потреблять 1–4 vCPU и 1–4 ГБ RAM в зависимости от сборки.

Как мигрировать с GitHub?

Миграция репозиториев и issues обычно выполняется поэтапно: репозитории, вики, issues/PRs, CI/CD. GitLab поддерживает импорт из GitHub через веб-интерфейс и API, но для большого количества репозиториев рекомендуется скриптовый подход.

Экспорт репозитория через GitHub и импорт в GitLab (пример для одного репозитория):

# Клонировать с GitHub с полной историей
git clone --mirror git@github.com:org/repo.git
# На GitLab создать пустой проект и получить URL: git@gitlab.example.com:group/repo.git
cd repo.git
git push --mirror git@gitlab.example.com:group/repo.git

Ожидаемый вывод:

Counting objects: 12345, done.
Delta compression using up to 8 threads.
Total 12345 (delta 6789), reused 12345 (delta 6789)
To git@gitlab.example.com:group/repo.git
 * [new branch]      main -> main
 * [new tag]         v1.0 -> v1.0

Типичная проблема: "remote: HTTP Basic: Access denied" при пуше. Причина — отсутствие доступа по SSH/ключам или неправильные права на GitLab.

Фикс: настройте SSH-ключи в профиле пользователя GitLab или используйте Personal Access Token и HTTPS. Для массовой миграции используйте скрипты с токеном администратора и проверьте rate limits GitHub API.

Issues и Pull Requests: GitLab предлагает импорт через API (Project Import) или инструменты вида github-to-gitlab. Для сохранения комментариев и метаданных используйте экспорт из GitHub в формате JSON и затем импорт через GitLab API. Для крупных проектов подготовьте mapping пользователей (author mapping), иначе комментарии будут приписаны одному пользователю либо анонимизированы.

Частые вопросы

Какой образ gitlab/gitlab-runner использовать для Docker executor?

Рекомендуется использовать официальный образ gitlab/gitlab-runner:alpine для небольших runner, либо образ на базе docker:24.0 с docker-in-docker (dind) при необходимости сборки контейнеров. Образ gitlab/gitlab-runner:alpine занимает примерно 60–90 МБ в сжатом виде (данные 2025). Для production-использования выберите образ с предустановленными зависимостями, соответствующими вашим сборкам, и ограничьте ресурсы посредством Docker limits и cgroups.

Что делать при нехватке места в /var/opt/gitlab?

Первое действие — проверить, какие директории занимают место: sudo du -sh /var/opt/gitlab/*. Чаще всего растёт папка backups или registry storage. Настройте ротацию и удаление старых backup-файлов, перенесите registry на отдельный диск и настройте символьную ссылку, либо используйте внешнее S3-совместимое хранилище (Omnibus поддерживает настройку object storage для artifacts и LFS). Перед переносом данных остановите GitLab и сделайте полный бэкап.

Почему runner не берёт задания?

Причины: runner помечен как «paused» или не зарегистрирован для нужного проекта/тега. Проверьте в интерфейсе GitLab: Settings → CI/CD → Runners, убедитесь, что runner доступен. Запустите sudo gitlab-runner verify на хосте. Если используется Docker executor, проверьте доступность Docker daemon и наличие необходимых образов. Часто помогает перезапуск runner: sudo gitlab-runner restart и проверка логов /var/log/gitlab/gitlab-runner.log или journalctl -u gitlab-runner.

Зачем нужен отдельный external_url для registry?

Отдельный registry_external_url позволяет иметь отдельный DNS-имя и сертификат для Container Registry, упрощая управление сертификатами и политиками безопасности. Это полезно, если registry нужно размещать за отдельным CDN/прокси или на другом адресе с собственными правилами доступа. Наличие отдельного URL также упрощает настройку docker login и CI/CD, поскольку URL registry будет независим от UI GitLab.

Сколько оперативной памяти нужно для 50 разработчиков?

Для команды около 50 человек рекомендовано 16–32 ГБ RAM и 8 vCPU для самого GitLab, плюс выделенные хосты для runner в зависимости от интенсивности CI. Если команда активно использует CI/CD, планируйте отдельные runner-пулы с общей RAM 32–64 ГБ и быстрые диски для артефактов. Оцените пиковые нагрузки по количеству параллельных билдов и объёму артефактов.

Дополнительные руководства по интеграции CI/CD и Linux-администрированию доступны в категориях DevOps и Linux на сайте. Для примеров конфигураций systemd и автоматизации рекомендуются статьи в разделе DevOps.