Как установить и настроить GitLab CI-раннер на VPS

MAATRIX

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

Зачем свой раннер вместо общих

GitLab CI выполняет пайплайны на раннерах — исполнителях, которые забирают задания, собирают проект и прогоняют тесты. Публичные общие раннеры GitLab.com удобны для старта, но у них есть потолок бесплатных минут, а сборки идут на инфраструктуре, которую вы не контролируете. Для приватного кода, тяжёлых сборок или частых пайплайнов это становится узким местом.

Собственный раннер решает эти вопросы. Вы не платите за минуты — платите только за VPS, на котором он крутится, и используете его сколько угодно. Окружение полностью под вашим контролем: нужные версии инструментов, доступ к приватным ресурсам, кеш между сборками. И данные проекта не покидают вашу инфраструктуру, что важно для чувствительного кода.

Ещё один практичный плюс для российских команд — независимость от способа оплаты зарубежных сервисов. VPS у MAATRIX оплачивается картой РФ, по СБП, криптой или токеном MAAT, а локацию можно выбрать под задачу: US ближе к зарубежным реестрам пакетов и внешним API, RU — к российским сервисам с минимальным пингом.

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

Шаг 1. Выбор сервера под раннер

Требования к VPS зависят от того, что вы собираете. Для лёгких проектов — линтинг, тесты небольшого бэкенда — хватает двух ядер и 2 ГБ памяти. Сборка фронтенда с установкой зависимостей, компиляция или прогон Docker-образов заметно прожорливее: там комфортнее четыре ядра, 4–8 ГБ памяти и быстрый диск, потому что установка пакетов и сборка активно работают с диском.

Не экономьте на диске: сборки создают много временных файлов, тянут зависимости и образы. Медленный или маленький диск станет узким местом раньше, чем процессор. Работаем на Ubuntu 24.04 с root-доступом. Сразу поставьте базовую защиту — вход по SSH-ключу и фаервол, ведь раннер будет иметь доступ к вашему коду и, возможно, к секретам деплоя.

Шаг 2. Установка Docker

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

curl -fsSL https://get.docker.com | sh
docker --version

Docker-executor даёт воспроизводимость: пайплайн всегда стартует из заданного образа, и результат не зависит от того, что осталось на сервере после предыдущих запусков. Это избавляет от классической проблемы «на моей машине работает» и делает сборки предсказуемыми. Альтернативный shell-executor запускает команды прямо в системе сервера — он проще, но грязнее и менее безопасен, поэтому для большинства задач выбирают именно Docker.

Шаг 3. Установка GitLab Runner

Сам раннер ставится из официального репозитория GitLab. Подключите его и установите пакет:

curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | bash
apt install -y gitlab-runner

После установки раннер работает как системный сервис и стартует автоматически. Проверьте, что он запущен:

systemctl status gitlab-runner

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

Шаг 4. Регистрация раннера

Чтобы раннер начал получать задания, его нужно зарегистрировать в вашем проекте или группе GitLab. Токен регистрации берётся в настройках CI/CD проекта — раздел с раннерами. Запустите регистрацию и следуйте подсказкам:

gitlab-runner register

Мастер спросит адрес вашего GitLab, токен регистрации, описание раннера, теги и тип исполнителя. В качестве исполнителя укажите docker и задайте образ по умолчанию, из которого будут стартовать сборки без явного указания. Теги — важная деталь: они позволяют направлять конкретные задания на конкретные раннеры. Например, тег docker или build в задании подскажет GitLab, что его должен взять именно ваш раннер. После успешной регистрации раннер появится в настройках проекта как активный.

Шаг 5. Первый пайплайн

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

build:
  image: alpine:latest
  tags:
    - docker
  script:
    - echo "Раннер работает"
    - uname -a

Закоммитьте файл и запушьте в репозиторий. GitLab автоматически запустит пайплайн, а ваш раннер заберёт задание, стартует контейнер из указанного образа и выполнит команды. В интерфейсе GitLab, в разделе пайплайнов, вы увидите лог выполнения. Если задача прошла и в логе видны ваши строки — раннер, исполнитель и связь с GitLab настроены верно. С этого момента можно наполнять пайплайн реальными шагами: установка зависимостей, тесты, сборка, деплой.

Шаг 6. Оптимизация и обслуживание

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

Следите за диском — сборки оставляют образы и временные файлы, которые со временем забивают место. Настройте периодическую очистку неиспользуемых Docker-образов, иначе однажды пайплайны встанут из-за нехватки места. Проверьте, что раннер стартует после перезагрузки (он ставится в автозапуск по умолчанию, но лишняя проверка не помешает). Если сборки стали упираться в ресурсы и очередь растёт, это честный сигнал перейти на более мощный VPS — подобрать и оплатить его из России удобно у MAATRIX. Так свой раннер остаётся быстрым и предсказуемым помощником команды.

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