Настройка GitLab CI/CD: понимаем принципы работы и запускаем первый pipeline

Все найденные мной русскоязычные гайды не дают базового понимания того, как это работает, по большому счету это просто инструкции по настройке, причем под какой-то конкретный продукт и кейс: .net, Java, Node JS, etc.

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

• Максимально много функционала, которыми обладает Gitlab (общие абстракции актуальны и для его аналогов).

• Инструменты которые нужны: Bash, Docker, Kubernetes и другие.

• Общую теорию и практику с конкретными сценариями.

Материал разбит на 3 части.

1. [Вы здесь → ] Простейший пример ci-cd

2. [in progress 80%] Более зрелый CI/CD (выход в продакшн, self-hosted runner и работа с registry)

3. [todo] Горизонтальное масштабирование CI/CD (высоко-нагруженный продакшн)

Оглавление

• В чем идея CI/CD?

• Терминология

• Простейший CI/CD (разработка, MVP)

  • Простой пример .gitlab-ci.yml

  • Схема работы простейшего CI/CD

  • Практика с простейшим шаблоном CI/CD

В чем идея CI/CD

Даже начинающему разработку интуитивно понятно что такое CI/CD и для чего оно нужно. Отправили коммиты с изменениями в репозиторий — нужно исходный код превратить в собранное приложение и развернуть его на dev/test/prod стенде. Можно зайти на VPS и все сделать вручную: git clone, запустить автотесты, сделать сборку и запустить собранное приложение, при этом старое запущенное приложение, нужно заменить новым билдом. Автоматизацию этого процесса и назвали CI/CD. В эту аббревиатуру навалили сразу несколько значений которые всегда делаются рядом друг с другом и часто эти действия трудно однозначно классифицировать.

Но я все же попробую классифицировать и достичь какой-то однозначности по терминологии.

Терминология

CI (continues integration, непрерывная интеграция) — действия необходимые для интеграции новых изменений в имеющуюся кодовую базу.

Continues integration включает в себя следующее:

• объедение всех изменений в одну точку

• установку зависимостей

• статистические проверки кода (типизация, линтеры)

• запуск тестов (Unit, интеграционные, e2e)

• проверка работоспособности сборки (убедиться что сборка возможна)

• сборка кодовой базы. Это может быть как сборка библиотеки в соответствующий формат (например, npm-модуль, PyPI-пакет, Go-модуль), так и сборка в конечный исполняемый формат (.jar, .whl, bundle, Docker-контейнер, .exe-файл и т. д.) Результат сборки принято называть артефактом.

• загрузка артефакта в специализированное хранилище для дальнейшего использования и версионирования. Такие хранилища часто называют registry (npm registry, Docker Registry, PyPI) или hub (Docker Hub), а также repository manager (Nexus, Artifactory, GitHub Packages).

CD (continues delivery, непрерывная доставка) — действия необходимые для доставки артефакта в место назначения (сервер где он будет выполняться). На этом этапе определяется куда будет доставлен артефакт, на dev, test, pre-prod(stage), prod.

Continues delivery включает в себя следующее:

• Получение артефакта на целевом сервере

CD (continues deployment, непрерывное развертывание) — Действия необходимые для запуска уже доставленного артефакта.

Continues deployment включает в себя следующее:

• Запуск артефакта

• Миграция БД (если наш артефакт ее использует)

• Запуск e2e тестов. Именно тех чья функция заключается в том, что бы проверить целостность работы системы. Некоторые e2e могли быть запущены еще на этапе CI.

• Тут может быть так же механизм отката к предыдущей версии.

Delivery и Deployment на практике часто смешивается в одно целое “доставили и сразу запустили”. А если приблизиться к реальности еще больше и отдалиться от академических определений — часто на практике все 3 части смешиваются в один большой конвеер который и называется единым словом CI/CD или CICD. Таким образом, на практике все может быть свалено в одну большую кучу и например запуск тестов или миграций можно встретить совсем не в той последовательности, которая встречается в учебниках и теоритических статьях.

Pipeline (пайплайн) — это цепочка всех шагов необходимых для реализации CI/CD, каждый шаг это stage (стадия, этап), внутри каждого stage запускаются jobs (джобы, задачи). Если один этап падает, дальнейшие шаги отменяются. Дословно с английского переводиться как “трубопровод”, соответственно для носителя языка это ассоциируется с каким-то промышленным трубопроводом, который построен с целью доставки чего-то из точки A в точку B.

