# Развёртывание сайта из Git

Source: https://support.kapsulehost.com/ru-ru/site-git-deploy

Git-деплой подключает репозиторий к сайту так, что каждый пуш в выбранную ветку клонирует код, запускает вашу сборку и публикует результат. Это руководство охватывает первоначальное подключение, два шага на стороне репозитория, завершающие настройку, чтение истории развёртываний и определение buildpack, которое решает, как собирается приложение на Node.js.

## Где находится Git-деплой

Откройте раздел **Сайты**, нажмите на сайт, откройте группу **Окружение** в левом меню сайта и выберите **Git-деплой**. Рядом находятся две связанные страницы:

- **Развёртывания**, полная история развёртываний для этого сайта, в той же группе **Окружение**.
- **Buildpack**, определённая стратегия сборки, для сайтов на Node.js, в группе **Приложения**.

Страница Git-деплоя прямо объясняет своё назначение: подключите репозиторий, и каждый пуш в настроенную ветку запускает сборку и развёртывание.

![Страница Git-деплоя для сайта в KPanel, где подключён репозиторий](https://support.kapsulehost.com/help/screenshots/site-git-deploy.4716f1a9.webp)

## Подключение репозитория

1. Выберите **Провайдера**: GitHub, GitLab или Bitbucket.
2. Введите **URL репозитория**. Вам нужна форма SSH, например `git@github.com:user/repo.git`.
3. Укажите **Ветку**, из которой будет выполняться развёртывание. По умолчанию в поле указано `main`.
4. При необходимости укажите **Команду сборки**, например `npm run build`.
5. При необходимости укажите **Выходной каталог**, например `dist`, `public` или `.` для репозитория, который уже собран.
6. Нажмите **Подключить репозиторий**.

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

### Дополнительные скрипты

Разворачивая раздел **Дополнительно**, вы увидите два дополнительных поля:

- **Скрипт перед развёртыванием**, который выполняется перед сборкой.
- **Скрипт после развёртывания**, который выполняется после развёртывания.

Используйте хук после развёртывания для действий, которые обязательно должны произойти после появления нового кода: очистка кеша приложения, выполнение миграции базы данных, перезапуск воркера.

### Автоматическое развёртывание при пуше

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

> **Tip:** Отключайте автоматическое развёртывание во время заморозки кода или инцидента, вместо того чтобы отключать репозиторий. Отключение репозитория приводит к удалению ключа развёртывания и секрета webhook, поэтому оба шага на стороне репозитория придётся выполнять заново.

## Завершение настройки в вашем репозитории

Подключение репозитория в KPanel это лишь первый из трёх шагов. Пока не выполнено ни одно развёртывание, страница показывает баннер с надписью **Завершить настройку: осталось 2 шага** и всем необходимым для этого.

### Шаг 2: добавьте ключ развёртывания

KapsuleHost нужен доступ на чтение, чтобы клонировать ваш репозиторий. Баннер показывает публичный ключ с кнопкой **Скопировать ключ**.

Вставьте его в ключи развёртывания вашего репозитория. Для GitHub баннер предлагает кнопку быстрого перехода **Добавить на GitHub** прямо на нужную страницу настроек. Достаточно доступа на чтение, не выдавайте доступ на запись.

### Шаг 3: добавьте webhook

Webhook сообщает KapsuleHost о том, что произошёл пуш. Баннер показывает три значения:

| Поле | Значение |
|---|---|
| URL полезной нагрузки | URL, заканчивающийся на `/api/git-deploy/webhook/` плюс идентификатор этого сайта |
| Секрет | Сгенерированный секрет подписи, скрытый до нажатия на значок «глаз» |
| Тип содержимого | `application/json` |

Скопируйте каждое значение в настройки webhook вашего репозитория. Для GitHub есть кнопка быстрого перехода **Добавить webhook на GitHub**. Установите тип содержимого JSON, а не значение по умолчанию с кодировкой формы, иначе полезная нагрузка не будет разобрана.

> **Warning:** Относитесь к секрету webhook как к паролю. Любой, у кого есть этот секрет и URL полезной нагрузки, может запустить развёртывание вашего сайта. Оба значения показываются только тем, кто уже может администрировать сайт, а секрет остаётся скрытым за значком «глаз», пока вы его не запросите.

## Развёртывание вручную

Нажмите **Развернуть сейчас** на странице Git-деплоя, чтобы собрать и развернуть текущую вершину настроенной ветки без пуша коммита. Это работает независимо от того, включено ли автоматическое развёртывание, именно поэтому это подходящий инструмент во время заморозки: пуши игнорируются, но вы всё равно можете выпустить исправление.

## Чтение истории развёртываний

Откройте **Окружение**, затем **Развёртывания**. Страница называется **История развёртываний** и перечисляет каждое развёртывание, запущенное webhook'ом или вручную, начиная с самого нового.

Каждая строка содержит:

- Значок статуса и короткий хеш коммита SHA, с веткой в виде метки.
- Сообщение коммита или **Ручное развёртывание**, если сообщения коммита не было.
- Автора, сколько времени прошло, сколько времени это заняло и что вызвало запуск.
- Метку статуса.

Статусы: **ожидание**, **сборка**, **развёртывание**, **успех** и **ошибка**. Пока что-то выполняется, страница обновляется автоматически каждые пять секунд и показывает под таблицей примечание **Автоматическое обновление**, так что можно оставить страницу открытой и наблюдать за ходом развёртывания.

### Когда развёртывание завершается неудачей

У неудачной строки справа появляется кнопка **Ошибка**. Нажмите на неё, чтобы развернуть захваченный вывод ошибки прямо здесь, не покидая страницу. Этот вывод это собственный текст ошибки сборки, поэтому обычно в нём указан файл или команда, которые привели к сбою.

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

## Определение buildpack

На сайтах с Node.js страница **Buildpack** в группе **Приложения** показывает, как KapsuleHost решил собирать ваше приложение. Определение выполняется по файлам в корне вашего репозитория, и побеждает первое совпадение:

| Определено | Триггер |
|---|---|
| Пользовательский buildpack | `kapsule.config.yaml` или `kapsule.config.yml` в корне |
| Buildpack Dockerfile | `Dockerfile` в корне |
| Node.js | `package.json` со скриптом `start`, `build` или `dev` |
| Python | `requirements.txt` или `pyproject.toml` |
| PHP | `composer.json` |
| Статический сайт | `index.html` в корне |

Если ничего не совпадает, страница сообщает об этом и перечисляет поддерживаемые триггеры. Добавьте `Dockerfile` или `kapsule.config.yaml`, чтобы взять управление сборкой под явный контроль.

### Запуск сборки

Нажмите **Запустить сборку**, чтобы поставить её в очередь. Страница опрашивает сервер каждые три секунды, пока выполняется запуск, а таблица **Последние сборки** показывает последние запуски с временем начала, типом, статусом, продолжительностью и получившейся ссылкой на образ. Нажмите на строку, чтобы увидеть хвост её лога.

Одновременно может выполняться только одна сборка. Попытка запустить вторую, пока одна уже в очереди или выполняется, отклоняется с сообщением **Сборка уже выполняется**, и это сделано намеренно: две сборки, одновременно записывающие один и тот же результат, это верный способ получить наполовину развёрнутый сайт.

## Отключение

Нажмите **Отключить** и подтвердите. Подтверждение явно объясняет последствия: конфигурация Git-деплоя и ключ развёртывания удаляются, а файлы вашего сайта не затрагиваются. Сайт продолжает обслуживать то, что было развёрнуто последним.

После этого наведите порядок, удалив ключ развёртывания и webhook в настройках вашего репозитория. Они просто перестанут работать, но оставленные «мёртвые» записи усложняют следующую проверку.

## Решение проблем

**Пуши ничего не вызывают.** Сначала проверьте переключатель автоматического развёртывания, затем webhook в вашем репозитории. Большинство провайдеров показывают последние доставки и их коды ответа, что сразу покажет, покинул ли запрос ваш репозиторий вообще.

**Клонирование не удаётся.** Ключ развёртывания отсутствует, был вставлен с переносом строки внутри, либо был добавлен не в тот репозиторий. Скопируйте его заново кнопкой **Скопировать ключ**, а не выделением текста вручную.

**Развёртывание проходит успешно, но сайт не меняется.** Скорее всего, неверно указан выходной каталог. Если ваша сборка записывает результат в `dist`, а выходной каталог не указан, собранные файлы никогда не попадут в корень, который обслуживается сайтом.

**Всё показывает «ожидание» и ничего не меняется.** Развёртывание было поставлено в очередь, но так и не было подхвачено. Запустите **Развернуть сейчас** вручную и проверьте страницу «Развёртывания» на наличие строки с ошибкой.

## Куда двигаться дальше

- [Предпросмотр развёртываний для pull request'ов](https://support.kapsulehost.com/ru-ru/site-preview) добавляет отдельный URL для каждого PR поверх этой настройки.
- [Хранение секретов приложения для сайта](https://support.kapsulehost.com/ru-ru/site-secrets) для учётных данных, которые нужны вашей сборке и среде выполнения.
- [Журнал активности сайта](https://support.kapsulehost.com/ru-ru/site-activity-log) фиксирует изменения конфигурации, сделанные здесь.