GitHub Actions для Next.js: кэш, lint, typecheck, тесты и защита main
Цель
Ни один коммит не попадает в main, если не прошли линтер, проверка типов и тесты. Проверки идут быстро за счёт кэша и не жгут минуты на устаревших пушах. Ниже workflow и настройки репозитория, которые превращают его из рекомендации в обязательное условие.
Workflow
# .github/workflows/ci.yml
name: CI
on:
pull_request:
push:
branches: [main]
concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true
permissions:
contents: read
jobs:
quality:
name: lint-typecheck-test
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version-file: .nvmrc
cache: npm
- run: npm ci
- name: Lint
run: npm run lint
- name: Typecheck
run: npx tsc --noEmit
- name: Unit tests
run: npm test -- --run
build:
name: build
runs-on: ubuntu-latest
needs: quality
timeout-minutes: 20
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version-file: .nvmrc
cache: npm
- run: npm ci
- uses: actions/cache@v4
with:
path: .next/cache
key: nextjs-${{ runner.os }}-${{ hashFiles('package-lock.json') }}-${{ hashFiles('**/*.ts', '**/*.tsx') }}
restore-keys: |
nextjs-${{ runner.os }}-${{ hashFiles('package-lock.json') }}-
- run: npm run buildЧто здесь важно
`concurrency` с `cancel-in-progress`. Три пуша подряд в одну ветку запускают три прогона, нужен только последний. Группа по github.ref отменяет предыдущие для той же ветки или PR, но не трогает другие.
`permissions: contents: read`. По умолчанию GITHUB_TOKEN может получить права на запись. Для проверок они не нужны, и при компрометации зависимости, которая выполняется в CI, токен с минимальными правами ограничивает ущерб.
Кэш npm. setup-node с cache: npm кэширует глобальный кэш пакетов по хешу lock-файла. npm ci при этом всё равно ставит node_modules с нуля, но без скачивания из сети. Кэшировать сам node_modules не стоит: при смене версии Node нативные модули окажутся несовместимыми.
Кэш `.next/cache`. Next.js переиспользует результаты прошлой сборки. Ключ включает хеш исходников, а restore-keys позволяет взять самый свежий кэш с тем же lock-файлом, если точного совпадения нет. Без этого кэша next build в CI выводит предупреждение об его отсутствии.
`.nvmrc`. Одна версия Node локально и в CI. Расхождение версий — частая причина «у меня работает».
Скрипты в package.json
{
"scripts": {
"lint": "eslint .",
"typecheck": "tsc --noEmit",
"test": "vitest",
"build": "next build"
}
}Команда next lint в новых версиях Next.js объявлена устаревшей, поэтому линтер вызывается напрямую. next build сам проверяет типы, но отдельный шаг tsc --noEmit в первой задаче падает раньше и не тратит время на сборку.
Защита main
Workflow без правил репозитория — просто индикатор. Настройте ruleset (Settings → Rules → Rulesets) или классическую защиту ветки:
- 1.Require a pull request before merging — прямые пуши в
mainзапрещены. - 2.Require status checks to pass — добавьте проверки
lint-typecheck-testиbuild. Имена берутся из поляnameзадачи; если переименовать задачу, правило будет ждать проверку, которая больше никогда не придёт, и PR застрянет. - 3.Require branches to be up to date — PR проверяется с последним состоянием
main, а не с тем, от которого его когда-то отвели. - 4.Block force pushes и запрет удаления ветки.
- 5.Не добавляйте себя в обход правил «на всякий случай»: обход используется именно в тот вечер, когда тесты падают.
Безопасность workflow
- Событие
pull_requestдля PR из форков запускается без доступа к секретам — это правильно. Не меняйте его наpull_request_targetради секретов: там workflow выполняется в контексте базовой ветки с правами, и checkout кода из PR даёт чужому коду доступ к ним. - Сторонние actions закрепляйте по полному SHA коммита, а не по тегу: тег можно перевесить. Официальные
actions/*по мажорной версии — разумный компромисс. - Секреты для деплоя держите в Environments с обязательным подтверждением, а не в общих секретах репозитория.
Диагностика
- PR не мержится, проверка «Expected — Waiting for status». Имя обязательной проверки не совпадает с именем задачи, или workflow не запустился из-за фильтра
paths. Если workflow с фильтром путей не стартовал, обязательная проверка так и останется в ожидании. - Кэш не восстанавливается. Кэши изолированы по веткам: PR видит кэш своей ветки и базовой, но не соседних PR. Первый прогон в новой ветке всегда холодный.
- Тесты висят до таймаута. Vitest в режиме наблюдения ждёт изменений. В CI переменная
CI=trueвыставлена автоматически и Vitest это учитывает, но явный--runнадёжнее.
Когда этого достаточно, а когда нет
Для команды из пары человек этот набор закрывает основное. E2E-тесты на Playwright добавляются отдельной задачей с needs: build, когда появятся критичные пользовательские сценарии. Если CI занимает больше десяти минут, разбейте тесты на шарды через матрицу, а не отключайте их.