Кэширование зависимостей в CI/CD: как ускорить пайплайн без ложных срабатываний | AdminWiki

Кэширование зависимостей в CI/CD: как ускорить пайплайн без ложных срабатываний

20 ноября 2026 13 мин. чтения

Что даёт кэширование зависимостей и что именно кэшировать

Кэш возвращает пайплайну то, что он теряет между запусками: скачанные пакеты, собранные нативные модули, слои образа, редко меняющиеся бинарники. Ускорение появляется при одном условии: ключ кэша привязан к содержимому lock-файла. Ключ по номеру сборки или по текущей дате даёт либо постоянные промахи, либо устаревшие зависимости в сборке, которая при этом выглядит зелёной.

Дальше разбираем, что кэшировать в первую очередь, как построить ключ по lock-файлу, как это выглядит в GitLab CI и GitHub Actions, какие три ошибки чаще всего превращают кэш в источник ложных срабатываний и какими командами проверить результат.

Примеры записаны для конкретных окружений: GitLab CI с раннером Docker executor, GitHub Actions с actions/cache@v4, Node.js 22 и npm 10, Python 3.12 с pip 24. Синтаксис полей, пути и поведение кэша зависят от версии платформы и пакетного менеджера, поэтому сверяйте блок с документацией своего окружения перед копированием.

Почему без кэша пайплайн каждый раз начинает с нуля

Хостинговый раннер выдаёт чистую виртуальную машину или контейнер на каждый job. Каталоги ~/.npm, ~/.cache/pip, ~/.m2, ~/.gradle в нём пусты. Self-hosted раннер с Docker executor ведёт себя так же, пока вы не примонтируете volume или не включите кэш явно.

Время job складывается из четырёх частей: скачивание архивов пакетов, разрешение графа зависимостей, компиляция нативных модулей (node-gyp, сборка wheel из исходников) и post-install скрипты. Кэш убирает первую часть и часто третью. Разрешение зависимостей остаётся: пакетный менеджер всё равно сверяет lock-файл.

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

Пакетный менеджер, слои сборки и инструменты: что кэшировать в первую очередь

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

  1. Кэш пакетного менеджера. npm хранит архивы в ~/.npm (в GitLab CI удобно перенести его внутрь проекта флагом --cache .npm), pnpm — в store, путь к которому печатает pnpm store path, pip — в ~/.cache/pip (Linux, путь печатает pip cache dir), Maven — в ~/.m2/repository, Gradle — в ~/.gradle/caches и ~/.gradle/wrapper.
  2. Слои Docker-сборки. BuildKit кэширует промежуточные слои, и при неизменном слое с зависимостями повторная сборка не выполняет установку пакетов заново. Кэш экспортируется в registry или в хранилище CI (--cache-to type=registry, cache-to: type=gha для build-push-action). Порядок инструкций в Dockerfile разбираем отдельно в статье про кэширование слоёв Dockerfile.
  3. Инструменты сборки. Бинарники линтеров, плагины Terraform, компиляторы и SDK меняются редко, поэтому их каталоги стоит кэшировать с ключом, включающим версию инструмента. Изменение версии должно менять ключ, иначе вы получите старый бинарник при обновлённом конфиге.

Кэш node_modules целиком оправдан не всегда. При частой смене lock-файла и нативных модулях выгоднее кэшировать store пакетного менеджера: он переносимее и менее чувствителен к различиям окружений.

Что кэшироватьЧто не кэшироватьПочему
Store npm, pnpm, yarn, pip, Maven, GradleСекреты, .env, приватные ключиКэш читают другие job и ветки, секрет в нём превращается в утечку
Слои Docker-сборкиАртефакты сборки (dist/, target/)Результат должен пересобираться из текущего кода, иначе тесты проверяют прошлый коммит
Бинарники линтеров, плагины Terraform, SDKnode_modules при ежедневной смене lock-файлаПочти не экономит время и повышает риск несовместимости нативных модулей
Каталог загрузок пакетного менеджера с ключом по версииЛоги, отчёты покрытия, временные файлыРастут каждый запуск, вытесняют полезные записи из кэша

Ключ кэша по lock-файлу: как сделать инвалидацию предсказуемой

Ключ кэша должен зависеть от содержимого lock-файла: package-lock.json, pnpm-lock.yaml, yarn.lock, poetry.lock, pom.xml, а для pip — от файла с зафиксированными версиями и хешами. Схема простая: префикс с именем пакетного менеджера и окружения плюс хеш lock-файла. Ключ вида npm-linux-<хеш package-lock.json> меняется только тогда, когда меняется набор зависимостей.

