GitHub Actions + Vercel: CI/CD для новичка пошагово

Быстрый вывод

Для простого сайта обычно достаточно Vercel Git integration: push в GitHub создает preview/production deployments без отдельного workflow.

GitHub Actions нужен, если вы хотите сначала запускать lint, build, tests и только после этого разрешать деплой.

Главное решение: либо Vercel сам деплоит из GitHub, либо Actions делает явный `vercel deploy`, либо Actions только проверяет код, а деплой остается за Vercel.

Что такое CI/CD

CI/CD — это автоматизированный процесс проверки, сборки и деплоя проекта после изменений в репозитории.

Упрощенно: вы пушите код, система выполняет шаги и публикует результат по заданным правилам.

• CI: проверки и сборка
• CD: доставка и деплой
• Контроль качества до production

Как связаны GitHub Actions и Vercel

GitHub Actions отвечает за workflow в репозитории: когда запускать, какие команды выполнять и какие условия применять.

Vercel отвечает за сборку и публикацию Next.js-приложения, включая preview и production окружения.

Встроенная GitHub-интеграция Vercel уже покрывает базовый автодеплой. Actions добавляет слой проверок и управляемого процесса.

Когда хватает обычного автодеплоя Vercel

Для простых проектов часто достаточно встроенной интеграции GitHub → Vercel без отдельного workflow.

GitHub Actions становится нужен, когда требуется дополнительный контроль: кастомные шаги, свои проверки и единый pipeline.

Если вы только учитесь деплоить сайт, сначала разберите базовый процесс: Как деплоить сайт через Vercel: инструкция для новичка.

Когда GitHub Actions не нужен

В этом случае отдельный workflow может не усилить проект, а добавить еще одну точку отказа.

• Проект простой и стандартно деплоится через Vercel Git integration.
• Нет тестов, typecheck или дополнительных проверок.
• Вы не готовы безопасно работать с secrets и permissions.
• Нужны только preview deployments для pull request.
• В команде нет процесса review и protected branches.

Когда GitHub Actions действительно нужен

• Нужно запускать lint, typecheck, tests и build до production.
• Нужно блокировать deploy при падении проверок.
• Есть monorepo или нестандартный build.
• Нужны security checks или audit steps.
• Production deploy должен быть ручным или защищенным.
• Нужно использовать Vercel CLI с prebuilt deployment.

Что делает GitHub Actions

• Запуск на push и pull request
• Установка зависимостей
• Запуск lint и build
• Запуск тестов и typecheck, если они есть
• Условный deploy по веткам и правилам
• Остановка pipeline до production, если проверки упали

Что делает Vercel

• Сборка Next.js-проекта
• Preview Deploy для проверки изменений
• Production Deploy для main-ветки
• Управление окружениями и проектными настройками
• Хранение Vercel project settings и environment variables

Безопасная схема pipeline

Эта схема отделяет качество кода от публикации. Если build падает, сначала используйте диагностику Ошибки сборки на Vercel: как исправлять через Codex.

• Checkout repository.
• Setup Node.js.
• Install dependencies.
• Run lint.
• Run typecheck/tests, если они есть.
• Run build.
• Deploy только после успешных проверок.
• Preview для pull request, production только для основной ветки.

Пошаговая настройка для новичка

Лучше начинать с минимального и стабильного пайплайна.

1. Подготовить проект локально

Если локальная сборка нестабильна, CI/CD только зафиксирует эту проблему, но не решит ее.

Перед автоматизацией полезно пройти Как тестировать код от Codex без глубокого программирования.

• npm install
• npm run lint
• npm run build

2. Подключить репозиторий к GitHub

GitHub Actions живет внутри репозитория, поэтому проект должен быть в GitHub с понятной веточной стратегией.

3. Создать workflow файл

Workflow хранится в папке `.github/workflows` и описывает, когда и какие шаги запускать.

Файл должен быть понятным и минимальным. Не начинайте с огромного pipeline, если проект еще не проходит базовые проверки.

4. Запустить базовый pipeline

• Trigger: push / pull_request
• Install dependencies
• Run lint
• Run build
• Deploy только после success

5. Подключить Vercel CLI

Для кастомного CI/CD часто используют Vercel CLI, чтобы явно управлять шагами сборки и деплоя в workflow.

Если Vercel Git integration уже делает deploy, не добавляйте второй deploy через Actions без ясной причины — иначе получите дублирующиеся deployments.

