Общие шаблоны GitLab

Все сервисы наследуют поведение CI/CD от двух общих шаблонов, поддерживаемых в репозитории meduza/infra. Эта страница подробно описывает каждый шаблон и объясняет, как расширять их в вашем сервисе.

Подключение шаблонов

Каждый .gitlab-ci.yml сервиса начинается с подключения общих определений:

include:
  - project: 'meduza/infra'
    file:
      - '.gitlab/ci/docker-build.yml'
      - '.gitlab/ci/nomad-deploy.yml'

Это делает скрытые задачи .docker_build и .nomad_deploy доступными для наследования в вашем пайплайне.

---

Шаблон .docker_build

Расположение: .gitlab/ci/docker-build.yml

Этот шаблон отвечает за сборку Docker-образа и его отправку в контейнерный реестр.

Исходный код шаблона

.docker_build:
  stage: build
  image: docker:24
  services:
    - docker:24-dind
  before_script:
    - docker login $REGISTRY_HOST -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD
  script:
    - cd ${SERVICE_DIR}
    - >-
      docker build ${BUILD_ARGS}
      --platform linux/amd64
      -t $REGISTRY_IMAGE/${SERVICE_NAME}:$CI_COMMIT_SHORT_SHA .
    - docker push $REGISTRY_IMAGE/${SERVICE_NAME}:$CI_COMMIT_SHORT_SHA
    - # Tags as prod/stage/dev based on branch

Переменные

Переменная	Обязательна	Описание
SERVICE_NAME	Да	Имя, используемое в пути образа (например, backend, frontend).
SERVICE_DIR	Да	Подкаталог с Dockerfile относительно корня репозитория.
BUILD_ARGS	Нет	Дополнительные аргументы для docker build (например, --build-arg VITE_API_URL=...).
REGISTRY_HOST	Авто	Устанавливается GitLab; указывает на gitlab.amzgit.com:5050.
REGISTRY_IMAGE	Авто	Устанавливается GitLab; полный путь реестра для проекта.
CI_REGISTRY_USER	Авто	Учётные данные GitLab для реестра контейнеров.
CI_REGISTRY_PASSWORD	Авто	Учётные данные GitLab для реестра контейнеров.
CI_COMMIT_SHORT_SHA	Авто	Первые 8 символов хеша коммита, используемые как тег образа.

Автоматические переменные

Переменные с пометкой Авто предоставляются GitLab CI и не требуют ручной настройки. Вам нужно определить только SERVICE_NAME, SERVICE_DIR и, при необходимости, BUILD_ARGS.

Как наследовать

build:backend:
  extends: .docker_build
  variables:
    SERVICE_NAME: backend
    SERVICE_DIR: back

build:frontend:
  extends: .docker_build
  variables:
    SERVICE_NAME: frontend
    SERVICE_DIR: front
    BUILD_ARGS: "--build-arg VITE_API_URL=https://api.amzhub.ai"

Каждый блок extends создаёт конкретную CI-задачу, наследующую все image, services, before_script и script из шаблона. Вы переопределяете только секцию variables.

Кавычки в BUILD_ARGS

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

BUILD_ARGS: "--build-arg FOO=bar --build-arg BAZ=qux"

Не используйте YAML-списки — BUILD_ARGS подставляется непосредственно в команду docker build как одна строка.

Поведение тегирования образов

Шаблон присваивает каждому образу два тега:

1. Тег commit SHA — $REGISTRY_IMAGE/$SERVICE_NAME:$CI_COMMIT_SHORT_SHA (присваивается всегда)
2. Тег окружения — один из prod, stage или dev в зависимости от исходной ветки:
   • Ветка main создаёт тег prod
   • Ветка stage создаёт тег stage
   • Ветка dev создаёт тег dev

Это значит, что образ gitlab.amzgit.com:5050/meduza/hub/backend:a1b2c3d4 также будет доступен как gitlab.amzgit.com:5050/meduza/hub/backend:dev, если собран из ветки dev.