Хешируйте lock-файл, а не manifest. В package.json или pyproject.toml версии часто заданы диапазонами, и файл не меняется при обновлении транзитивных зависимостей. Кэш при этом останется прежним, а сборка будет ссылаться на старые пакеты.

Промах после правки lock-файла — ожидаемое поведение, а не ошибка. Первый запуск после обновления зависимостей будет медленнее, зато второй снова попадёт в кэш.

Почему ключ по номеру сборки или по дате не работает

Два антипаттерна дают противоположные и одинаково неприятные результаты.

  • Ключ, который никогда не меняется. Например, константа npm-cache или ключ по имени проекта. Кэш не инвалидируется, в сборку попадают устаревшие зависимости, тесты проходят на старом дереве пакетов и дают ложноположительный результат.
  • Ключ, который меняется каждый запуск. Номер сборки, CI_PIPELINE_ID, текущая дата. Промах гарантирован всегда: кэш записывается, но не переиспользуется, а время тратится на сохранение и загрузку архива.

Хеш lock-файла снимает обе проблемы: ключ стабилен между запусками и меняется ровно при изменении зависимостей.

Fallback-ключи и частичное восстановление кэша

После обновления lock-файла точный ключ промахивается, и job качает всё с нуля. Частично ускорить первый запуск помогают fallback-ключи: при промахе CI ищет запись по префиксу ключа, восстанавливает её, а пакетный менеджер докачивает недостающие версии. В GitHub Actions это restore-keys, в GitLab CI — cache:key:prefix вместе с cache:key:files.

Осторожность нужна в двух местах. Fallback подходит для пакетных менеджеров, которые корректно доустанавливают пакеты поверх частичного store: npm, pnpm и pip с этим справляются, а вот нативные модули, собранные под другую версию ABI Node.js или другой дистрибутив, могут дать ошибку при загрузке. Второй момент: слишком широкий префикс притягивает кэш чужой ветки. Ограничивайте префикс именем пакетного менеджера, ОС и, если нужно, веткой.

key: npm-Linux-${{ hashFiles('package-lock.json') }}
restore-keys: |
  npm-Linux-

Синтаксис и поддержка fallback зависят от платформы, проверьте поля по документации вашей версии CI.

Кэш зависимостей в GitLab CI: пример конфигурации

В GitLab CI кэш описывается секцией cache в job. Поля cache:key:files, cache:paths и cache:policy поддерживаются давно, но нюансы слияния при extends стоит сверить с версией вашего GitLab.

.npm_cache:
  cache:
    key:
      files:
        - package-lock.json
      prefix: npm-$CI_COMMIT_REF_SLUG
    paths:
      - .npm/
    policy: pull-push

build:
  extends: .npm_cache
  stage: build
  image: node:22
  script:
    - npm ci --cache .npm --prefer-offline --no-audit
    - npm run build
  artifacts:
    paths:
      - dist/

test:
  extends: .npm_cache
  stage: test
  image: node:22
  cache:
    policy: pull
  script:
    - npm ci --cache .npm --prefer-offline --no-audit
    - npm test

Что здесь важно:

  • cache:key:files заставляет GitLab вычислить новый ключ кэша при изменении содержимого перечисленных файлов. Пока содержимое не меняется, ключ остаётся неизменным между ветками и пайплайнами, поэтому кэш переиспользуется. При изменении файла вычисляется новый ключ и создаётся новый кэш, который подхватывают последующие запуски (CI/CD YAML syntax reference, GitLab Docs).
  • Ключ по файлам строится на SHA от последнего коммита для каждого указанного файла; несуществующие файлы при расчёте игнорируются. Поэтому опечатка в имени файла не даст ошибку, но и не привяжет ключ к нужному lock-файлу — проверяйте имена.
  • prefix с CI_COMMIT_REF_SLUG привязывает кэш к ветке. Без префикса кэш с одинаковым ключом доступен разным веткам, и зависимость из feature-ветки может попасть в сборку main.
  • policy: pull в тестах экономит время: job только читает кэш и не пытается перезаписать его наперегонки с другими job. Запись оставьте одному job с pull-push.
  • cache и artifacts решают разные задачи. Кэш ускоряет повторные запуски и не гарантирует наличие файлов, артефакты передают результат сборки между job и хранятся как результат пайплайна.

По умолчанию защищённые и незащищённые ветки не разделяют кэш: разделение кэшей для защищённых веток — это функция безопасности, и она включена. Отключить её можно в настройках проекта, сняв опцию раздельных кэшей для защищённых ветвей, — тогда все ветки используют один кэш (Caching in GitLab CI/CD, GitLab Docs). Отключайте осознанно: общий кэш удобнее для попаданий, но снимает изоляцию, которая не даёт незащищённой ветке влиять на кэш, читаемый защищённой веткой.

