GitLab CI/CD: общая конфигурация и диагностика

Курс «Лаборатория GitLab CI/CD»

Лаборатория course-card дошла до ручной подготовки staging. В одном файле находятся общая среда, workflow, стадии и четыре задания. Разделим настройки без изменения процесса: корневой .gitlab-ci.yml сохраняет общую политику, а ci/jobs.yml — определения jobs. Затем разберём, как оценивать итоговую конфигурацию, потому что короткий корневой файл не показывает всех наследуемых свойств.

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

Локальный include

Корневой файл конечного варианта задаёт default image, SITE_TITLE, workflow и стадии build, verify, prepare, затем подключает definitions из текущего репозитория. В полном архиве этот файл сохранён без пропущенных разделов. Здесь показан только добавляемый include-блок:

include:
  - local: '/ci/jobs.yml'

Путь относится к репозиторию версии, для которой читается конфигурация. Он не является адресом файла на компьютере автора урока. Если ci/jobs.yml не попал в commit, GitLab не сможет получить definitions. Поэтому внешний вид локальной папки сам по себе не доказывает, что нужный файл доступен серверу.

Local include удобен, когда общая политика и задания живут вместе. Для внешних шаблонов потребуется отдельно решить версию, доверие и доступ. Не подключайте изменяемую удалённую ветку только ради уменьшения собственного YAML: новая редакция шаблона может поменять состав процесса без явного изменения проекта. Возможности include описаны в официальной документации.

Небольшой шаблон extends

В ci/jobs.yml создайте скрытое определение .node-job с диагностической командой. Начальная точка в имени означает, что оно служит шаблоном и само не является выполняемым job. Реальные задания используют extends, сохраняя свои stage, needs и script.

.node-job:
  before_script:
    - node --version

build-site:
  extends: .node-job
  stage: build
  script:
    - node scripts/build.mjs
  artifacts:
    name: 'course-card-$CI_COMMIT_SHORT_SHA-$CI_PIPELINE_ID'
    paths:
      - dist/
    reports:
      dotenv: build.env
    expire_in: 7 days

Это полный build job конечной структуры; остальные jobs в том же include-файле описаны в архиве. Общая команда сообщает версию среды, а конкретный script строит сайт. Мы не скрываем предметную работу внутри многоуровневого наследования. Читатель должен по определению job находить его основной output без перехода через пять шаблонов.

Extends выполняет слияние настроек по правилам GitLab, а не простое склеивание всех списков. Если дочерний job переопределяет before_script, ожидайте замены соответствующего значения, а не автоматического добавления строк. Не принимайте визуальное повторение ключа за гарантию объединения. Итоговые свойства нужно смотреть после раскрытия конфигурации.

Карта входов и выходов

Job	Вход	Output	Условие готовности
build-site	JSON, шаблон, SITE_TITLE, генератор	dist и build.env	Данные соответствуют договору
analyze-catalog	JSON и анализатор	Необязательная кэш-сводка	Правильное число курсов и уроков
verify-site	Артефакт build	reports JSON/XML	Целостность и структура соблюдены
prepare-staging	Тот же dist и успех verify	staging	Разрешённое ручное действие

Эта таблица позволяет заметить случайное изменение смысла. Если verify начинает вызывать build, вход перестаёт быть артефактом предыдущей работы. Если prepare сохраняет новую сборку вместо полученной, теряется идентичность. Если анализ читает dist, он уже не может стартовать с needs пустым списком. Поддержка конфигурации начинается с такой причинной карты.

Общий workflow допускает branch до MR, MR, default branch и выбранный ручной запуск. Prepare появляется только после push в default branch. Поэтому не каждый зелёный pipeline имеет одинаковый состав. MR показывает проверку изменения, а default branch может ожидать ручную подготовку. Нужно оценивать состояние относительно события и состава обязательных jobs.

Проверка конфигурации и запуск

CI Lint и Pipeline Editor могут проверять допустимость и раскрывать объединённый файл. Это помогает обнаружить неправильный ключ, отсутствующий include и несогласованные needs. Но такая проверка не выполняет build.mjs и не подтверждает доступность внешнего образа. Документация инструмента находится в разделе валидации CI/CD configuration.

С другой стороны, успешный запуск одного события не доказывает правильность всех rules. Нужны отдельные условия: ветка без MR, ветка с MR, default push и исключённый тег. В этой серии они описаны как ожидаемые состояния. При самостоятельной проверке запишите source, commit, состав jobs и outputs, чтобы сравнивать конкретные случаи, а не общую фразу «всё работает».

Не путайте тестирование учебного pipeline с редакционной подготовкой этих материалов. При написании курса не выполнялись программы, контейнеры, CI Lint, тесты и внешняя публикация. Полные листинги и правила позволяют воспроизвести процесс позднее в собственной среде. Отсутствие запуска сохранено как example_execution: not_run у каждой статьи.

При изменении include-файла сравните итоговый job с таблицей договора. Добавленная строка before_script может повлиять на все четыре задания, даже если автор редактировал только небольшой шаблон. Поэтому общие настройки должны оставаться короткими и понятными. Если действие требуется только build, поместите его в build, а не в универсальный шаблон ради сокращения нескольких символов. Такой выбор делает последствия редакции видимыми для человека, который читает файл впервые. Общая конфигурация полезна, когда выражает действительно общее условие, а не скрывает разные предметные задачи под одним именем.

Разбор первой причины

Начинайте диагностику с фазы, где возникла первая существенная ошибка. Невалидная конфигурация не создаёт нужный граф. Pending означает ожидание подходящего runner. Ошибка загрузки image происходит до программы. Failed build относится к данным, шаблону или генератору. Failed verify требует посмотреть передачу и отчёт. Отсутствующая manual-кнопка может быть следствием rules.

Не добавляйте retry, allow_failure или optional без установления причины. Retry помогает при определённых временных ошибках, но не исправит неправильный путь. Allow failure меняет обязательность результата, а optional — допустимость отсутствующей зависимости. Эти ключи выражают договор процесса и могут скрыть проблему, если используются как универсальные средства сделать pipeline зелёным.

Если отчёта нет, читайте журнал: программа могла не начать работу или не успеть записать outputs. Если отчёт есть, сопоставьте его commit с release metadata. Старый файл из кэша или другого pipeline не должен считаться подтверждением текущего результата. Сохранение происхождения помогает даже в лаборатории с тремя карточками.

Ожидаемый итог серии — оригинальный каталог и понятный конвейер его подготовки: один build-артефакт, обязательная проверка, независимый анализ и ручной staging-пакет без внешнего получателя. Архив проекта содержит конечный YAML, программы и снимки каждого шага. Механизм можно развивать дальше, сохраняя эти входы, outputs и границы подтверждённых действий.