プレビューデプロイは、プルリクエストごとにそのブランチのコードからビルドされた専用のライブURLを提供するため、レビュアーは差分を読んで想像する代わりに、実際の変更をクリックして確認できます。各プレビューは新しいコミットをプッシュするたびに更新され、プルリクエストがクローズされると自動的に削除されます。
プレビューデプロイの場所
ウェブサイト を開き、サイトをクリックし、サイトの左メニューの Environment グループを開いて プレビュー を選択します。このページのタイトルは プレビューデプロイ です。
プレビューはステージングとは別物です。ステージングは意図的にプッシュする、長期間存在するサイトのコピーであるのに対し、プレビューはプルリクエストごとに作成され、終了後に破棄される短期間の環境です。多くのチームは両方を使用しています。もう一方についてはステージング環境を参照してください。
まずGitデプロイをセットアップする
プレビューは単独で機能するものではありません。本番サイトのデプロイキーとビルドコマンドを再利用するため、プレビューを有効にする前にサイトが動作するGitデプロイ設定を持っている必要があります。
Gitデプロイが設定されていない場合、ページには「まずGitデプロイをセットアップしてください」と表示され、有効化フォームの代わりに「Gitデプロイに移動」ボタンが表示されます。Gitからのサイトのデプロイの手順を進めてから、再度このページに戻ってください。
Gitデプロイが接続されていてもビルドコマンドが設定されていない場合、Previewページに警告が表示されます。プレビューは、リポジトリがすでにビルド済みで、静的ファイルがルートにあるものとして扱います。これは単純なHTMLサイトであれば正しい動作ですが、コンパイルが必要なものにとっては誤りとなるため、プロジェクトに必要であればGitデプロイページでビルドコマンドを設定してください。
プレビューの有効化
- プレビューデプロイを有効にする カードに、リポジトリを
owner/repo形式で入力します。URLでもSSHアドレスでもなく、2つの部分だけです。例えばacme/marketing-siteのようになります。 - Enable をクリックします。
owner/name に一致しないものはすべて拒否され、「リポジトリはowner/name形式である必要があります」と表示されます。
有効化した直後、KPanelは「ウェブフックシークレットを今すぐコピーしてください」という見出しのカードにウェブフック署名シークレットを表示し、二度と表示されないという警告を出します。
ページを離れる前にシークレットをコピーしてください。これは一度だけ生成され、その後は取得できません。紛失した場合の対処法は再生成することですが、これにより古いシークレットは無効になり、結局リポジトリのウェブフックも更新する必要があります。
リポジトリへのウェブフックの追加
設定済みのカードには、リポジトリ設定のWebhooks配下に貼り付けるための ウェブフックURL が表示されます。以下のように設定してください。
- ペイロード URL: ページに表示されているウェブフックURL。
- Secret: 先ほどコピーした値。
- コンテンツの種類: JSON。
- Events: プルリクエストイベントに加え、プッシュも選択します。これにより、オープン中のプルリクエストへの新しいコミットでプレビューが再ビルドされます。
これが設定されると、プルリクエストを開いてから数分以内にプレビューがビルドされます。バックグラウンドジョブが新しいプレビュー作業を1分ごとにチェックするため、KPanel側で何かを押す必要はありません。
プレビューURL
各プレビューには pr-<pull-request-number>-<site-id>.kapsulecloud.app という形式の専用ホスト名が割り当てられ、ワイルドカード証明書でカバーされているため、自分で証明書の手続きをすることなくHTTPSで提供されます。
確実にプレビューを開く方法は、最近のプレビュー 内のそのプレビューの行にある Open ボタンを使うことです。これはそのビルド用に発行された正確なURLを保持しています。そのリンクをプルリクエストに貼り付ければ、レビュアーはKPanelを探す必要が一切なくなります。
最近のプレビュー一覧の読み方
最近のプレビュー セクションには、最新のプレビューが新しい順に一覧表示されます。各行には、プルリクエスト番号とタイトル、ブランチ、コミット、そしてステータスが表示されます。
| ステータス | 意味 |
|---|---|
| BUILDING | クローンとビルドを実行中 |
| LIVE | プレビューURLで配信中 |
| FAILED | ビルドがエラーになりました。ログを展開して原因を確認してください |
| DESTROYED | クリーンアップ済み（通常はプルリクエストがクローズされたため） |
行の ビルドログを切り替える をクリックすると、そのビルド出力をインラインで展開できます。このログは、プレビューが失敗したときに最初に確認すべき場所であり、ローカルでビルドした場合と同じ出力です。
一覧が空の場合はその旨が表示されます。リポジトリでプルリクエストを開けば、数分以内にプレビューがビルドされます。
ウェブフックシークレットのローテーション
設定済みのカードで シークレットを再生成 をクリックします。KPanelは確認を求め、現在のシークレットが直ちに機能しなくなること、その後リポジトリのウェブフック設定を更新する必要があることを明示します。
新しいシークレットは、以前と同じ一度限り表示のカードに一度だけ表示されます。コピーしたうえで、リポジトリ側のウェブフックを更新してください。この2つの操作の間は、受信するウェブフック配信が拒否されるため、2つの手順を間を置かずに続けて行ってください。
リポジトリの管理者権限を持つ人がチームを離れたとき、または共有チャットチャンネルやチケットなど、シークレットが漏らしてはいけない場所に貼り付けられたことがある場合は、シークレットを再生成してください。
プレビューを無効にする
Disable をクリックします。設定が無効化され、保存されていたシークレットは消去されます。既存のプレビューは再ビルドされなくなります。
リポジトリ側のウェブフックも削除して整理しておきましょう。削除しなくても害のあることは起きず単に失敗し続けるだけですが、永遠にエラーを返し続けるウェブフックは、リポジトリの配信ログ上のノイズになります。
コストと運用管理
プレビューは実際のコードをビルドして提供するため、サイト上の他のデプロイと同じリソースを使用します。これを抑えるための習慣が2つあります。
- 作業していないプルリクエストはクローズしてください。クローズされたプルリクエストのプレビューは自動的にクリーンアップされます。
- プレビューを本番環境の認証情報に接続しないでください。Secretsタブの preview 環境を通じてテスト用のキーを渡してください。これはまさに、プレビューと本番の設定が混同されないようにするために存在します。
プレビューURLは非公開ではありません。有効な証明書を持つ、実際に公開到達可能なホスト名であり、リンクを持つ誰でも開くことができます。実際の顧客データを含むものをプレビューでレビューしないでください。また、本番データベースのダンプからプレビュー環境を作成しないでください。
トラブルシューティング
プルリクエストを開いてもビルドされない。 リポジトリのウェブフックの最近の配信状況を確認してください。401または403はシークレットが一致していないことを意味するため、再生成して両側を更新してください。配信自体が行われていない場合は、ウェブフックがプルリクエストイベントを購読していません。
プレビューはビルドされるが、ディレクトリ一覧や404が表示される。 Gitデプロイページの出力ディレクトリが、実際にビルドが書き込む場所と一致していません。プレビューはこの設定を本番環境から引き継ぎます。
プレビューでのみビルドが失敗する。 最もよくある原因は、本番環境には存在するがプレビュー環境には追加されていない依存関係や環境変数です。Secretsページの preview タブを確認してください。
プレビューURLが機能しなくなる。 その行のステータスを確認してください。DESTROYED は、プルリクエストがクローズされ、環境が回収されたことを意味し、これは意図された挙動です。
次に読むべき内容
- Gitからのサイトのデプロイ、前提となる設定です。
- サイトのアプリシークレットの保存、環境ごとの認証情報について。
- ステージング環境、永続的な本番前環境のコピーについて。