Проверка: откройте лог job и найдите строки со словом cache. При попадании раннер пишет, что проверяет кэш по ключу и успешно распаковывает архив, при промахе сообщает об отсутствии записи, после job появляется сообщение о создании кэша. Формулировки различаются между версиями раннера, ориентируйтесь на ключ кэша в строке и на слово cache.

Кэширование в GitHub Actions: пример с actions/cache

Для Node.js проще всего встроенный кэш setup-node: он сам считает ключ по lock-файлу и восстанавливает store npm.

- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: npm
    cache-dependency-path: package-lock.json

Ручной вариант через actions/cache@v4 даёт контроль над ключом и путями. Версию экшена фиксируйте: синтаксис между мажорными версиями меняется.

- name: Cache npm store
  uses: actions/cache@v4
  with:
    path: ~/.npm
    key: npm-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
    restore-keys: |
      npm-${{ runner.os }}-

- name: Install dependencies
  run: npm ci --prefer-offline --no-audit

Проверьте шаблон пути: **/package-lock.json нужен только для монорепозитория, в обычном проекте достаточно package-lock.json. Если шаблон не совпадает ни с одним файлом, ключ теряет привязку к lock-файлу и совпадает у всех запусков — это ровно тот антипаттерн с устаревшими зависимостями. Поведение hashFiles при отсутствии совпадений сверяйте с документацией вашей версии GitHub Actions.

restore-keys проверяются последовательно: если ключ не совпал напрямую, выполняется поиск ключей с префиксом ключа восстановления, а при нескольких частичных совпадениях возвращается последний созданный кэш. Поэтому порядок и ширина префиксов в списке влияют на то, какой кэш вы получите (Справочник по кэшированию зависимостей, GitHub Docs).

Область видимости в GitHub Actions устроена иначе, чем в GitLab CI: кэш ограничен ключом, путями и веткой, а кэш ветки по умолчанию доступен другим веткам (actions/cache, GitHub). Кэш, созданный при запуске workflow по pull request, создаётся для ссылки слияния и может быть восстановлен только повторным запуском того же pull request — базовой веткой или другими pull request'ами он не подхватывается.

Хранилище кэша тоже ограничено. GitHub удаляет записи, к которым не обращались более 7 дней. По умолчанию общий размер всех кэшей в репозитории ограничен 10 ГБ, и этот лимит могут увеличить владельцы enterprise/организации или администраторы репозитория. При достижении максимума действует политика вытеснения: кэши удаляются в порядке даты последнего доступа от самой старой к самой новой, а новый кэш сохраняется (Dependency caching reference, GitHub Docs). В настройках GitHub Actions для репозитория можно задать срок хранения кэшей (по умолчанию 7 дней, до 90 дней для публичных и до 365 дней для приватных и внутренних репозиториев) и лимит вытеснения размера кэша (по умолчанию 10 ГБ, до 10 000 ГБ на репозиторий) (Управление настройками GitHub Actions для репозитория, GitHub Docs).

Проверка: в логе шага кэширования ищите строки с ключом. При попадании появляется сообщение о восстановлении кэша с конкретным ключом, при промахе — сообщение, что кэш по указанным ключам не найден, а в пост-шаге job будет запись о сохранении. Практический тест: запустите workflow дважды без правок, затем измените версию одной зависимости в package-lock.json и убедитесь, что третий запуск промахнулся.

Для Docker-сборки в Actions кэш слоёв укладывается в хранилище GitHub через buildx и build-push-action с cache-to: type=gha. Схему для нескольких сервисов и registry разбираем в материале про кэширование в Docker и Kubernetes.

Типичные ошибки кэширования и как их избежать

Три конфигурации дают большинство инцидентов: кэш без инвалидации, секреты внутри кэшируемых путей и общий кэш для всех ветвей.

Кэш без инвалидации: почему сборка «зелёная», а зависимости старые

Сценарий: lock-файл обновили, ключ кэша остался прежним, job восстановил старый store и поставил пакеты из него. Тесты прошли, релиз ушёл, а на проде другая версия библиотеки. Риск в том, что такой сбой не виден в логах: job зелёный, время пайплайна даже улучшилось.

Исправление: ключ по хешу lock-файла и версия в префиксе для ручного сброса (npm-v2-...). Дополнительно проверяйте, что после установки версия критичной зависимости совпадает с ожидаемой, например через npm ls <пакет> или вывод pip freeze в лог.

Секреты в кэше: как не превратить ускорение в утечку

