Простой и надежный вход в CI/CD: как настроить кэш зависимостей, чтобы сборки не “умирали”

Стабильный CI/CD — это не про красивый статус в интерфейсе GitLab/GitHub. Это про воспроизводимость, предсказуемость и скорость, которые со временем не ломаются из‑за “случайного” изменения зависимостей или окружения сборки. Самая частая причина ухудшения пайплайнов — не медленные тесты и даже не компиляция, а зависимость от внешнего мира: пакеты скачиваются заново, сеть пульсирует, а кэш начинает “подсасывать” неправильные версии.

Кэширование зависимостей решает и скорость, и стоимость сборок, но при ошибках может сделать хуже: сборки станут нестабильными или будут выдавать ложные результаты. Поэтому подход должен быть простым, механически проверяемым и “минимально поддерживаемым”.

В этой статье разберем практические паттерны кэширования для pip/Poetry и Node (node_modules), покажем, как формировать ключи кэша по lockfile, сформулируем правила “всегда воспроизводимо” и разберем типичные ошибки, когда кэш портит сборку. В конце соберем минимально поддерживаемую конфигурацию, которую можно перенести между CI-системами.

Почему кэш “иногда ломает”, и что значит “воспроизводимо”

Что кэшируем на самом деле

Кэш в CI обычно хранит артефакты, вычисленные “из прошлого состояния”. В зависимости от контекста это может быть:

• скачанный архив пакета (pip wheels, Poetry cache);
• распакованные пакеты (node_modules);
• промежуточные сборки (например, кеш компилятора для Python‑расширений или сборки npm);
• системные артефакты (например, слои Docker).

Смысл кэша — избежать повторных операций, которые детерминированы входными данными. Но детерминированность часто иллюзорна: “вчера работало” означает, что вы случайно совпали с версией пакетов, платформой или параметрами.

Правило воспроизводимости

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

1. lockfile (или эквивалента, который фиксирует версии);
2. runtime (Python/Node версии);
3. платформы/архитектуры (важно для бинарных wheel’ов и нативных модулей);
4. (иногда) параметров установки (например, extras, опции, приватный индекс).

Если этого нет — кэш становится “приблизительным”, и вы начнете ловить эффекты типа: “на ветке A все зелено, на ветке B красно, хотя зависимости совпадают”, или наоборот — “красно в CI, но локально ок”.

Минимальная модель: как устроить кэширование зависимостей

Принцип: кэш должен быть производным

Практический паттерн такой:

• Определяем функцию ключа: cache_key = hash(lockfile + runtime + platform + relevant_options).
• Кэш используем как ускорение, но не как источник правды.
• При изменении lockfile ключ меняется — кэш обновляется автоматически.
• При изменении runtime ключ меняется, чтобы избежать неконсистентности.

Идея простая: кэш — это “ускоритель”, а не “хранилище состояния проекта”.

Принцип: кэширование должно быть идемпотентным

Если повторить шаг установки с тем же lockfile и тем же ключом, результат должен быть одинаковым. На практике это означает:

• использование --require-hashes (для pip) или строгое следование lockfile (для Poetry);
• не смешивать dev/prod окружения без учета в ключе;
• не кэшировать частичные результаты (например, недокачанные зависимости из-за таймаута).

Кэширование Python: pip и Poetry

pip: wheels и их ключи

Для pip чаще всего кэшируют скачанные wheels, а не полностью установленный site-packages (хотя технически можно кэшировать и это). Wheels — более безопасный объект, потому что соответствуют конкретным версиям и обычно учитывают платформу.

Ключевой подход: кэш wheels должен зависеть от requirements.txt (или вашего lockfile) и условий установки.

Пример для CI-скрипта (логика универсальная, команды можно адаптировать под GitHub Actions/GitLab):

# 1) Убедимся, что pip знает, какие зависимости фиксированы
# Например, requirements.txt генерируется заранее и является lockfile.

PYTHON_VERSION="$(python --version | awk '{print $2}')"
PLATFORM="$(python -c "import platform; print(platform.platform())")"

