Установка и использование GitLab Runner

В современной разработке программного обеспечения ключевую роль играют автоматизация и непрерывная интеграция (CI/CD). Один из важнейших инструментов в этой области — GitLab Runner.

Что такое GitLab Runner

GitLab Runner — это сервис, который выполняет задания из CI/CD-пайплайнов в GitLab. Он получает задачи от GitLab, запускает их в нужной среде и возвращает результат: успешно, с ошибкой или с логами выполнения.

Всё актуальное — в наших соцсетях. Подписывайтесь!

Телеграм ВКонтакте

Runner не хранит код и не управляет репозиториями. Его задача — исполнение. Все, что описано в .gitlab-ci.yml(сборка, тесты, линтинг, деплой), фактически выполняется именно им.

GitLab Runner может работать на отдельном сервере, в виртуальной машине, контейнере или в Kubernetes-кластере. За счет этого легко масштабировать CI/CD: добавить еще раннеры под нагрузку, разделить задачи по типам или изолировать чувствительные процессы.

Основные возможности GitLab Runner:

• выполнение задач в изолированной среде;
• поддержка разных исполнителей: shell, Docker, Docker Compose, Kubernetes и других;
• параллельный запуск нескольких задач;
• гибкая привязка раннеров к конкретным проектам или группам;
• контроль ресурсов и окружения, в котором запускается код.

С точки зрения архитектуры GitLab Runner — это агент. Он сам подключается к GitLab, регулярно запрашивает новые задания и выполняет их от имени проекта. Благодаря этому GitLab не требует прямого доступа к серверам, где происходит сборка или деплой.

Без GitLab Runner CI/CD в GitLab существовать не может: пайплайн может быть описан, но без раннера он просто не будет запущен.

Типы раннеров

Есть два типа раннеров:

GitLab-hosted — это раннеры, которые полностью обслуживает GitLab. Они доступны пользователям GitLab.com и GitLab Dedicated и не требуют установки или администрирования.

Особенности GitLab-hosted:

• полностью управляются GitLab;
• готовы к работе сразу после создания проекта;
• каждая задача запускается в новой виртуальной машине;
• доступны окружения Linux, Windows и macOS;
• автоматически масштабируются под нагрузку.

Такие раннеры подходят, когда важен быстрый старт и минимальные затраты времени на поддержку. Они удобны для стандартных сборок, тестов и сценариев, где не требуется глубокая настройка окружения или доступ к внутренней инфраструктуре.

Self-managed — это раннеры, которые вы устанавливаете и обслуживаете самостоятельно. Их можно использовать в GitLab.com, GitLab Self-Managed и GitLab Dedicated.

Особенности self-managed раннеров:

• устанавливаются и настраиваются вручную;
• работают на вашей инфраструктуре;
• позволяют полностью контролировать окружение выполнения;
• поддерживают разных исполнителей: Shell, Docker, Kubernetes и так далее;
• могут быть привязаны к конкретному проекту, группе или всему инстансу.

Их выбирают, когда нужны нестандартные конфигурации, доступ к закрытой сети, повышенные требования к безопасности или оптимизация скорости за счет повторного использования окружений. Self-managed раннеры часто используют в корпоративных проектах и сложных CI/CD-процессах.

Подготовка к установке

Перед установкой GitLab Runner важно правильно подготовить сервер. От этого зависит стабильность CI/CD, скорость выполнения задач и безопасность всей инфраструктуры. На практике Runner чаще всего разворачивают не на локальной машине, а на отдельном сервере — так проще управлять нагрузкой и изоляцией.

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

Облачные серверы Рег.облака созданы для эффективной разработки и хостинга: вы получаете выделенный CPU, быстрые диски SSD/NVMe, защиту от DDoS‑атак до 1,5 Tbps (L3/L4) и высокоскоростное подключение (1 Гбит/с внутри приватной сети, 350 Мбит/с в интернет). Управление сервером максимально упрощено — все операции (апгрейд, перезагрузка, остановка) доступны через API, а развертывание занимает всего 1-2 минуты. Приватная сеть с скоростью 10 Гбит/с позволяет строить кластеры и размещать базы данных на отдельных серверах, а почасовая оплата делает решение экономичным даже для краткосрочных задач.

Установка GitLab Runner

GitLab Runner можно установить разными способами — на Linux или Windows, через репозитории, пакеты или отдельный бинарник. Конкретный вариант зависит от операционной системы, требований к безопасности и того, где именно будет работать Runner: на отдельном сервере, в облаке или внутри контейнера.

В этом разделе разберем основные варианты установки GitLab Runner и покажем, как подготовить систему так, чтобы Runner работал стабильно и без лишних проблем.

Linux