6. Настроить GitHub Secrets

Секреты хранятся в настройках GitHub, а не в коде репозитория.

Не печатайте secrets в workflow logs. Для Vercel env отдельно проверьте Environment Variables на Vercel: как не сломать прод.

• VERCEL_TOKEN
• VERCEL_ORG_ID
• VERCEL_PROJECT_ID
• Дополнительные API keys только если они реально нужны workflow

7. Разделить preview и production

Безопасная схема: ветки и PR деплоятся в preview, а `main` — в production.

Для production используйте protected branch, review rules или manual approval, если проект уже получает трафик.

8. Добавить обязательные проверки перед деплоем

• Lint
• Build
• Typecheck, если есть
• Tests, если есть
• Базовые smoke-checks при необходимости

9. Понять схему vercel pull → vercel build → vercel deploy --prebuilt

Эта цепочка позволяет собирать проект в CI под вашим контролем и отправлять в Vercel уже готовый prebuilt-артефакт.

Минимальный workflow пример

Ниже не универсальный файл для всех проектов, а пример структуры. Команды должны совпадать с вашим `package.json`.

`name: Checks`, `on: [push, pull_request]`, `permissions: contents: read`, затем steps: `actions/checkout`, `actions/setup-node`, `npm ci`, `npm run lint`, `npm run build`.

Deploy-шаг добавляйте только если вы сознательно выбрали explicit deploy через Vercel CLI. Если deploy делает Vercel Git integration, оставьте workflow только для проверок.

GitHub Actions permissions

Минимальное правило: workflow не должен получать write-доступ без необходимости.

Для обычных проверок достаточно `contents: read`. Write permissions, deployments permissions и доступ к secrets добавляйте только под конкретную задачу.

Особенно аккуратно работайте с pull request из внешних forks: secrets не должны уходить в недоверенный код.

10. Сначала проверить на preview

Перед production важно убедиться, что workflow стабильно проходит на pull request и preview-ссылках.

Пример рабочей логики CI/CD

• Создаете feature-ветку
• Push запускает GitHub Actions
• Workflow делает lint/build и preview deploy
• Проверяете результат
• Merge в main запускает production deploy

Три безопасные модели

Для большинства сайтов сначала достаточно модели 1 или 2. Модель 3 нужна, когда вы осознанно переносите контроль сборки в CI.

• Модель 1: Vercel Git integration делает все деплои, GitHub Actions не используется.
• Модель 2: GitHub Actions делает только checks, а Vercel деплоит после push/merge.
• Модель 3: GitHub Actions делает checks, `vercel build` и `vercel deploy --prebuilt`.

Где это применяется

• Next.js проекты на Vercel
• AI и контентные продукты
• Сервисные сайты и блоги
• Командная разработка с pull request-процессом

Частые ошибки

• Собирать сложный pipeline до стабильного проекта
• Не проверять локальный build перед CI/CD
• Хранить токены вне secrets
• Смешивать preview и production
• Деплоить в прод без проверки preview
• Одновременно включить Vercel autodeploy и явный Actions deploy без правил
• Дать workflow лишние write-permissions
• Печатать secrets в logs

Ошибки workflow

Если workflow падает на установке зависимостей, проверьте lockfile и Node.js version.

Если падает build, сначала смотрите первую ошибку в logs и сверяйте с локальным `npm run build`.

Если deploy не проходит из Actions, проверьте `VERCEL_TOKEN`, `VERCEL_ORG_ID`, `VERCEL_PROJECT_ID`, связку проекта и наличие нужных env variables.

Supply chain security

GitHub Actions выполняет код из репозитория и сторонних actions, поэтому важно использовать проверенные official actions и не запускать случайные команды.

Перед добавлением нового action проверьте источник, версию, permissions и нужен ли он вообще.

Секреты Vercel, GitHub, API и базы данных не должны попадать в YAML, public logs или ответы AI-ассистента.

Почему это важно

GitHub Actions + Vercel дает воспроизводимый процесс: меньше ручных ошибок, быстрее обратная связь и безопаснее выкладка.

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

Вывод

CI/CD — это практичная последовательность шагов, а не сложная DevOps-магия.

Начинайте с простого workflow, отдельно настраивайте preview и production, не дублируйте деплои и усложняйте pipeline только по мере роста проекта.

Если нужна общая схема работы с AI-разработкой, GitHub и деплоем, изучите полный workflow Codex + GitHub + Vercel.