Stage (стадия, этап) — группа конкретных действий (джобов) из которых состоит пайплайн.

job (джоба) — конкретное действие или скрипт.

Runner (раннер) GitLab — runner выполняет джобы в пайплайне. Runner умеет выполнять джобы параллельно друг другу, использовать разные экзекьютеры (executors). Раннер можно установить отдельно на вашу машину и тогда gitlab будет просить его выполнять все инструкции.

Executor (экзекьютер) — способ выполнения скриптов описанных в джобах, например может работать в docker или сразу на целевой машине в bash.

Более детально и схематично каждый термин будет описан дальше в статье.

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

Простейший CI/CD (разработка, MVP)

В этом разделе рассмотрим конфигурацию и схему простой реализации CI/CD которая подойдет на этапе разработки или MVP.

Простой пример .gitlab-ci.yml

Все начинается с репозитория, а точнее с описанного в нем файла .gitlab-ci.yml (документация GitLab по gitlab-ci.yml). Этот файл содержит все инструкции, которые нужно выполнить для целей CI/CD.

Рассмотрим простейший пример, который GitLab предлагает в качестве стартового шаблона .gitlab-ci.yml:

Вместо реальных запусков тестов используется команда echo, которая просто выводит сообщение в консоль, а также команда sleep, которая создает искусственную задержку.

stages:          # Список stages (стадий) для jobs и порядок их выполнения
  - build
  - test
  - deploy

build-job:       # Джоба build, выполняемая в первую очередь
  stage: build
  script:
    - echo "Compiling the code..."
    - echo "Compile complete."

unit-test-job:   # Запуск тестов
  stage: test    # Запустится только если build прошел успешно
  script:
    - echo "Имитация запуска unit-тестов... с задержкой 60 секунд"
    - sleep 60
    - echo "Покрытие кода в районе 90%"

lint-test-job:   # Еще одна джоба, которая относится к стадии "test"
  stage: test    # Так как она тоже относится к стадии "test", будет запущена параллельно
  script:
    - echo "Проверка кода линтером... Задержка 10 секунд."
    - sleep 10
    - echo "Нет ошибок линтера."

deploy-job:      # Само развертывание (deploy)
  stage: deploy  # Запустится только если все джобы из стадии "test" завершились успешно
  environment: production
  script:
    - echo "Развертывание приложения..."
    - echo "Приложение развернуто."

Когда GitLab отслеживает изменение в репозитории, он передает инструкции из .gitlab-ci.yml раннеру. Раннер, в свою очередь, использует указанный executor для выполнения команд. Подробнее о поддерживаемых executors — в документации GitLab.

Runner (раннер) GitLab — это программа, которая выполняет инструкции в указанном окружении. Executor определяет, в каком именно окружении будут выполнены команды. Так как в примере используются только базовые утилиты echo и sleep, подойдет практически любой executor:

• Docker — каждая джоба запускается в изолированном Docker-контейнере на основе указанного образа.

• Shell — команды выполняются напрямую в оболочке хост-системы, где установлен раннер.

• Kubernetes — джобы выполняются в подах кластера Kubernetes.

• SSH — команды выполняются на удаленной машине через SSH-соединение.

Для большинства реальных проектов рекомендуется использовать Docker, так как он обеспечивает изоляцию и воспроизводимость окружения.

Если вы используете не Self Hosted Gitlab (который поднят в вашей инфраструктуре), а GitLab.com (SaaS-инстанс) по умолчанию будет использован shared runners, который в стандартной конфигурации использует Docker executor — каждая джоба запускается в изолированном контейнере.

Схема работы простейшего CI/CD

Схема на примере когда:

• Используется gitlab.com (не self hosted)

• Runner установлен на вашем сервере

• Используется docker executor

• Используется вышеописанный шаблон .gitlab-ci.yml (4 джобы)