1. Откройте индекс доступных пакетов. Все актуальные версии и архитектуры можно посмотреть по ссылке.
2. Определите архитектуру системы. Она нужна, чтобы правильно указать ${arch} в имени пакета.

Debian / Ubuntu:

CentOS / RHEL:

Чаще всего это amd64 или arm64.

3. Скачайте пакеты GitLab Runner.

Debian / Ubuntu:

CentOS / RHEL:

Где замените ${arch} на amd64, arm или arm64.

4. Установите пакеты.

Debian / Ubuntu:

Если появятся ошибки зависимостей, выполните:

CentOS / RHEL:

5. Проверьте установку:

6. Запустите и включите автозапуск

На этом установка завершена. Далее Runner нужно зарегистрировать в GitLab и выбрать исполнителя.

Windows

Важно! Убедитесь, что до установки GitLab Runner у вас установлен Git.

1. Создайте каталог для Runner. Например, C:\GitLab-Runner.
2. Скачайте бинарный файл GitLab Runner из официального хранилища GitLab для 32- или 64-битной системы.
3. Скачанный файл положите в каталог, созданный на первом шаге. До этого его можно переименовать в gitlab-runner.exe — так будет проще работать.

4. Ограничьте права на каталог и исполняемый файл. Откройте командную строку с правами администратора.
5. Установите и запустите Runner:

Регистрация раннера

GitLab Runner сам по себе ничего не делает — его нужно зарегистрировать. Регистрация нужна, чтобы связать конкретный Runner с GitLab: объяснить, какие проекты он обслуживает, какие задания может выполнять и в каком окружении. Без регистрации Runner не получает задачи из CI/CD и остается просто сервисом в системе.

При регистрации все настройки сохраняются в файл config.toml. В дальнейшем GitLab использует его, чтобы отправлять задания именно этому Runner.

Linux

1. Получите токен аутентификации раннера. Его можно создать в GitLab при добавлении раннера. В интерфейсе он отображается как строка с префиксом glrt-. Этот токен используется именно для регистрации Runner, а не для запуска задач.

2. Запустите команду регистрации. На Linux регистрация выполняется от имени пользователя с правами администратора:

Если Runner должен выходить в интернет через proxy, сначала задайте переменные окружения и передайте их команде:

3. Укажите адрес GitLab:
   • для GitLab.com — https://gitlab.com;
   • для self-managed — адрес вашего сервера, например https://gitlab.example.com.

4. Введите токен аутентификации раннера. По нему GitLab определяет, к какому уровню относится Runner: проект, группа или весь инстанс.
5. Задайте описание раннера. Это произвольный текст, который отображается в интерфейсе GitLab. Обычно указывают назначение и окружение, например: linux-docker-runner или prod-shell-runner.
6. Укажите теги для заданий. Их нужно вводить через запятую. GitLab будет отправлять задания на этот Runner только в том случае, если теги совпадают с тегами задания в .gitlab-ci.yml.
7. Опционально: добавьте maintenance note. Это служебная заметка для администраторов. Ее удобно использовать для описания ограничений или особенностей Runner.
8. Выберите тип исполнителя:

• shell;
• docker;
• docker+machine;
• kubernetes;
• другие варианты.

9. После ответа на все вопросы Runner сохраняет конфигурацию в config.toml.

С этого момента GitLab Runner считается зарегистрированным и может принимать задания.

Windows

Перед регистрацией у вас должен быть токен аутентификации раннера. Его можно получить двумя способами:

• создать instance-, group- или project-раннер в интерфейсе GitLab;
• использовать уже существующий токен из файла config.toml.

Токен всегда начинается с префикса glrt-.

1. Запустите команду регистрации:

2. Укажите адрес GitLab:
   • для GitLab.com — https://gitlab.com;
   • для self-managed — адрес вашего сервера, например https://gitlab.example.com.

3. Вставьте токен с префиксом glrt-. По нему GitLab определяет, где именно будет использоваться этот раннер.
4. Укажите описание раннера. Это имя, которое будет отображаться в интерфейсе GitLab. Как правило, в него записывают назначение или окружение, например:

5. Задайте теги заданий. Их нужно прописать через запятую. GitLab будет отправлять задания на раннер только при совпадении тегов в .gitlab-ci.yml.
6. Опционально: добавьте maintenance note — это служебная заметка для администраторов. Ее удобно использовать, чтобы указать ограничения, окружение или особые условия работы раннера.
7. Выберите тип исполнителя:

• shell;
• docker;
• kubernetes;
• другие поддерживаемые варианты.

8. Завершите регистрацию. После ответов на все вопросы GitLab Runner сохранит настройки в config.toml и будет готов принимать задания из CI/CD.

Выбор исполнителя для выполнения заданий

От исполнителя зависит, где и как GitLab Runner будет выполнять CI/CD‑задания: какая ОС будет использоваться, как будут изолированы процессы, какие ресурсы доступны и какой уровень безопасности применен. Это напрямую влияет на работу пайплайна.

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

Выбор исполнителя всегда привязан к задачам и окружению. Например, если задания должны выполнять PowerShell-команды, логично установить Runner на Windows и использовать shell-исполнитель — команды будут запускаться напрямую в системе. Если требуется запускать сборки и тесты в изолированном окружении с заранее подготовленными зависимостями, обычно выбирают Docker-исполнитель и регистрируют Runner на Linux-сервере. В этом случае каждое задание выполняется внутри контейнера.

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

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

Билды и задачи

В контексте CI/CD в GitLab часто используют два термина — билды и задачи. Они связаны между собой, но обозначают разные уровни выполнения пайплайна.

Задача (job) — это минимальная единица работы в CI/CD. Она описывается в .gitlab-ci.yml и содержит конкретные инструкции: какие команды выполнить, в каком окружении, с какими условиями запуска. Задача всегда выполняется одним раннером и одним исполнителем.

Билд (build) — это результат выполнения задачи. Когда GitLab отправляет задачу раннеру, тот запускает ее, а процесс выполнения и его итог называют билдом. У билда есть статус (успешно, ошибка, отменен), логи, артефакты и время выполнения.

Одна и та же задача может запускаться много раз: после коммита, при запросе на слияние или по ручному запуску пайплайна. Каждый запуск создает отдельный билд, у которого есть своя история и свои результаты. Раннеры отвечают за выполнение этих билдов, тогда как задачи содержат инструкции о том, какие действия и в какой последовательности необходимо выполнить.

Артефакты и кэши, создаваемые в процессе CI/CD, занимают место и требуют надёжного хранения. Используйте объектное хранилище Рег.облако, совместимое с S3, для централизованного хранения результатов сборок, отчётов тестирования и зависимостей. Это разгрузит раннер и обеспечит доступность артефактов даже при переустановке сервера.

Тестирование

Тестирование в GitLab CI/CD — это проверка кода на ошибки. Она проходит автоматически после сборки (или одновременно с ней) и помогает выявить проблемы до выпуска кода в продакшен.

Тесты описываются в виде задач в .gitlab-ci.yml. Это могут быть юнит-тесты, интеграционные тесты, end-to-end сценарии, проверки стиля кода или статический анализ. GitLab не навязывает формат — раннер просто выполняет команды, которые вы указали.

Каждый запуск тестов — отдельный билд. Runner берет задачу, создает нужное окружение и запускает тесты. GitLab сохраняет статус, логи и артефакты — например, отчеты, скриншоты и дампы ошибок.
Почему автотесты полезны? Они:

• быстро показывает, что сломалось и на каком этапе;
• служат фильтром для основной ветки — не пропускают битый код;
• гарантируют одинаковые результаты вне зависимости от окружения и пользователя;
• упрощают код-ревью, потому что базовые проверки уже выполнены.

Запуск тестов настраивается под нужды проекта: можно делать это при каждом коммите, при запросе на слияние или вручную. Главное — процесс автоматизирован и воспроизводим.

Допустим, проект написан на Python и использует pytest. Простейший этап тестирования в .gitlab-ci.yml может выглядеть так:

Где:

• GitLab Runner запускает задачу на этапе test;
• используется Docker-образ с Python 3.12;
• устанавливаются зависимости проекта;
• запускаются тесты через pytest.

Если хотя бы один тест завершится с ошибкой, билд получит статус failed, и пайплайн остановится. Если все тесты пройдут успешно, GitLab пометит этап как выполненный, и пайплайн продолжится дальше.

Безопасность

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

Основные моменты, на которые стоит обратить внимание:

• Изоляция выполнения. Используйте исполнители с изоляцией, такие как Docker или Kubernetes. Они ограничивают влияние задач на хост-систему. Shell-исполнитель запускает команды напрямую и подходит только для контролируемых окружений.
• Минимальные права. Раннер должен работать под отдельной учетной записью без расширенных привилегий. Избыточные права увеличивают риск компрометации системы.
• Разграничение доступа к раннерам. Привязывайте раннеры к проектам или группам, а не ко всему инстансу, если это возможно.
• Работа с секретами. Токены, пароли и ключи передавайте через защищенные переменные GitLab. Не храните секреты в репозитории и не выводите их в логи.
• Контроль тегов. Используйте теги заданий, чтобы явно указывать, какие пайплайны могут запускаться на конкретном раннере.
• Регулярные обновления. Обновляйте GitLab Runner, образы контейнеров и базовую систему. Старые версии часто содержат известные уязвимости.
• Мониторинг и логи. Проверяйте логи выполнения заданий и состояние раннеров.

