Артефакты и кэш: передача файлов между джобами и кэш, который не попадает

Артефакты против кэша: две разные задачи

Они выглядят похоже — оба хранят файлы — но решают противоположные проблемы:

• Артефакты выносят файлы из workflow: выходы сборки, тест-отчёты, coverage, логи — то, что человек или поздний джоб скачивает. Загружай через actions/upload-artifact, забирай через actions/download-artifact. Это единственный способ передать файлы между джобами, ведь каждый джоб выполняется на свежем раннере. Дефолтное хранение — 90 дней (настраивается per-upload вниз до 1 дня или задаётся на весь репозиторий), после чего они удаляются.
• Кэш ускоряет будущие запуски той же работы: каталоги зависимостей (~/.npm, node_modules, ~/.cargo), промежуточные результаты сборки. Используй actions/cache. Запись кэша ключуется и неизменяема после записи — и она best-effort (по возможности, без гарантии), не гарантирована: по политике вытеснения GitHub удаляет кэши, не запрашивавшиеся 7 дней, и когда кэши репозитория превышают 10 ГБ суммарно, он вытесняет least-recently-used записи, чтобы остаться под лимитом.

Ментальное правило: артефакт = «мне нужен этот файл позже или человеку», кэш = «пересчёт этого медленный, а входы редко меняются». Никогда не используй кэш для выходов сборки, которые нельзя терять (он может быть вытеснен в любой момент); никогда не используй артефакты как кэш скорости (нет restore по ключу, а 90-дневное хранение стоит места).

- uses: actions/upload-artifact@v4
  with:
    name: dist
    path: build/
    retention-days: 7      # сократи с дефолта 90 дней для эфемерных сборок

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

Ключ кэша — это весь дизайн

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

• key должен включать хэш содержимого входов — hashFiles('**/package-lock.json'). Когда lockfile меняется, хэш меняется, ключ меняется, и старый кэш правильно не используется. Ключ без хэша (key: npm из Hook) никогда не меняется, поэтому либо служит устаревшим кэшем вечно, либо — раз записи неизменяемы — фиксирует то, что сохранено первым.
• restore-keys — упорядоченный список префиксов, пробуемых при промахе точного key. При изменении lockfile точный ключ ещё не существует, но restore-keys: npm-${{ runner.os }}- совпадает с предыдущим кэшем как частичное попадание — так ты стартуешь от node_modules прошлой сборки и устанавливаешь только дельту, затем сохраняешь под новым точным ключом. Это и превращает холодный кэш в тёплый сквозь подъёмы зависимостей.

Семантика сохранения ловит людей: actions/cache сохраняет автоматически в конце джоба только если точный key ещё не существовал (попадание по точному ключу означает отсутствие сохранения). Неизменяемость означает, что нельзя перезаписать запись — чтобы «обновить» кэш, надо изменить ключ. А из-за вытеснения по 7-дневному простою и 10 ГБ-LRU кэш редко запускаемого workflow может просто исчезнуть, что правильное поведение, а не баг — кэш это оптимизация, обязанная терпеть промахи.

Размеры и гигиена

Кэши и артефакты оба стоят места и оба имеют лимиты, кусающие на масштабе. Одна запись кэша должна быть каталогом зависимостей, а не всем workspace — кэширование node_modules плюс ~/.npm плюс выхода сборки утраивает размер и толкает к 10 ГБ-LRU-обрыву быстрее, вытесняя другие полезные кэши. Артефакты по умолчанию хранятся 90 дней, что для per-PR выходов сборки расточительно; сократи retention-days до недели или меньше для эфемерных данных, а долгое хранение оставь релизам и аудит-логам. Сжимай перед загрузкой крупных артефактов и вообще не загружай node_modules как артефакт — для этого есть кэш. Дисциплина — сопоставлять каждое хранилище его задаче: долговечная передача → артефакт с намеренным хранением; оптимизация скорости с терпимыми промахами → кэш с ключом, хэширующим содержимое.