# Если у вас requirements.txt — это lockfile,
# используйте его содержимое:
LOCK_HASH="$(sha256sum requirements.txt | awk '{print $1}')"

CACHE_DIR="$HOME/.cache/pip/wheels"
CACHE_KEY="pip-wheels-${PYTHON_VERSION}-${PLATFORM}-${LOCK_HASH}"

echo "Cache key: $CACHE_KEY"
echo "Cache dir: $CACHE_DIR"

# В CI обычно есть шаг restore/save кеша по CACHE_KEY
# Далее — установка:
python -m pip install --upgrade pip
python -m pip install --no-input --disable-pip-version-check -r requirements.txt

Ключевые моменты:

• Если у вас нет lockfile (просто requirements.in + pip install -r requirements.txt без фиксации), вы получите кэш по “произвольной” актуальной версии пакетов. Воспроизводимости не будет.
• Если Python версия меняется, wheels могут стать несовместимыми. Поэтому она должна участвовать в ключе.

Для “железобетонной” воспроизводимости

Если вы можете управлять зависимостями так, чтобы их версии фиксировались хешами, добавьте --require-hashes и используйте pip-compile --generate-hashes (pip-tools). Тогда даже при сетевых флуктуациях вы не примете “другой” пакет.

python -m pip install --no-input --require-hashes -r requirements.txt

Это не ускоритель “в чистом виде”, но уменьшает шанс “тихой” несовместимости.

Poetry: кэш как производная от lockfile

Poetry уже опирается на lockfile (poetry.lock) и по умолчанию стремится к детерминированности. Но кэшировать ~/.cache/pypoetry можно и нужно, а также стоит избегать сценариев, когда вы смешиваете разные группы зависимостей.

Минимальная модель для Poetry:

• ключ кеша = hash(poetry.lock) + python_version + groups;
• кэш = Poetry cache и/или wheel cache pip, который Poetry использует внутри.

Пример:

PYTHON_VERSION="$(python --version | awk '{print $2}')"
PLATFORM="$(python -c "import platform; print(platform.system()\"/\"+platform.machine())")"
LOCK_HASH="$(sha256sum poetry.lock | awk '{print $1}')"

# Если вы ставите только main dependencies:
# poetry install --only main
GROUPS="main"

CACHE_KEY="poetry-${PYTHON_VERSION}-${PLATFORM}-${LOCK_HASH}-${GROUPS}"
echo "Cache key: $CACHE_KEY"

# Кэшируемые директории зависят от вашего CI и настроек,
# но обычно достаточно:
# - ~/.cache/pypoetry
# - ~/.cache/pip
export PIP_CACHE_DIR="$HOME/.cache/pip"
export POETRY_CACHE_DIR="$HOME/.cache/pypoetry"

# Установка
poetry config virtualenvs.create false  # установить в system env контейнера/VM
poetry install --only main --no-interaction --no-ansi

Если вы используете виртуальные окружения внутри кэша — можно ускориться сильнее, но вы сильнее рискуете несовместимостью и “залипанием” старого окружения. Для минимально поддерживаемого варианта лучше кэшировать то, что детерминировано: скачанные артефакты и вычисленные колеса, а не готовую среду.

Кэширование Node.js: node_modules, npm cache и правильные ключи

node_modules: быстро, но опасно без учета среды

Кэшировать node_modules можно, но это один из самых хрупких вариантов: дерево зависимостей зависит от:

• версии Node;
• версии npm/yarn/pnpm;
• платформы (особенно для нативных модулей);
• параметров установки (production/dev);
• архитектуры.

Если вы все это не учтете в ключе — получите “оно запускается на одной машине и ломается на другой”.

npm cache: обычно безопаснее

Для npm часто достаточно кэшировать ~/.npm (npm cache), а затем запускать npm ci. Это уменьшит время скачивания и сборок, но оставляет node_modules в рабочем виде, который создается заново в текущем окружении.

И ключ кэша все равно должен зависеть от lockfile (package-lock.json) и runtime.

