GitLab CI-раннер на сервере: частые ошибки и решения

MAATRIX

Свой GitLab CI-раннер обещает быстрые и неограниченные сборки, но на практике первые пайплайны часто зависают в статусе pending, падают на правах Docker или забивают диск за неделю. Хорошая новость — почти все ошибки GitLab-раннера на сервере типовые и решаются точечно. Разберём самые частые из них: от заданий, которые никто не берёт, до внезапно вставшего конвейера.

Ошибка: задания висят в pending

Самая частая и обескураживающая ситуация. Пайплайн запустился, но задача бесконечно висит в статусе pending, и раннер её не берёт. В девяти случаях из десяти дело в несовпадении тегов. Если раннер зарегистрирован с определёнными тегами, а задача в .gitlab-ci.yml требует другой тег или не указывает его вовсе, GitLab не находит подходящего исполнителя.

Проверьте две вещи. Первая — теги задачи должны совпадать с тегами раннера. Вторая — в настройках раннера есть опция, разрешающая брать задания без тегов; если она выключена, а задача без тегов, раннер её проигнорирует. Сверьте теги в интерфейсе GitLab и в файле пайплайна:

build:
  tags:
    - docker
  script:
    - echo ok

Ещё одна причина — раннер просто не в статусе online. Если он давно не выходил на связь, GitLab считает его недоступным. Проверьте, что сервис раннера запущен на сервере и достукивается до GitLab.

Ошибка: раннер offline после регистрации

Раннер зарегистрирован, виден в проекте, но помечен как offline и не берёт задания. Раннер общается с GitLab, сам инициируя соединения, поэтому причина — либо сервис не запущен, либо он не может достучаться до адреса GitLab. Проверьте состояние сервиса и его логи:

systemctl status gitlab-runner
journalctl -u gitlab-runner --since "10 min ago"

Если сервис остановлен — запустите его и включите в автозапуск. Если запущен, но в логах ошибки соединения, проверьте, что с сервера вообще открывается адрес вашего GitLab и не мешает ли исходящему трафику фаервол. Раннеру не нужны входящие порты, но исходящие соединения к GitLab обязаны проходить. При неверно указанном при регистрации адресе GitLab раннер тоже останется offline — тогда его перерегистрируют с правильным URL.

Ошибка: permission denied при работе с Docker

Пайплайн с Docker-исполнителем падает с ошибкой доступа к Docker-сокету или невозможности запустить контейнер. Причина в правах: процесс раннера должен иметь доступ к Docker. При установке из официального пакета это обычно настроено, но при ручной конфигурации или использовании Docker-in-Docker всплывают нюансы.

Убедитесь, что пользователь, под которым работает раннер, входит в группу docker, и что тип исполнителя и образ заданы корректно. Для сборок, которые сами собирают Docker-образы, нужен особый режим — либо привилегированный контейнер, либо проброс сокета, и у каждого варианта свои последствия для безопасности. Не включайте привилегированный режим бездумно: он расширяет возможности сборки, но и повышает риски, если в пайплайн попадёт чужой код. Взвесьте, что именно собираете, и выбирайте минимально достаточные права.

Ошибка: диск забился и пайплайны встали

Через неделю-другую активной работы пайплайны внезапно начинают падать с ошибкой нехватки места, хотя проект небольшой. Это классика Docker-исполнителя: каждая сборка тянет образы, создаёт контейнеры и временные слои, а старое никто не убирает. Диск заполняется незаметно, пока не встанет всё разом.

Решение — регулярная очистка неиспользуемых образов, контейнеров и кеша. Её настраивают по расписанию, чтобы не делать вручную:

docker system prune -af
df -h

Первая команда убирает всё неиспользуемое, вторая показывает, сколько места освободилось. Заведите такую очистку в cron или в саму конфигурацию раннера. И честно оцените объём диска: если сборки тяжёлые и частые, маленького диска не хватит в принципе, и разумнее взять VPS с большим быстрым накопителем, чем каждый день чистить вручную.

Ошибка: медленные сборки без кеша

Пайплайн отрабатывает, но мучительно долго: каждая сборка заново скачивает все зависимости с нуля. Причина в том, что кеш между сборками не настроен. Без него установка пакетов фронтенда или зависимостей бэкенда повторяется каждый раз, съедая минуты и трафик.

Настройте кеширование каталогов зависимостей в .gitlab-ci.yml, привязав кеш к файлу блокировки версий, чтобы он переиспользовался, пока зависимости не изменились:

cache:
  key:
    files:
      - package-lock.json
  paths:
    - node_modules/

Так пакеты скачиваются только при изменении зависимостей, а обычные прогоны берут их из кеша. Дополнительно ускоряет дело кеш слоёв Docker-образов. Если после всех оптимизаций сборки всё равно упираются во время, посмотрите на ресурсы сервера: нехватка ядер и памяти растягивает компиляцию, и переход на более мощный VPS окупается сэкономленным временем команды.

Ошибка: раннер не стартует после перезагрузки

Перезагрузили сервер под обновления — и обнаружили, что пайплайны не идут, потому что раннер не поднялся. При установке из пакета сервис ставится в автозапуск, но если раннер настраивали нестандартно или отключали автозапуск при отладке, он останется выключенным.

Проверьте и при необходимости включите автозапуск:

systemctl is-enabled gitlab-runner
systemctl enable --now gitlab-runner

Первая команда должна показать enabled. Возьмите за правило после любой перезагрузки убеждаться, что раннер в статусе online в интерфейсе GitLab. Тихо выпавший раннер коварен: пайплайны копятся в очереди, а команда не понимает, почему ничего не собирается.

Как выстроить стабильную работу раннера

Большинство перечисленных проблем не возникают, если с самого начала соблюдать несколько правил. Согласуйте теги задач и раннера, чтобы задания находили исполнителя. Настройте кеш зависимостей и регулярную очистку Docker, чтобы сборки были быстрыми, а диск свободным. Проверьте автозапуск и следите за статусом online. Подберите ресурсы сервера под реальную тяжесть сборок, а не под минимум.

Отдельно окупается адекватный VPS. Быстрый диск и достаточные ядра с памятью убирают половину проблем со скоростью и местом ещё до их появления. У MAATRIX сервер под раннер оплачивается из России картой, по СБП или криптой, а конфигурацию можно нарастить, когда сборки станут тяжелее. На такой основе свой GitLab-раннер работает предсказуемо и экономит команде часы ожидания.

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