Почему CI/CD Python разваливается на зависимостях
Классический сценарий: разработчик прогоняет тесты локально, всё зелёное, ветка уходит в общий конвейер — и сборка зависимостей падает на установке пакетов. Причина не в коде, а в окружении разработчика: оно накоплено месяцами и не описано ни в одном файле проекта.
Первый источник — отсутствие зафиксированного набора версий. Если зависимости объявлены диапазонами, а файл блокировки не обновляется при каждом изменении, CI/CD Python ставит то, что на момент запуска лежит в индексе. Два запуска на разных машинах дают разные деревья зависимостей, и конфликт версий пакетов всплывает уже в чужой ветке.
Второй — смешение инструментов. pip, Poetry и Conda разрешают зависимости по-разному: Conda тянет бинарные сборки из своих каналов, pip — из индексов, Poetry фиксирует собственное дерево. Один пакет, поставленный в обход основного менеджера, делает сборку невоспроизводимой. Отдельная строка боли — версия интерпретатора: расхождение между локальной машиной и образом в конвейере меняет правила разрешения зависимостей и ломает бинарные пакеты, собранные под другую версию.
Цена такой нестабильности — не одна упавшая сборка. Падение сборки на этапе установки съедает время всей команды, приучает игнорировать красные прогоны и переносит поиск настоящей ошибки на день релиза. Разбираем, как это закрывается.
Что меняется в команде после налаженной сборки и выпуска
Эффект от налаженного конвейера виден в ежедневных цифрах: сколько идёт сборка, сколько занимает возврат к прошлому релизу, какая доля шагов выпуска делается руками. Ниже — четыре сдвига, которые заказчик замечает уже в первые недели, без отдельного проекта по «внедрению метрик».
Сборка — минуты вместо десятков минут
Кэш зависимостей и слоёв, фиксированный базовый образ, разделение установки пакетов и прогона тестов — сборка перестаёт заново скачивать и компилировать одно и то же. Разработчик получает обратную связь по своему коммиту, а не к концу дня, и правки перестают копиться в ожидании прогона.
Воспроизводимость на всех стендах
Poetry с зафиксированным lock-файлом, хеши пакетов и один образ для локальной машины, тестового стенда и боевого окружения убирают расхождения «у меня работает». Набор зависимостей одинаков везде, поэтому сбой воспроизводится локально, а не только на сервере за пять минут до выпуска.
Возврат к прошлому релизу — минуты
Артефакт собирается один раз и продвигается по средам без пересборки: в боевое окружение попадает ровно то, что прошло проверки. Если релиз пошёл не так, возврат — это переключение на предыдущий тег, а не повторная сборка и поиск нужной ветки в спешке.
Класс отказов, который уходит
Расхождение окружений, забытая зависимость, несовместимая версия библиотеки, шаг, пропущенный вручную, — эти отказы ловятся на этапе проверок и не доходят до пользователей. Доля ручных операций в выпуске падает, а вместе с ней уходит вариативность: сценарий выполняется одинаково и человеком, и по расписанию.
Способы сборки окружений для Python-проектов
В Python нет встроенной фиксации окружения: интерпретатор один, а набор библиотек в системной ветке общий для всех проектов. Стоит поднять рядом второй сервис с несовместимой мажорной версией общей зависимости — и падает уже работающий. Виртуальное окружение закрывает изоляцию, но не воспроизводимость: без фиксации версий сборка на другой машине подтянет свежие транзитивные зависимости и поведение кода изменится.
Выбор менеджера зависимостей определяет, что именно попадает в изоляцию и насколько повторяемо это воспроизводится в сборке пакетов.
| Вариант | Когда подходит | Ограничения |
|---|---|---|
venv + pip + requirements.txt |
Небольшие сервисы, зависимости перечислены вручную | Нет фиксации транзитивных версий — повторная установка даёт другой набор |
pip-tools |
Уже сложился requirements.txt, нужна фиксация версий |
Прямые и транзитивные списки ведутся раздельно, конфликты разрешаются пересборкой |
| Poetry / PDM | Библиотеки и сервисы с группами зависимостей под тесты и документацию | Свой алгоритм разрешения версий, расхождения с pip при сборке артефактов |
| Conda | Научный стек и бинарные зависимости вне PyPI | Тяжёлые каналы, окружение плохо ужимается в минимальный образ |
| Образ контейнера как окружение | Сервисы, где среда сборки и рантайм должны совпадать | Без слоистого кеша время сборки растёт кратно на каждой правке кода |
Практически выбор идёт по двум осям: кто разрешает конфликты версий — pip или собственный механизм менеджера, и где проходит граница окружения — в виртуальном каталоге или в образе. Для сервиса, который выкатывается контейнером, разумно фиксировать версии файлом блокировки и ставить зависимости отдельным слоем: тогда правка кода не перетаскивает библиотеки, а несовпадение версий всплывает на сборке, а не в рантайме.
Этапы внедрения: от разбора репозиториев до передачи
Порядок работ одинаков для любого стека: сначала разобраться, что уже есть в репозиториях, и только потом строить конвейер. Пропущенный аудит приводит к тому, что сборка заводится в одном проекте и разваливается в остальных, а расхождение окружений всплывает уже на выкате. Ниже — последовательность, по которой мы проходим внедрение.
- Аудит репозиториев. Смотрим структуру проектов и то, чем объявлены зависимости: requirements.txt с точными версиями, pyproject.toml с Poetry или отдельная среда Conda. Отмечаем, где окружение собирается руками и сколько это отнимает времени у команды.
- Схема конвейера. Согласуем стадии и их порядок: подготовка окружения, проверки кода, тесты, сборка артефакта, публикация, доставка на стенды. Для каждой стадии сразу определяем, что считается блокирующей ошибкой.
- Настройка окружений. Приводим версию интерпретатора и состав зависимостей к единому виду, включаем кэш пакетов между запусками — повторная сборка больше не тянет всё с нуля.
- Тестовый прогон. Запускаем конвейер на одном репозитории или ветке, замеряем время стадий и ищем падения на пустом месте: плавающие зависимости, отсутствие изоляции тестов.
- Приёмочная проверка. Проходим сценарии, критичные для заказчика: падение тестов блокирует доставку, откат на предыдущий артефакт, параллельные сборки не мешают друг другу.
- Передача и обучение. Отдаём схему конвейера, инструкцию по правке стадий и разбор типовых сбоев, проходим их с командой — дальше поддержку ведут своими силами.
Конфигурации, схемы и регламенты: что остаётся в проекте
Настроенный конвейер без документации живёт до первого ухода инженера, который его собирал: через месяц уже никто не помнит, почему зависимости фиксируются именно так и что произойдёт при откате. Поэтому вместе с работающей сборкой передаём комплект артефактов в репозиторий проекта и в базу знаний команды — по ним процесс воспроизводится без автора.
- Файлы конфигурации конвейера с комментариями: где стадии сборки и тестов, какие условия запуска, что кэшируется между прогонами.
- Файлы управления зависимостями для выбранного инструмента (pip, Poetry или Conda): зафиксированные версии, разделение наборов для разработки и для релиза.
- Схема окружений: какие контуры есть, что в каждом разворачивается, чем отличаются параметры, как окружение поднимается с нуля.
- Политики доступа к секретам: где хранятся ключи, кто их выдаёт, как проходит ротация и что гарантированно не попадает в логи.
- Регламент выпуска: путь от ветки до продуктивной среды, кто принимает решение, в каких точках возможен откат и что блокирует выпуск.
- Инструкции для дежурного инженера: типовые сбои сборки, порядок действий при падении прогона и откате, точки эскалации.
Комплект снимает зависимость от устных договорённостей: новый инженер входит в проект по документам, а проверяющий видит, кто и на каком основании менял доступы и выпуски. Регламент и схема окружений остаются рабочими документами — их правят вместе с кодом, а не восстанавливают после сбоя.
Кейс: конвейер выпуска для распределённой команды
В распределённой команде сборка одного сервиса занимала от 18 до 25 минут, и это время почти не зависело от объёма правок. Причина была не в тестах: половину шага съедала установка зависимостей, которую каждый контур решал по-своему — сервисы тянули свежие версии из общего индекса, часть проектов собиралась Poetry, аналитический контур жил в отдельном Conda-окружении. На выходе получалось главное: сборщик и машина разработчика давали разные наборы пакетов.
Что изменили
Зависимости свели к единому источнику истины: версии фиксируются файлом блокировки, установка идёт из него, а не из диапазонов. Кэш слоёв настроен так, что пересборка окружения запускается только при изменении этого файла, а сама сборка в GitLab CI идёт в неизменяемом образе, привязанном к конкретной ревизии кода. Проверки разделили на быстрый набор на каждое изменение и полный прогон перед выпуском.
До: около 20 минут на сборку, срывался каждый четвёртый выпуск — расхождение окружений, падение на шаге установки, ручные правки на сервере. После: сборка укладывается в 6–7 минут, срывается один выпуск из двадцати, а откат возвращает предыдущий образ за минуты вместо ручного разбора.
Чем сборка библиотеки отличается от сборки сервисов?
Библиотека и сервис различаются не содержимым репозитория, а тем, что считается результатом сборки. У библиотеки это неизменяемый пакет, который публикуется в приватный реестр и дальше живёт в чужих зависимостях. У сервиса — образ, который разворачивается в конкретном окружении и остаётся там работать месяцами. Отсюда расходятся требования к версионированию, публикации артефактов и откату.
Сборка библиотек проверяется матрицей: несколько версий интерпретатора, оба поддерживаемых менеджера зависимостей, отдельно — установка пакета из собранного артефакта, а не из исходников. Схема версионирования здесь семантическая и жёсткая: изменение, ломающее обратную совместимость, обязано поднять мажорную часть. От пакета зависят другие команды, и они обновляются по своему графику, а не одновременно с вами.
Публикация артефактов для библиотеки — операция необратимая по смыслу: одна версия выпускается один раз, перезапись запрещена, иначе у двух разных сборок окажется одинаковое имя. Если в выпущенной версии нашлась ошибка, выпускают новую patch-версию; откат выполняется на стороне потребителя, который закрепляет предыдущий номер в своём файле зависимостей.
Сборка сервисов решает другую задачу: получить воспроизводимый образ, одинаково ведущий себя на стенде и в рабочем контуре. Здесь проверяют запуск приложения, миграции схемы данных, чтение конфигурации и секретов, поведение под нагрузкой. Версионирование привязывают к состоянию репозитория и метке выпуска, а не к номеру пакета, — важна трассировка «какая ревизия кода сейчас работает».
Откат сервиса и откат библиотеки — тоже разные процедуры. Пакет нельзя вернуть назад в реестре: можно лишь пометить проблемную версию как непригодную, а зависимые проекты переведут свои закрепления. Сервис откатывается переключением на предыдущий образ — быстро, но только если миграции схемы совместимы с прошлым кодом. Поэтому изменения данных готовят так, чтобы один шаг выпуска допускал работу обеих версий.
Технические сомнения перед стартом работ
Вопросы, которые чаще всего всплывают перед началом работ, касаются не инструментов, а рисков: что будет с уже работающим конвейером, как разруливаются конфликты зависимостей и что происходит после передачи. Ниже — короткие ответы по каждому.
У нас уже настроен конвейер сборки — придётся переписывать всё с нуля?
Нет. Сначала снимаем инвентаризацию: какие окружения, откуда тянутся зависимости, где шаги дублируются. Обычно переиспользуется большая часть — меняются только этапы установки зависимостей и кэширования. Переход делаем поэтапно, чтобы основная ветка оставалась рабочей.
Что делать, если зависимости двух сервисов конфликтуют по версиям?
Разводим их по изолированным окружениям и фиксируем несовместимые пары в отдельных сборочных целях. Конфликт, который нельзя снять обновлением, локализуется в одном сервисе и не блокирует сборку остальных. Разбор конфликтов ведём по дереву зависимостей, а не подбором наугад.
Можно ли обойтись без собственного хранилища пакетов?
Да, но с оговорками: при каждой сборке тянем из внешних индексов и держим локальный кэш. Своё хранилище стоит поднимать, когда нужны закрытые пакеты, строгий контроль версий или сборка без доступа во внешнюю сеть. Решение принимаем по числу сервисов и требованиям к изоляции.
Как обеспечивается воспроизводимость сборки?
Фиксируем точные версии, а не диапазоны, и храним файл блокировки рядом с исходниками. Сборка идёт в чистом окружении, с закреплёнными базовыми образами. Это даёт одинаковый результат на машине разработчика и на сборочном агенте, а также позволяет повторить релиз через месяцы.
Кто сопровождает конвейер после передачи?
Передаём конфигурации, схемы этапов и описание типовых сбоев с порядком действий. Команда заказчика может вести конвейер сама — документация рассчитана на это. Если нужна поддержка, остаёмся на сопровождении: правим сбои сборки, обновляем зависимости, дорабатываем этапы под новые сервисы.
Обсудим задачу и вернёмся со схемой и планом
Чтобы вернуться со схемой конвейера, а не с общими словами, нам хватает одного обсуждения задачи. Мы разбираем, как сейчас собирается и публикуется код, где чаще всего падают проверки и какие шаги перед выпуском версии делают руками.
От вас нужен минимум вводных:
- репозиторий или его структура: ветки, теги, порядок выпуска версий;
- файлы зависимостей — что используете: pip, Poetry или Conda, есть ли приватные зеркала пакетов;
- перечень сред и чем они отличаются по доступам и переменным окружения;
- слабые места за последние месяцы: упавшие сборки, ручные шаги, откаты;
- ограничения: закрытые сети, требования по доступам и регламенты безопасности;
- желаемое время сборки и выпуска — цифры, которые считаете приемлемыми.
В ответ присылаем схему конвейера целиком: этапы, условия запуска, кэш зависимостей, разделение проверок и публикации артефактов. К ней — состав работ с границами «что входит и что нет», план работ по этапам и оценку сроков в рабочих днях, отдельно на настройку и на передачу в эксплуатацию. Если на каком-то шаге видим риск, говорим о нём до старта, а не в середине.
Опишите задачу в свободной форме — вернёмся с оценкой и планом.
