Кто на самом деле выполняет команды из .gitlab-ci.yml? Не сам GitLab: он хранит описание конвейера, раздаёт работу и показывает результат, но ни одной команды не запускает. Это делает GitLab Runner — отдельная программа на какой-то машине. Пока раннера нет, конвейер стоит, сколько бы задач в нём ни было, поэтому без этого урока ни одна следующая практика не заработает.
Раннер написан на Go, ставится пакетом или запускается контейнером gitlab/gitlab-runner, и одна его копия может обслуживать много проектов. С GitLab они в тех же отношениях, что диспетчер такси с водителем: диспетчер принимает заказы, но за руль не садится, а водитель сам выходит на линию и спрашивает «есть заказ?». Отсюда главное свойство раннера: команды выполняются в предсказуемом окружении и там, где они нужны, например рядом с твоим стендом.
Как раннер получает работу
Раннер раз в несколько секунд сам обращается к GitLab по его адресу (external_url) и спрашивает, нет ли задач для него. Получил — выполнил, отправил журнал и результат обратно.
Из направления соединения следует удобная вещь: раннер может стоять за домашним роутером или в закрытой сети, и ему не нужны входящие порты. Нужно только, чтобы он видел GitLab.
Задача без подходящего раннера не падает, а висит в статусе pending с подписью «This job is stuck». Это первая типичная грабля: конвейер «не запускается», а на деле его просто некому выполнить.
Исполнители
Раннер сам задачу не выполняет — он поручает её исполнителю (executor). Исполнитель определяет, где именно пойдут команды. Тебе нужны два:
Есть и другие — kubernetes (каждая задача в поде кластера), ssh, virtualbox, — но в первый месяц работы ты увидишь именно эти два. Мы возьмём docker: он изолирует задачи друг от друга и каждый раз начинает с чистого листа.
Для сборки образов внутри задачи нужен Docker, а внутри контейнера задачи его нет. Самый простой выход — пробросить в контейнер задачи сокет Docker с хоста, /var/run/docker.sock: это файл-дверь, через который программа docker разговаривает с демоном. Тогда команда docker build в задаче на деле выполняется демоном стенда.
Удобство стоит дорого: доступ к сокету — это фактически root на машине. Любая задача сможет запустить любой контейнер с любыми томами. На учебном стенде это приемлемо, на рабочем сервере для сборки берут отдельную машину или инструменты без демона — Kaniko, Buildah.
Только раннер с любым исполнителем ничего не выполнит, пока GitLab ему не доверяет: случайная программа не должна забирать задачи с секретами твоего проекта.
Регистрация по токену
Чтобы раннер начал брать задачи, его регистрируют. С GitLab 16 способ такой: сначала раннер создают в интерфейсе — в проекте Settings → CI/CD → Runners → New project runner. Там же задают теги и галочку «брать задачи без тегов». GitLab в ответ показывает токен с префиксом glrt- — один раз, потом его не посмотреть.
Затем на машине раннера запускают gitlab-runner register и отдают ему адрес GitLab, этот токен и тип исполнителя. Раннер записывает всё в файл config.toml и выходит на линию. В интерфейсе рядом с раннером загорается зелёный кружок — он на связи.
В старых статьях ты встретишь другой способ: один общий registration token проекта, который вставляли в команду. Он устарел, с GitLab 18 выключен по умолчанию, и пользоваться им не надо.
Теги — метки раннера, по которым задача выбирает исполнителя. Задача с tags: [docker] пойдёт только к раннеру с таким тегом. Если раннеру не разрешено брать задачи без тегов, а у задачи тегов нет, она повиснет в pending — вторая типичная грабля.
Раннеры бывают трёх уровней: проекта (обслуживает один проект), группы (все проекты группы) и инстанса (весь GitLab, создаёт администратор). На стенде хватит раннера проекта.
Словарь урока
Что спросят на собеседовании
- Конвейер завис в pending. Что проверить?Есть ли раннер на связи для этого проекта, совпадают ли теги задачи и раннера, разрешено ли раннеру брать задачи без тегов. Чаще всего дело в тегах.
- Чем опасен проброс docker.sock в задачи?Доступ к сокету равен root на машине: задача может запустить любой контейнер с любым томом. Сборочный раннер держат на отдельной машине или собирают через Kaniko и Buildah.
Что дальше
Дальше — поднять раннер рядом с GitLab и зарегистрировать его по токену.