Если build-job создает какой-то артефакт, его можно расположить в каком-то хранилище. Если довольствоваться самой простой и быстрой реализацией, можно исключить работу с registry (хранилищем артефактов). Часто на начальных этапах разработки так и поступают, вместо дополнительных действий с registry происходит следующее: раннер поднимает контейнер в котором происходит подключение по SSH к целевому серверу, на целевом сервере уже установлен docker и git, по этому в рамках подключения SSH достаточно сделать git pull, docker run, а старый контейнер просто гасят. Это работает когда в репозитории разработчика есть Dockerfile который делает все необходимое для запуска приложения: установка зависимостей, сборка и запуск.

Но этот сценарий имеет сразу множество недостатков и подходит для этапа разработки или MVP, но не для поддержки серьезного продакшена. Недостатки такого подхода по пунктам:

• Downtime — нужно положить старый контейнер, поднять новый, приложение недоступно пока происходит сборка нового контейнера.

• Сборка нагружает production сервер

• Нет истории артефактов, нет возможности откатиться к прошлому артефакту, если с новым что-то пошло не так.

• Не подходит для горизонтального масштабирования.

• Уязвимая инфраструктура — доступ к серверу прода попадает в gitlab (ssh ключи), а на сервере прода есть доступ к репозиторию.

• Исходный код присутствует на сервере прода.

• Docker хранит свои слои и кэш на сервере прода.

При этом у многих такой подход живет в проде и ничего страшного не случается (до поры до времени).

Практика с простейшим шаблоном CI/CD

Закоммитим и запушим данный .gitlab-ci.yml файл gitlab и посмотрим что произойдет.

При просмотре пайплайна, gitlab визуализирует наши stages и jobs. Всего у нас 4 джобы. 2 параллельных lint-test-job и unit-test-job они находятся в стадии test. Перейдем в unit-test-job и посмотрим что gitlab нам отобразит:

В .gitlab-ci.yml это описано так:

unit-test-job:   # Запуск тестов
  stage: test    # Запустится только если build прошел успешно
  script:
    - echo "Имитация запуска unit-тестов... с задержкой 60 секунд"
    - sleep 60
    - echo "Покрытие кода в районе 90%"

Всего 3 команды, но в логах мы видим много всего. По этому разберем каждую строчку для лучшего понимания.

Running with gitlab-runner 18.10.0~pre.705.ge11dde90 (e11dde90)
  on green-4.saas-linux-small-amd64.runners-manager.gitlab.com/default ntHFEtyXQ, system ID: s_8990de21c550
  feature flags: FF_USE_GIT_PROACTIVE_AUTH:true

Running with gitlab-runner 18.10.0~pre.705.ge11dde90 (e11dde90)

on green-4.saas-linux-small-amd64.runners-manager.gitlab.com/default ntHFEtyXQ

Нам сообщается версия runner’а который занимался выполнением джобы. Я не нашел прямой ссылки для перехода к нему, по этому просто подставил в url его номер, так мне удалось просмотреть информацию о нем.

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

Двигаемся по логам дальше и видим:

Preparing the "docker+machine" executor
Using default image
Using Docker executor with image ruby:3.1 ...
Using default image
Using effective pull policy of [always] for container ruby:3.1
Pulling docker image ruby:3.1 ...
Using docker image sha256:9981... for ruby:3.1 with digest ruby@sha256:9162...

Preparing the "docker+machine" executor

Using default image
Using Docker executor with image ruby:3.1 ...

Using effective pull policy of [always] for container ruby:3.1

Pulling docker image ruby:3.1
Using docker image sha256:9981... for ruby:3.1 with digest ruby@sha256:9162...

Нам говориться о подготовке экзекьютора и загрузке docker образа. Читаем дальше:

Preparing environment
Using effective pull policy of [always] for container sha256:c11...
Running on runner-nthfetyxq-project-79632759-concurrent-0 via runner-nthfetyxq-s-l-s-amd64-1775396763-e03183f3...
Getting source from Git repository
Gitaly correlation ID: 73b6c9732c8240b7b5a1937a1eaac112
Fetching changes with git depth set to 20...
Initialized empty Git repository in /builds/webstap/self-server-config/.git/
Created fresh repository.
Checking out 3575359a as detached HEAD (ref is main)...
Skipping Git submodules setup
$ git remote set-url origin "${CI_REPOSITORY_URL}" || echo 'Not a git repository; skipping'