В кэш не должны попадать .env, файлы с токенами, приватные ключи, конфиги с паролями, а также каталоги, куда пакетный менеджер или скрипт складывает учётные данные (.npmrc с токеном registry, pip.conf с паролем).

Кэш читают другие job и, при совпадении ключа, другие ветки. Токен, осевший в кэше, доступен тому, кто может запустить пайплайн в этом репозитории, а также тому, кто читает хранилище кэша напрямую.

Держите секреты в защищённых переменных CI и передавайте их в момент выполнения, не записывая на диск в кэшируемых путях. В примерах используйте очевидные заглушки:

npm config set //registry.example.com/:_authToken "${NPM_TOKEN_PLACEHOLDER}"

Заглушка ${NPM_TOKEN_PLACEHOLDER} демонстрирует синтаксис, реальный токен подставляется из переменной CI и в репозиторий не попадает. Если пакетный менеджер пишет токен в файл в домашней директории, исключите этот файл из путей кэша.

Грязный кэш между ветками: изоляция и область видимости

Общий ключ для всех ветвей приводит к невоспроизводимым сборкам: в main приезжает store, собранный в feature-ветке, а там могли быть другие версии транзитивных зависимостей или пакеты из локального registry.

Привязывайте ключ к ветке (CI_COMMIT_REF_SLUG в GitLab CI, github.ref_name в GitHub Actions) и используйте раздельные кэши для защищённых ветвей. Компромисс очевиден: изоляция по веткам снижает долю попаданий, зато результат сборки перестаёт зависеть от чужих экспериментов. Для долгоживущих веток допустим общий префикс по ветке, для коротких feature-веток хватает точного ключа по lock-файлу.

Как проверить, что кэш работает и не даёт ложных срабатываний

Проверка занимает три шага и не требует отдельных инструментов.

  1. Базовая линия. Выключите кэш и прогоните пайплайн 3 раза подряд на одинаковом коммите. Запишите длительность job установки зависимостей и общую длительность пайплайна. Три запуска нужны, чтобы отсечь разброс сети раннера.
  2. Замер с кэшем. Включите кэш и повторите 3 запуска. Второй и третий должны попадать в кэш; первый после включения кэша попадать не может, записи ещё нет.
  3. Проверка инвалидации. Измените одну версию в lock-файле, запустите пайплайн и убедитесь, что кэш промахнулся, а после job сохранился под новым ключом.

Попадание в кэш определяется по логу job: ищите ключ кэша и слова cache, restored, extracted, not found, cache is empty. Точные формулировки отличаются между версиями GitLab Runner, GitHub Actions и экшенов, поэтому ориентируйтесь на свой ключ в строке лога, а не на заученную фразу.

ЭтапВремя до кэшаВремя послеПопадание в кэш
Установка зависимостейзамер 1замер 2hit по ключу с хешем lock-файла
Сборка проектазамер 1замер 2не кэшируется, время не должно падать
Тестызамер 1замер 2hit, политика pull
Первый запуск после смены lock-файлазамер 1замер 2miss, ожидаемо

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

Для диагностики неожиданных промахов и устаревших данных пригодится материал про ошибки кэширования и их диагностику.

Чек-лист и когда кэш лучше отключить

Проверьте пункты перед включением кэша в общий пайплайн.

  • Ключ кэша содержит хеш lock-файла, а не номер сборки, дату или константу.
  • В путях кэша нет .env, .npmrc с токеном, приватных ключей и каталогов с учётными данными.
  • Область видимости ограничена: префикс по ветке или раздельные кэши для защищённых ветвей.
  • Есть ручной сброс: версия в префиксе ключа (npm-v2-...) увеличивается одной строкой.
  • Проверены попадание и промах по логу, а также поведение после правки lock-файла.
  • Время пайплайна измерено до и после на 3 запусках.
  • Запись кэша выполняет один job, остальные работают с политикой чтения.

Кэш вредит в трёх случаях. На очень коротких пайплайнах, где сохранение и распаковка архива занимают столько же времени, сколько установка пакетов. В проектах с ежедневной сменой lock-файла, где почти каждый запуск промахивается. И там, где нужна абсолютная воспроизводимость с нуля, например в аудите релизной сборки: тогда имеет смысл отдельный пайплайн без кэша.

Ручной сброс выполняйте осознанно. В GitLab CI кэш раннеров очищается кнопкой в настройках CI/CD проекта, в GitHub Actions кэш удаляется через интерфейс или командой gh cache delete --all (свериться с версией gh CLI). Обе операции затрагивают все кэши проекта или репозитория: ближайшие пайплайны пойдут без кэша и станут медленнее, а другие команды получат точно такое же замедление. Если нужно точечно, меняйте версию в префиксе ключа вместо полной очистки.

Поделиться: