Preview-деплои дают каждому pull request собственный рабочий URL, собранный из кода этой ветки, чтобы рецензенты могли открыть реальное изменение, а не читать diff и гадать. Каждое превью обновляется при отправке нового коммита и автоматически удаляется при закрытии pull request.
Где находятся Preview-деплои
Откройте раздел Веб-сайты, нажмите на сайт, откройте группу Environment в левом меню сайта и выберите Предпросмотр. Страница называется Preview-деплои.
Превью отличаются от staging. Staging - это одна долгоживущая копия сайта, в которую вы отправляете изменения осознанно; превью же - это кратковременное окружение, создаваемое для каждого pull request и удаляемое впоследствии. Многие команды используют и то, и другое. Вторую половину темы смотрите в статье Staging-окружения.
Сначала настройте Git-деплой
Превью не являются самостоятельной функцией. Они используют ключ деплоя и команду сборки рабочего сайта, поэтому прежде, чем включить превью, на сайте должна быть настроена рабочая конфигурация Git-деплоя.
Если Git-деплой не настроен, на странице отображается надпись Сначала настройте Git-деплой и кнопка Перейти на Git-деплой вместо формы включения. Пройдите шаги статьи Деплой сайта из Git, затем вернитесь сюда.
Если Git-деплой подключен, но команда сборки не задана, на странице Preview отображается предупреждение. Превью будут считать, что репозиторий уже собран, а статические файлы находятся в корне. Это верно для простого HTML-сайта и неверно для всего, что требует компиляции, поэтому при необходимости задайте команду сборки на странице Git-деплоя.
Включение превью
- В блоке Включить preview-деплои введите репозиторий в формате
owner/repo. Не URL, не SSH-адрес: просто два сегмента, напримерacme/marketing-site. - Нажмите Включить.
Всё, что не соответствует формату owner/name, будет отклонено с сообщением Репозиторий должен быть в формате owner/name.
Сразу после включения KPanel показывает секрет подписи webhook в блоке с заголовком Скопируйте ваш webhook secret сейчас и предупреждением, что повторно вы его не увидите.
Скопируйте секрет прежде, чем покинуть страницу. Он генерируется один раз и не может быть получен повторно. Если вы его потеряли, решение - восстановить его заново, что аннулирует старый секрет и потребует обновления 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, которое существует именно для того, чтобы конфигурации превью и рабочей среды нельзя было перепутать.
URL превью не является приватным. Это реальное, публично доступное имя хоста с действительным сертификатом, и любой, у кого есть ссылка, может его открыть. Не используйте превью для проверки чего-либо, содержащего реальные данные клиентов, и не наполняйте окружения превью дампом рабочей базы данных.
Устранение неполадок
При открытии pull request ничего не собирается. Проверьте последние доставки webhook в вашем репозитории. Код 401 или 403 означает, что секрет не совпадает, поэтому восстановите его и обновите на обеих сторонах. Полное отсутствие доставок означает, что webhook не подписан на события pull request.
Превью собирается, но показывает список каталога или 404. Каталог вывода на странице Git-деплоя не совпадает с тем, куда реально записывает ваша сборка. Превью наследуют эту настройку от рабочей среды.
Сборка завершается ошибкой только в превью. Самая частая причина - зависимость или переменная окружения, которая существует в рабочей среде, но так и не была добавлена в окружение превью. Проверьте вкладку preview на странице Secrets.
URL превью перестал работать. Посмотрите на статус в его строке. DESTROYED означает, что pull request закрыт и окружение было освобождено, это ожидаемое поведение.
Что дальше
- Деплой сайта из Git, необходимая предварительная настройка.
- Хранение секретов приложения для сайта для учётных данных по окружениям.
- Staging-окружения для постоянной копии перед выходом в продакшен.