Пример для npm:

NODE_VERSION="$(node --version)"
NPM_VERSION="$(npm --version)"
PLATFORM="$(node -p "process.platform + '/' + process.arch")"
LOCK_HASH="$(sha256sum package-lock.json | awk '{print $1}')"

INSTALL_MODE="production"  # либо dev/all

CACHE_KEY="npm-cache-${NODE_VERSION}-${NPM_VERSION}-${PLATFORM}-${LOCK_HASH}-${INSTALL_MODE}"
echo "Cache key: $CACHE_KEY"

export NPM_CONFIG_CACHE="$HOME/.npm"

# Установка строго по lockfile
# npm ci удаляет node_modules и ставит "как в lockfile"
npm ci --omit=dev

Почему npm ci важно: оно предназначено для чистой установки по lockfile и уменьшает шансы на “дрейф” зависимостей при повторном запуске.

Когда кэшировать node_modules оправдано

Если вы контролируете CI как “один и тот же контейнер” (одинаковые версии Node/npm, одинаковая ОС/архитектура) и кэш ключится строго, node_modules дает максимальный ускоряющий эффект. Но это требует дисциплины.

Если у вас есть монорепозиторий, workspace и нестандартные флаги, кэширование node_modules превращается в отдельную инженерную задачу (и обычно это слишком дорого для “минимально поддерживаемой” конфигурации).

Ключи кэша: что именно хэшировать и как избежать “невидимых” изменений

Lockfile обязателен

Если говорить прямо: без lockfile кэш не может быть надежным механизмом воспроизводимости.

• Для pip — обычно requirements.txt, сформированный из lock-процесса (pip-tools), или другой эквивалент.
• Для Poetry — poetry.lock (он и есть ваш lockfile).
• Для npm — package-lock.json.
• Для yarn — yarn.lock.
• Для pnpm — pnpm-lock.yaml.

При этом важно учитывать, что иногда lockfile обновляется не так очевидно (например, при смене опций установки). Поэтому ключ должен включать параметры, которые меняют состав зависимостей.

Учитывайте группы и режимы установки

Примеры параметров, которые меняют набор пакетов:

• Python/Poetry: --only main vs --with dev (или отдельные группы в Poetry);
• Node: --omit=dev vs установка dev-зависимостей;
• npm/yarn/pnpm: --frozen-lockfile и аналоги;
• приватные реестры (если вы подключаете разные индексы, зависит состав).

Если вы не учтете режим, получите классическую проблему: кэш production-зависимостей будут пытаться применить там, где ожидаются dev-зависимости.

Включайте “runtime fingerprint” в ключ

Минимальный набор для ключа:

• Python version;
• OS/arch (хотя бы platform.system()/machine или process.platform/arch);
• Node version + версия пакетного менеджера (npm/yarn/pnpm).

Для нативных модулей это особенно критично: wheel/сборка зависит от ABI и инструментов.

Правила “всегда воспроизводимо”: практический чеклист

Ниже — набор правил, который дает хороший баланс между надежностью и скоростью.

1) Устанавливайте строго из lockfile

• pip: генерация lock + pip install -r requirements.txt (желательно --require-hashes);
• Poetry: poetry install и неизменный poetry.lock;
• npm: npm ci (а не npm install).

2) Делите dev и prod кэши

Обычно лучше иметь два режима:

• dev (включая тесты/линтеры);
• prod (только то, что нужно приложению).

В ключ кэша добавляйте режим установки. Это дешевле, чем потом разбираться с “странными” зависимостями.

3) Не кэшируйте “слишком много”, пока не уверены

Самый безопасный минимум:

• pip/Poetry: кеш скачанных wheels/артефактов;
• npm: кеш пакетного менеджера;
• node_modules — опционально, только при строгих гарантиях идентичности окружения.

4) Делайте установку идемпотентной

Повторный запуск CI должен быть “механически одинаковым”. Если команда установки не чистит старые артефакты (например, npm install), то кеш может начать спорить с остатками файлов.

