# Предварительные деплои для пул-реквестов

Source: https://support.kapsulehost.com/ru-ru/site-preview

Preview-деплои дают каждому pull request собственный рабочий URL, собранный из кода этой ветки, чтобы рецензенты могли открыть реальное изменение, а не читать diff и гадать. Каждое превью обновляется при отправке нового коммита и автоматически удаляется при закрытии pull request.

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

Откройте раздел **Веб-сайты**, нажмите на сайт, откройте группу **Environment** в левом меню сайта и выберите **Предпросмотр**. Страница называется **Preview-деплои**.

Превью отличаются от staging. Staging - это одна долгоживущая копия сайта, в которую вы отправляете изменения осознанно; превью же - это кратковременное окружение, создаваемое для каждого pull request и удаляемое впоследствии. Многие команды используют и то, и другое. Вторую половину темы смотрите в статье [Staging-окружения](https://support.kapsulehost.com/ru-ru/staging-environments).

![Страница Preview-деплоев для сайта в KPanel](https://support.kapsulehost.com/help/screenshots/site-preview.0fb977c9.webp)

## Сначала настройте Git-деплой

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

Если Git-деплой не настроен, на странице отображается надпись **Сначала настройте Git-деплой** и кнопка **Перейти на Git-деплой** вместо формы включения. Пройдите шаги статьи [Деплой сайта из Git](https://support.kapsulehost.com/ru-ru/site-git-deploy), затем вернитесь сюда.

> **Note:** Если Git-деплой подключен, но команда сборки не задана, на странице Preview отображается предупреждение. Превью будут считать, что репозиторий уже собран, а статические файлы находятся в корне. Это верно для простого HTML-сайта и неверно для всего, что требует компиляции, поэтому при необходимости задайте команду сборки на странице Git-деплоя.

## Включение превью

1. В блоке **Включить preview-деплои** введите репозиторий в формате `owner/repo`. Не URL, не SSH-адрес: просто два сегмента, например `acme/marketing-site`.
2. Нажмите **Включить**.

Всё, что не соответствует формату `owner/name`, будет отклонено с сообщением **Репозиторий должен быть в формате owner/name**.

Сразу после включения KPanel показывает секрет подписи webhook в блоке с заголовком **Скопируйте ваш webhook secret сейчас** и предупреждением, что повторно вы его не увидите.

> **Important:** Скопируйте секрет прежде, чем покинуть страницу. Он генерируется один раз и не может быть получен повторно. Если вы его потеряли, решение - восстановить его заново, что аннулирует старый секрет и потребует обновления webhook в вашем репозитории.

## Добавление webhook в ваш репозиторий

В блоке с настроенной конфигурацией отображается **URL webhook**, который нужно вставить в настройки вашего репозитория, в раздел Webhooks. Настройте его следующим образом:

- **URL полезной нагрузки**: URL webhook, указанный на странице.
- **Secret**: значение, которое вы только что скопировали.
- **Тип контента**: JSON.
- **События**: события pull request, а также push, чтобы новые коммиты в открытом pull request пересобирали превью.

После этого открытие pull request приведёт к сборке превью в течение нескольких минут. Фоновая задача проверяет наличие новой работы для превью каждую минуту, поэтому нажимать что-либо в KPanel не требуется.

## URL превью

Каждое превью получает собственное имя хоста вида `pr-<pull-request-number>-<site-id>.kapsulecloud.app`, покрытое wildcard-сертификатом, поэтому оно обслуживается по HTTPS без каких-либо дополнительных действий с сертификатами с вашей стороны.

Надёжный способ открыть превью - это кнопка **Open** в строке превью в разделе **Недавние превью**, которая содержит точный URL, выделенный для этой сборки. Вставьте эту ссылку в pull request, чтобы рецензентам вообще не пришлось искать KPanel.

## Чтение списка Недавних превью

В разделе **Недавние превью** перечислены самые свежие превью, сначала новые. В каждой строке отображается номер и заголовок pull request, ветка, коммит и статус:

| Статус | Значение |
|---|---|
| BUILDING | Выполняется клонирование и сборка |
| LIVE | Обслуживается по URL превью |
| FAILED | Сборка завершилась ошибкой; разверните лог, чтобы увидеть причину |
| DESTROYED | Удалено, обычно потому что pull request закрыт |

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

Если список пуст, страница сообщает об этом: откройте pull request в репозитории, и превью будет собрано в течение нескольких минут.

## Смена секрета webhook

Нажмите **Восстановить secret** в блоке с настроенной конфигурацией. KPanel попросит подтверждение и прямо укажет, что текущий секрет перестанет работать немедленно и вам нужно будет обновить его в настройках webhook вашего репозитория.

Новый секрет показывается один раз, в том же одноразовом блоке, что и раньше. Скопируйте его, затем обновите webhook в вашем репозитории. Между этими двумя моментами входящие доставки webhook будут отклоняться, поэтому выполняйте оба шага подряд, без пауз.

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

## Отключение превью

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

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

## Расходы и обслуживание

Превью собирают и обслуживают реальный код, поэтому используют те же ресурсы, что и любой другой деплой сайта. Две привычки помогают держать это под контролем:

- Закрывайте pull request'ы, над которыми вы больше не работаете. У закрытого pull request превью удаляется автоматически.
- Не направляйте превью на рабочие (production) учётные данные. Выдавайте им тестовые ключи через окружение **preview** на вкладке [Secrets](https://support.kapsulehost.com/ru-ru/site-secrets), которое существует именно для того, чтобы конфигурации превью и рабочей среды нельзя было перепутать.

> **Warning:** URL превью не является приватным. Это реальное, публично доступное имя хоста с действительным сертификатом, и любой, у кого есть ссылка, может его открыть. Не используйте превью для проверки чего-либо, содержащего реальные данные клиентов, и не наполняйте окружения превью дампом рабочей базы данных.

## Устранение неполадок

**При открытии pull request ничего не собирается.** Проверьте последние доставки webhook в вашем репозитории. Код 401 или 403 означает, что секрет не совпадает, поэтому восстановите его и обновите на обеих сторонах. Полное отсутствие доставок означает, что webhook не подписан на события pull request.

**Превью собирается, но показывает список каталога или 404.** Каталог вывода на странице Git-деплоя не совпадает с тем, куда реально записывает ваша сборка. Превью наследуют эту настройку от рабочей среды.

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

**URL превью перестал работать.** Посмотрите на статус в его строке. **DESTROYED** означает, что pull request закрыт и окружение было освобождено, это ожидаемое поведение.

## Что дальше

- [Деплой сайта из Git](https://support.kapsulehost.com/ru-ru/site-git-deploy), необходимая предварительная настройка.
- [Хранение секретов приложения для сайта](https://support.kapsulehost.com/ru-ru/site-secrets) для учётных данных по окружениям.
- [Staging-окружения](https://support.kapsulehost.com/ru-ru/staging-environments) для постоянной копии перед выходом в продакшен.