gitlab-ci-explainer

Объясняет, почему job GitLab CI запускаются, пропускаются и зависят друг от друга.

gitlab-ci-explainer — локальный CLI на Python, который преобразует конфигурацию GitLab CI в детерминированное и проверяемое объяснение.

Important

Статус: проектирование. В репозитории пока есть документация и задачи на реализацию. Рабочего CLI ещё нет.

Зачем нужен проект

Валидный pipeline не всегда понятен. По одному YAML бывает сложно ответить:

• почему job появилась или исчезла;
• какое условие rules сработало;
• откуда пришло эффективное значение переменной;
• какой include, default или родительская job изменили итоговую конфигурацию;
• почему одна job может стартовать сразу, а другая ждёт завершения этапа.

Инструмент должен показывать промежуточные факты и причины результата, а не угадывать правдоподобный ответ.

Планируемый интерфейс

Первая полезная версия намеренно мала. Для одного локального файла:

stages: [build, test, deploy]

build:
  stage: build
  script: make build

test:
  stage: test
  needs: [build]
  script: make test

deploy:
  stage: deploy
  needs: [test]
  script: ./deploy.sh

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

$ ci-explain summary .gitlab-ci.yml
JOB     STAGE    NEEDS
build   build    -
test    test     build
deploy  deploy   test

Это целевой интерфейс, а не уже реализованный результат.

Первый этап

Версия 0.1 должна уметь:

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

В 0.1 не входят include, extends, вычисление rules, GitLab API, удалённые файлы, веб-сервис и AI-объяснения.

Принципы

Детерминированное ядро. Один вход и один контекст всегда дают один результат.

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

Сначала локальная работа. Сеть добавляется только там, где без неё нельзя реализовать конкретную возможность.

Явная совместимость. Неподдерживаемый синтаксис нельзя молча игнорировать.

Простая архитектура. Никаких плагинов, сервиса, базы данных и абстракций «на будущее» без реальной необходимости.

Обучение важнее скорости. Реализацию пишет владелец проекта. AI используется прежде всего как справочник, наставница, помощница в диагностике и ревьюер.

Документация

• План развития — порядок этапов и границы версий.
• Архитектура — модель обработки, ограничения и инварианты.
• Участие в разработке — рабочий процесс и требования к pull request.
• Режим обучения — как использовать AI и не отдать ему практику программирования.
• Инструкции для AI-агентов — правила работы с репозиторием.

Работа над реализацией ведётся в GitHub Issues. Начинать нужно с первой незаблокированной задачи текущего этапа и ограничивать один pull request одной задачей.

Граница проекта

Инструмент не выполняет script, не заменяет GitLab Runner и не становится вторым CI-сервисом. Он объясняет конфигурацию GitLab CI только в явно документированной области совместимости.