5) Очевидно обновляйте кэш при изменениях

Поскольку ключ включает lockfile и runtime, обновление — автоматическое. Если вы используете “фиксированный” ключ (например, pip-cache без хеша), то кэш будет жить дольше, чем ему полезно.

Типичные ошибки: как кэш портит сборку

Ошибка 1: фиксированный ключ кэша без привязки к lockfile

Симптом: “на одной ветке все нормально, на другой непонятно”.
Причина: вы используете один и тот же ключ для разных наборов зависимостей. CI может восстановить кэш старых wheels или npm пакетов.

Как исправить: ключ должен включать хеш lockfile.

Ошибка 2: кэшировать node_modules без учета Node/npm версий и платформы

Симптом: нативные модули падают с ошибками компиляции или runtime ABI.
Причина: node_modules был собран для другой версии Node или другой платформы.

Как исправить: либо переходите на кеш npm, либо ключуйте node_modules по node_version + npm_version + platform.

Ошибка 3: смешивать режимы dev/prod

Симптом: тесты “не находятся” или, наоборот, прод собирается с dev-зависимостями и становится тяжелым.
Причина: production-режим восстановил кэш из dev-сборки или наоборот.

Как исправить: режим установки (omit dev / groups в Poetry) — в ключ.

Ошибка 4: безусловно “скачали” зависимости, но кэш частично восстановился из‑за таймаута

Симптом: редко воспроизводимые ошибки, иногда зависящие от загрузки сети.
Причина: кеш был записан после неуспешной/частичной установки.

Как исправить: кэш сохраняйте только после успешной установки; в некоторых CI — явно контролируйте, что save выполняется в post-step при success.

Ошибка 5: кэшировать виртуальные окружения целиком

Симптом: внезапные конфликты пакетов или несоответствие интерпретатора.
Причина: venv зависит от пути, python ABI, наличия системных библиотек и может “прилипнуть” к контейнеру.

Как исправить: минимально — кэшировать артефакты установки; максимум воспроизводимости — строить venv/директории заново, используя кэш wheels.

Минимально поддерживаемая конфигурация (концептуальная)

Ниже — универсальный “каркас” пайплайна, который вы можете перенести на конкретный CI. Это не привязано к одному провайдеру, потому что логика одна: restore → install (строго по lockfile) → save (если успешно).

Шаблон ключей

• Python:
  • LOCK_HASH = sha256(lockfile)
  • CACHE_KEY = {tool}-{python}-{platform}-{LOCK_HASH}-{install_mode}
• Node:
  • CACHE_KEY = {tool}-{node}-{npm/yarn/pnpm}-{platform}-{LOCK_HASH}-{install_mode}

Шаблон шагов для Python

# Предусловие:
# - lockfile существует (requirements.txt/poetry.lock)
# - Python установлен и версия соответствует ожиданиям

LOCK_HASH="$(sha256sum poetry.lock | awk '{print $1}')"
PYTHON_VERSION="$(python -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")"
PLATFORM="$(python -c "import platform; print(platform.system()+'-'+platform.machine())")"
GROUPS="main"

CACHE_KEY="poetry-cache-${PYTHON_VERSION}-${PLATFORM}-${LOCK_HASH}-${GROUPS}"

# restore cache: ~/.cache/pip и ~/.cache/pypoetry

poetry config virtualenvs.create false
poetry install --only main --no-interaction --no-ansi

Шаблон шагов для npm

LOCK_HASH="$(sha256sum package-lock.json | awk '{print $1}')"
NODE_VERSION="$(node -p "process.versions.node")"
NPM_VERSION="$(npm -p "require('./package.json').version" 2>/dev/null || npm --version)"
PLATFORM="$(node -p "process.platform + '/' + process.arch")"
INSTALL_MODE="production"

CACHE_KEY="npm-cache-${NODE_VERSION}-${NPM_VERSION}-${PLATFORM}-${LOCK_HASH}-${INSTALL_MODE}"

# restore cache: ~/.npm