Для проектов с ресурсоёмкими сборками (компиляция больших кодовых баз, тяжёлые тесты, работа с GPU) или с высокими требованиями к безопасности обычные виртуальные серверы могут не подойти. Выделенные серверы Рег.облако дают доступ ко всем мощностям физического сервера: вы выбираете конфигурацию CPU, GPU, RAM и дисков, а также получаете полный контроль над аппаратным обеспечением. Это гарантирует стабильную производительность и отсутствие "соседей" даже при максимальной загрузке CI/CD.

Заключение

В этой статье мы разобрали, что такое GitLab Runner, как и где его можно установить, чем отличаются типы раннеров и исполнители, и зачем нужна регистрация.

Runner запускает билды, тесты и деплой автоматически, освобождая команду от рутины и повышая качество кода. Грамотная настройка раннера помогает внедрить CI/CD без риска для инфраструктуры и сделать процесс разработки более прозрачным и быстрым.

Блок FAQ

Что такое GitLab Runner и зачем он нужен?

GitLab Runner — это исполнитель CI/CD-пайплайнов в GitLab. Он получает задания из GitLab, запускает их в заданном окружении и возвращает результат выполнения: статус, логи и артефакты.

Он нужен, чтобы код не просто хранился в репозитории, а автоматически собирался, тестировался и разворачивался.

Где можно установить Runner?

GitLab Runner можно установить практически в любом окружении, где есть доступ к выполнению команд:

• на физическом сервере;
• на виртуальной машине;
• в облаке;
• в контейнере Docker;
• в кластере Kubernetes;
• на Linux, Windows и macOS.

Как зарегистрировать Runner?

Чтобы зарегистрировать GitLab Runner, нужно связать установленный раннер с GitLab с помощью токена аутентификации раннера.

Что такое shared и specific Runner?

Shared Runner и specific Runner — это способы, как GitLab распределяет CI/CD-задания между раннерами.

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

Specific Runner — раннер, который привязан к конкретному проекту или группе.
Он выполняет задания только от тех проектов, для которых был зарегистрирован. Это позволяет точно контролировать окружение, ресурсы, безопасность и нагрузку.

Как обеспечить безопасность Runner?

Есть несколько советов:

• Выбирайте изолированный исполнитель (Docker или Kubernetes), а shell используйте только в контролируемой среде.
• Запускайте Runner с минимальными правами.
• Ограничивайте, кто может пользоваться раннером.
• Секреты храните только в защищенных переменных GitLab и следите, чтобы они не попадали в логи.
• Регулярно обновляйте Runner, ОС и образы контейнеров.
• Держите раннер в отдельной зоне: по возможности без прямого доступа ко всей внутренней сети и критичным сервисам.

Можно ли запускать несколько Runner на одном сервере?

Да, на одном сервере можно запустить сразу несколько GitLab Runner. Главное — зарегистрировать каждый по отдельности. У всех будет свой файл настроек config.toml, так что они будут работать независимо.

Как обновить GitLab Runner?

Обновление GitLab Runner зависит от способа установки:

Через официальный репозиторий GitLab (Linux)

Достаточно обновить пакеты стандартным менеджером:

Debian / Ubuntu:

RHEL / CentOS / Fedora:

Runner обновится вместе с системой.

Через deb/rpm-пакеты вручную (Linux)

Скачайте новые версии пакетов из официального хранилища и установите их поверх старых. Конфигурация в config.toml при этом сохраняется.

Windows

Остановите сервис Runner, замените файл gitlab-runner.exe на новую версию и снова запустите сервис. Регистрация и настройки сохраняются.

Можно ли масштабировать Runner?

Да, масштабировать GitLab Runner можно.

Есть несколько способов:

• Добавить больше раннеров — можно установить и зарегистрировать дополнительные раннеры на других серверах или в облаке. GitLab сам будет распределять задания между всеми доступными исполнителями.
• Настроить параллельность — в файле config.toml параметр concurrent задает, сколько задач один раннер может выполнять одновременно. Можно увеличить это значение, если ресурсы сервера позволяют.
• Использовать автоскейлинг — для Docker Machine или Kubernetes-исполнителей доступен режим, при котором Runner сам поднимает и удаляет новые экземпляры по мере появления или завершения заданий.
• Shared runners на GitLab.com — если вы используете GitLab SaaS, масштабированием общих раннеров занимается сама платформа.
• Масштабирование позволяет ускорить выполнение пайплайнов, справляться с ростом задач и гибко управлять нагрузкой.