CI/CD на GitHub Actions: сборка и деплой сайта

GitHub Actions может собирать сайт при каждом pull request, а после слияния изменений в main — публиковать его на GitHub Pages. Ниже — рабочая схема для статического проекта на Node.js: сборка выполняется на Node.js 22, а готовая папка передаётся в отдельную задачу деплоя. Настройка подходит для типичного проекта с командами npm ci и npm run build; для сайта на другом стеке замените только шаг сборки.

Что именно мы автоматизируем

В workflow будут две задачи. Первая запускается и для pull request, и для push в main: устанавливает зависимости, собирает сайт и сохраняет результат как артефакт. Вторая запускается только после push в main и публикует артефакт на Pages.

Это разделение важно: pull request должен подтвердить, что проект собирается, но не должен выкладывать непроверенные изменения на публичный сайт. При этом деплой получает ровно тот результат, который собрал первый job, а не запускает сборку заново.

Артефакт — сохранённый файл или каталог, который одна задача CI передаёт другой. В нашем случае это собранные HTML, CSS и JavaScript из папки dist.

Сборка отвечает на вопрос «можно ли получить сайт из этого коммита?», а деплой — «какой именно коммит сейчас опубликован?» Не смешивайте проверку pull request с публикацией.

Три способа связать сборку и публикацию

Дальше используем второй вариант: встроенные официальные Actions для GitHub Pages. Если вашему приложению нужен серверный процесс, Pages не заменит хостинг — схема доставки на внешний сервер зависит от его протокола и инфраструктуры.

Workflow для GitHub Pages

Перед добавлением файла проверьте условия: в репозитории есть package-lock.json, скрипт build создаёт папку dist, а Node.js 22 подходит проекту. Если ваша система сборки складывает результат в другую папку, замените dist в файле. Создайте .github/workflows/deploy.yml и добавьте workflow:

name: Build and deploy

on:
  pull_request:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Build site
        run: npm run build

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: dist

  deploy:
    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Configure Pages
        uses: actions/configure-pages@v5

      - name: Deploy to Pages
        id: deployment
        uses: actions/deploy-pages@v4

Файл использует актуальные major-версии указанных Actions на момент подготовки материала: checkout@v4, setup-node@v4, upload-pages-artifact@v3, configure-pages@v5 и deploy-pages@v4. Перед внедрением проверьте их текущие версии в официальной документации и закрепляйте версии по правилам безопасности вашей команды.

Настройка репозитория и первая проверка

1. Добавьте workflow в основную ветку. Сохраните файл по пути .github/workflows/deploy.yml и отправьте commit в main. Проверка: в репозитории появилась вкладка Actions, а workflow стартовал после push.
2. Выберите источник публикации. Откройте настройки репозитория, раздел Pages, и укажите GitHub Actions как способ сборки и публикации. Проверка: в настройках Pages выбран workflow-процесс, а не ветка с готовыми файлами.
3. Проверьте, что сборка создаёт нужную папку. Запустите локально те же команды, что указаны в workflow: npm ci, затем npm run build. Проверка: появилась папка dist с главной страницей и ресурсами. Если проект создаёт build, исправьте путь в workflow.
4. Откройте завершённый запуск. В Actions проверьте шаги установки, сборки и загрузки артефакта. Проверка: job build завершился успешно; при push в main после него прошёл job deploy, а адрес сайта указан в результате публикации.
5. Проверьте pull request отдельно. Создайте ветку и откройте PR в main. Проверка: workflow собирает проект, но job публикации пропускается. После слияния в main начинается деплой.

Когда workflow ломается

Сборка не видит lock-файл

Команда npm ci завершится ошибкой, если в репозитории нет package-lock.json или он не соответствует package.json. Добавьте lock-файл в репозиторий и обновите его вместе с изменениями зависимостей. Не заменяйте команду молча на npm install: это может сделать состав установленных пакетов менее предсказуемым.

Артефакт не найден или пуст

Проверьте, куда именно ваша сборка складывает результат. Путь dist — настройка примера, а не универсальное имя каталога. В логе должен успешно завершиться шаг создания артефакта; если генератор создаёт, например, другую папку, передайте её в параметр path.

Сайт опубликован, но изображения или ссылки ведут не туда

Для проекта, опубликованного не в корне домена, сборщику часто нужно знать базовый путь сайта. GitHub Pages может размещать проектный сайт по адресу с именем репозитория в пути. Настройка базового URL зависит от используемого генератора: найдите параметр base path в его документации и проверьте ссылки именно на опубликованной странице.

Deploy завершился ошибкой доступа

Проверьте, что в настройках репозитория включена публикация через GitHub Actions, а workflow запрашивает разрешения pages: write и id-token: write. Если доступ ограничивает политика организации, потребуется помощь администратора. Не выдавайте workflow дополнительные права «на всякий случай».

Границы схемы и следующий шаг

Этот workflow публикует статические файлы. Он не запускает серверное приложение и не переносит базу данных, загруженные пользователями файлы или конфигурацию хостинга. Для внешнего сервера отдельно спроектируйте доставку, хранение секретов и откат: не копируйте в репозиторий пароли и приватные ключи.

После первого успешного деплоя проверьте, как сайт ведёт себя при недоступном Pages и при ошибке сборки: предыдущая публикация должна оставаться доступной, если новая не прошла. Затем настройте правила защиты ветки main и требуйте успешную проверку workflow до слияния. Отдельная тема — деплой секретов и миграции базы данных; здесь мы разбирали только статическую публикацию.