Кэш, matrix-сборки и артефакты

Кэш: хэш lockfile — единственный безопасный key

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

Каждый CI-job бежит на чистой машине, поэтому без помощи он заново делает каждый дорогой детерминированный шаг — прежде всего установку зависимостей — с нуля на каждый запуск. actions/cache это чинит: сохраняет директорию после первого запуска и восстанавливает на последующих по выбранной тобой строке-ключу. Кардинальное правило живёт целиком в этом key: он должен меняться ровно тогда, когда должно поменяться кэшируемое содержимое, и не раньше. Для зависимостей вход, определяющий node_modules, — это lockfile, поэтому его и хэшируют.

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

hashFiles('**/package-lock.json') даёт чек-сумму, которая меняется в тот же миг, когда меняется любая зависимость. При попадании cache восстанавливается и установка почти мгновенна; при промахе — новый lockfile — key новый, поэтому старая запись не переиспользуется, ты ставишь начисто, и запуск сохраняет новую запись под новым ключом. Вот почему константный key: deps опасен: он никогда не может промахнуться, поэтому восстанавливает протухшие зависимости вечно, а твой новый lockfile молча игнорируется. Всегда привязывай key к содержимому.

restore-keys — это лестница отката. Когда точный key промахивается, GitHub перебирает каждый префикс по очереди и восстанавливает самое свежее частичное совпадение — так что апдейт lockfile всё равно засевает cache из предыдущей записи runner.os-npm-, а не начинает с пустого, и пакетный менеджер качает только дельту. Это тёплый старт, а не шорткат для корректности: точный key по-прежнему решает, считается ли запись актуальной.

Matrix: одно определение job, много параллельных запусков

Как доказать, что библиотека работает на Node 18, 20 и 22, не копипастя три почти одинаковых job? Именно эту задачу решает strategy.matrix.

strategy.matrix запускает один и тот же job по разу на каждую комбинацию перечисленных измерений — стандартный способ доказать, что код работает на разных версиях Node и ОС, без копипасты job’ов. GitHub разворачивает декартово произведение и планирует каждую комбинацию параллельно.

test:
  strategy:
    fail-fast: false
    max-parallel: 4
    matrix:
      node: [18, 20, 22]
      os: [ubuntu-latest, macos-latest]
      include:
        - { node: 22, os: ubuntu-latest, coverage: true }
      exclude:
        - { node: 18, os: macos-latest }
  runs-on: ${{ matrix.os }}
  steps:
    - uses: actions/setup-node@v4
      with: { node-version: ${{ matrix.node }} }

Эта сетка node × os — это 3 × 2 = 6 job’ов; exclude убирает один, include добавляет лишнее поле к одной существующей комбинации (а с новым значением мог бы добавить и целый job). fail-fast: true (по умолчанию) отменяет всех соседей в момент первого падения — быстрая обратная связь, но ты теряешь полную картину; ставь false, когда нужно увидеть, какие именно комбинации сломались. max-parallel ограничивает, сколько бежит одновременно, дросселируя параллельное использование раннеров. Помни о взрыве: измерения умножаются, поэтому добавление третьей оси на 3 значения превращает 6 job’ов в 18, и каждый ест минуты раннера — matrix это ручка стоимости, а не бесплатное покрытие. Вместе эти ручки дают полный кросс-версионный сигнал из одного определения job; без fail-fast: false одна сломанная ячейка Node 18 может скрыть три других падающих комбинации под собой.

Артефакты: передай вывод из одного job в следующий

Поскольку каждый job — это свежая машина, сборка, собранная в одном job, не существует в следующем — файловая система пропадает, когда job завершается. Cache здесь неправильный инструмент: это keyed, best-effort, возможно-вытесненное ускорение, а не гарантированная передача. Артефакты — правильный инструмент: явные, надёжные-в-пределах-запуска выводы, которые ты загружаешь и потом скачиваешь и которые можешь публиковать как результаты запуска (собранный бандл, отчёты тестов, покрытие).

build:
  steps:
    - run: npm run build
    - uses: actions/upload-artifact@v4
      with: { name: dist, path: dist/ }
deploy:
  needs: build
  steps:
    - uses: actions/download-artifact@v4
      with: { name: dist }
    - run: ./deploy.sh dist/

Собрал один раз — деплой ровно те же байты, что ты тестировал, без дрейфа пересборки между job’ами. У артефактов есть период хранения (по умолчанию 90 дней, настраивается) и они учитываются в хранилище, поэтому называй их осознанно, а большие держи недолго.