Preparing environment
Using effective pull policy of [always] for container sha256:c11...

Running on runner-nthfetyxq-project-79632759-concurrent-0 via runner-nthfetyxq-s-l-s-amd64-1775396763-e03183f3...

runner-nthfetyxq-project-79632759-concurrent-0
       │                 │                   │
       │                 │                   └─ Слот конкурентности (первый из N)
       │                 └─ ID проекта в GitLab
       └─ Токен/ID раннера (короткий хеш)

via runner-nthfetyxq-s-l-s-amd64-1775396763-e03183f3
           │         │ │ │  │        │      │
           │         │ │ │  │        │      └─ ID инстанса (VM)
           │         │ │ │  │        └─ Похоже на Timestamp или порядковый номер
           │         │ │ │  └─ Архитектура: amd64
           │         s-l-s = shared/linux/small (тип машины)
           └─  Токен/ID раннера (короткий хеш)

Gitaly correlation ID: 73b6c9732c8240b7b5a1937a1eaac112

Fetching changes with git depth set to 20...

git init
git remote add <наш репозиторий>
git fetch origin --depth 20 

Initialized empty Git repository in /builds/webstap/self-server-config/.git/
Created fresh repository.

Checking out 3575359a as detached HEAD (ref is main)...

Skipping Git submodules setup

git remote set-url origin "${CI_REPOSITORY_URL}" || echo 'Not a git repository; skipping'

https://gitlab-ci-token:$CI_JOB_TOKEN@gitlab.example.com/my-group/my-project.git

|| echo 'Not a git repository; skipping

GitLab Runner на виртуальной машине скачал два Docker-образа — ruby:3.1 для выполнения пользовательского кода и gitlab-runner-helper для служебных операций, затем helper-контейнер склонировал Git-репозиторий webstap/self-server-config (shallow clone, глубина 20 коммитов) в директорию /builds/webstap/self-server-config, переключился на конкретный коммит 3575359a из ветки main и подготовил рабочую среду для выполнения скриптов из .gitlab-ci.yml.

Осталось разобрать последнюю часть:

Executing "step_script" stage of the job script
Using default image
Using effective pull policy of [always] for container ruby:3.1
Using docker image sha256:9981... for ruby:3.1 with digest ruby@sha256:916... ...
$ echo "Имитация запуска unit-тестов... с задержкой 60 секунд"
Имитация запуска unit-тестов... с задержкой 60 секунд
$ sleep 60
$ echo "Покрытие кода в районе 90%"
Покрытие кода в районе 90%
Cleaning up project directory and file based variables
Job succeeded

Using default image
Using effective pull policy of [always] for container ruby:3.1
Using docker image sha256:9981... for ruby:3.1 with digest ruby@sha256:916... ...

$ echo "Имитация запуска unit-тестов... с задержкой 60 секунд"

Имитация запуска unit-тестов... с задержкой 60 секунд

$ sleep 60
$ echo "Покрытие кода в районе 90%"
Покрытие кода в районе 90%

Cleaning up project directory and file based variables
Job succeeded

Job succeeded

Выполнен блок script из .gitlab-ci.yml джобы unit-test-job:

unit-test-job:   # Запуск тестов
  stage: test    # Запустится только если build прошел успешно
  script:
    - echo "Имитация запуска unit-тестов... с задержкой 60 секунд"
    - sleep 60
    - echo "Покрытие кода в районе 90%"

Ранее мы говорили об артефактах, в результате выполнения пайплайнов мы не создавали артефакты в скриптах наших джобов, но все же некоторые файлы были созданы и размещены в хранилище артефактов gitlab. Речь идет о файлах с логами. Просмотреть их можно если перейти в Build → Artifacts.

Мы рассмотрели как себя ведет шаблон CI-CD предложенный gitlab. Данную реализацию можно доработать таким образом, что одна из наших джобов подключалась через SSH к нашему VPS, заходила в определенную директорию, обновляла git репозиторий и поднимала контейнер. Но как я уже писал: у этого есть ряд недостатков.

Спасибо, что дочитали! Тем, кто уже подписан на мой телеграм-канал — отдельная благодарность, это мотивирует делиться опытом дальше. Остальным — заходите, помимо технических статей поднимаю и социально важные темы.