---

Шаблон .nomad_deploy

Расположение: .gitlab/ci/nomad-deploy.yml

Этот шаблон деплоит сервис в целевое окружение, отправляя Nomad-задачу на KVM-хост.

Исходный код шаблона

.nomad_deploy:
  stage: deploy
  image: alpine:3.19
  # Installs Nomad CLI, sets up SSH to KVM host
  # SCPs nomad job + vars files to KVM host
  # Runs: nomad job run -var image_tag=${CI_COMMIT_SHORT_SHA} \
  #        -var-file=... job.nomad.hcl

Что он делает

1. Устанавливает Nomad CLI внутри раннера alpine:3.19.
2. Настраивает SSH-доступ к KVM-хосту, используя секреты из CI/CD-переменных.
3. Копирует по SCP файл Nomad-задачи (job.nomad.hcl) и файл переменных для конкретного окружения на хост.
4. Запускает nomad job run с -var image_tag=${CI_COMMIT_SHORT_SHA} и соответствующим -var-file для целевого окружения.

Переменные

Переменная	Обязательна	Описание
JOB_NAME	Да	Имя Nomad-задачи (например, hub, auth, ml-pipeline).
ENV_NAME	Да	Целевое окружение: dev, stage или prod. Определяет, какой var-файл используется.
CI_COMMIT_SHORT_SHA	Авто	Передаётся как image_tag в Nomad-задачу, чтобы был загружен нужный Docker-образ.

Как наследовать

deploy:dev:
  extends: .nomad_deploy
  variables:
    JOB_NAME: hub
    ENV_NAME: dev
  only:
    - dev

deploy:stage:
  extends: .nomad_deploy
  variables:
    JOB_NAME: hub
    ENV_NAME: stage
  only:
    - stage

deploy:prod:
  extends: .nomad_deploy
  variables:
    JOB_NAME: hub
    ENV_NAME: prod
  only:
    - main

Деплой в продакшн

Задача deploy:prod запускается при пуше кода в main. На уровне CI нет ручного согласования. Защитите ветку main обязательными ревью мерж-реквестов в GitLab, чтобы предотвратить случайные деплои в продакшн.

Соответствие веток и окружений

Ключевое слово only ограничивает каждую задачу деплоя одной веткой. Это обеспечивает следующее соответствие:

Ветка	Окружение	Задача деплоя
dev	dev	deploy:dev
stage	stage	deploy:stage
main	prod	deploy:prod

---

Полный пример: сервис Hub

Объединяя оба шаблона, вот полный .gitlab-ci.yml для сервиса Hub:

include:
  - project: 'meduza/infra'
    file:
      - '.gitlab/ci/docker-build.yml'
      - '.gitlab/ci/nomad-deploy.yml'

stages:
  - build
  - deploy

# --- Build Jobs ---
build:backend:
  extends: .docker_build
  variables:
    SERVICE_NAME: backend
    SERVICE_DIR: back

build:frontend:
  extends: .docker_build
  variables:
    SERVICE_NAME: frontend
    SERVICE_DIR: front
    BUILD_ARGS: "--build-arg VITE_API_URL=https://api.amzhub.ai"

# --- Deploy Jobs ---
deploy:dev:
  extends: .nomad_deploy
  variables:
    JOB_NAME: hub
    ENV_NAME: dev
  only: [dev]

deploy:stage:
  extends: .nomad_deploy
  variables:
    JOB_NAME: hub
    ENV_NAME: stage
  only: [stage]

deploy:prod:
  extends: .nomad_deploy
  variables:
    JOB_NAME: hub
    ENV_NAME: prod
  only: [main]

Добавляете новый сервис?

Скопируйте этот паттерн. Единственное, что вы меняете — это SERVICE_NAME, SERVICE_DIR, JOB_NAME и любые BUILD_ARGS, специфичные для вашего сервиса. Всё остальное обрабатывается шаблонами.