Git Deploy はリポジトリとサイトを接続し、選択したブランチへのすべてのプッシュでコードをクローンし、ビルドを実行し、結果を公開します。本ガイドでは、初回の接続、セットアップを完了させるリポジトリ側の2つの手順、デプロイ履歴の読み方、そして Node.js アプリのビルド方法を決めるビルドパック検出について説明します。
Git Deploy の場所
ウェブサイト を開き、サイトをクリックし、サイトの左メニューにある Environment グループを開いて Git デプロイ を選択します。近くには関連する2つのページがあります。
- デプロイ: このサイトの完全なデプロイ履歴。同じ Environment グループ内にあります。
- Buildpack: 検出されたビルド方式。Node.js サイトの場合、アプリ グループ内にあります。
Git Deploy ページには、その役割がそのまま説明されています。リポジトリを接続すると、設定したブランチへのすべてのプッシュがビルドとデプロイを引き起こします。
リポジトリの接続
- Provider を選択します: GitHub、GitLab、または Bitbucket。
- リポジトリ URL を入力します。必要なのは SSH 形式で、例えば
git@github.com:user/repo.gitのようなものです。 - デプロイ元とする Branch を設定します。このフィールドの初期値は
mainです。 - 必要に応じて ビルドコマンド を設定します。例:
npm run build。 - 必要に応じて 出力ディレクトリ を設定します。例:
dist、public、または既にビルド済みのリポジトリの場合は.。 - リポジトリを接続 をクリックします。
リポジトリが現状のままデプロイ可能であれば、ビルドコマンドと出力ディレクトリは空のままにしておきます。これは通常の PHP サイトや静的サイトでよくあるケースです。
高度なスクリプト
詳細 を展開すると、2つの追加フィールドが表示されます。
- デプロイ前スクリプト: ビルドの前に実行されます。
- デプロイ後スクリプト: デプロイの後に実行されます。
新しいコードが配置された後に必ず行う必要があること、例えばアプリケーションキャッシュのクリア、データベースマイグレーションの実行、ワーカーの再起動などには、デプロイ後フックを使用してください。
プッシュ時の自動デプロイ
カード下部のトグルは、プッシュによってデプロイが実行されるかどうかを制御します。オンの場合、設定されたブランチへのすべてのプッシュがデプロイを引き起こします。オフの場合、今すぐデプロイ で手動でトリガーしたときのみデプロイが実行されます。
コードフリーズやインシデントの間は、リポジトリを切断するのではなく、自動デプロイをオフにしてください。切断するとデプロイキーと Webhook のシークレットが破棄されるため、後でリポジトリ側の2つの手順をやり直す必要があります。
リポジトリ側でのセットアップ完了
KPanel でリポジトリを接続するのは、3つの手順のうちの最初の1つにすぎません。デプロイが実行されるまでは、ページに セットアップを完了: 残り 2 ステップ というバナーが表示され、必要な情報がすべて示されます。
ステップ 2: デプロイキーの追加
KapsuleHost がリポジトリをクローンするには読み取りアクセス権が必要です。バナーには公開鍵と キーをコピー ボタンが表示されます。
これをリポジトリのデプロイキー設定に貼り付けます。GitHub の場合、バナーから GitHub に追加 ショートカットで該当の設定ページに直接移動できます。読み取りアクセスのみで十分です。書き込み権限は付与しないでください。
ステップ 3: Webhook の追加
Webhook は、プッシュが発生したことを KapsuleHost に伝えるものです。バナーには3つの値が表示されます。
| フィールド | 値 |
|---|---|
| ペイロード URL | /api/git-deploy/webhook/ で終わり、このサイトの ID が付加された URL |
| シークレット | 生成された署名用シークレット。目のアイコンをクリックするまで非表示 |
| コンテンツ タイプ | application/json |
それぞれの値をリポジトリの Webhook 設定にコピーします。GitHub の場合は Webhook を GitHub に追加 ショートカットがあります。コンテンツタイプは既定のフォームエンコードではなく JSON に設定してください。そうしないとペイロードが解析されません。
Webhook のシークレットはパスワードと同様に扱ってください。これとペイロード URL を持つ人は誰でもサイトのデプロイをトリガーできます。両方の値は、そのサイトを既に管理できる人にのみ表示され、シークレットは目のアイコンで要求するまで非表示のままです。
手動でのデプロイ
Git Deploy ページで 今すぐデプロイ をクリックすると、コミットをプッシュすることなく、設定されたブランチの現在の最新状態をビルド、デプロイします。これは自動デプロイがオンかオフかに関わらず機能するため、フリーズ中に使うのに適したツールです。プッシュは無視されますが、修正を出荷することはできます。
デプロイ履歴の確認
Environment を開き、次に デプロイ を開きます。ページタイトルは デプロイ履歴 で、Webhook または手動でトリガーされたすべてのデプロイを新しい順に一覧表示します。
各行には以下の情報が含まれます。
- ステータスアイコンと短いコミット SHA。ブランチはピル形式で表示されます。
- コミットメッセージ。表示するコミットメッセージがない場合は 手動デプロイ と表示されます。
- 実行者、実行からの経過時間、所要時間、トリガー元。
- ステータスピル。
ステータスには pending、building、deploying、success、failed があります。処理が進行中の間、ページは5秒ごとに自動更新され、テーブルの下に 自動更新中 の注記が表示されるため、開いたままデプロイが完了するのを見守ることができます。
デプロイが失敗した場合
失敗した行には右側に Error ボタンが表示されます。クリックすると、ページを離れることなくキャプチャされたエラー出力がインラインで展開されます。この出力はビルド自体のエラーテキストであるため、通常は失敗したファイルやコマンドの名前が示されます。
以下の順序で対処してください。エラーを読む、ローカルで同じビルドコマンドを再現する、修正する、プッシュする。ローカルでは動くがここでは動かない場合、その違いはほぼ常に環境の違いです。手元のマシンにグローバルにインストールされている依存関係が不足しているか、作業ディレクトリにはあるがコミットされていないファイルがある、といった場合です。
ビルドパック検出
Node.js サイトでは、アプリ グループ内の Buildpack ページで、KapsuleHost がアプリのビルド方法をどのように判断したかが表示されます。検出はリポジトリルートのファイルに対して実行され、最初に一致したものが採用されます。
| 検出結果 | トリガー |
|---|---|
| カスタムビルドパック | ルートにある kapsule.config.yaml または kapsule.config.yml |
| Dockerfile ビルドパック | ルートにある Dockerfile |
| Node.js | start、build、または dev スクリプトを持つ package.json |
| Python | requirements.txt または pyproject.toml |
| PHP | composer.json |
| 静的サイト | ルートにある index.html |
何も一致しない場合、ページにはその旨と、サポートされているトリガーの一覧が表示されます。ビルドを明示的に制御するには、Dockerfile または kapsule.config.yaml を追加してください。
ビルドの実行
ビルドを実行 をクリックするとビルドがキューに入ります。実行中はページが3秒ごとにポーリングし、最近のビルド テーブルには直近の実行結果が、開始時刻、種類、ステータス、所要時間、生成されたイメージ参照とともに表示されます。行をクリックするとログの末尾を確認できます。
同時に実行できるビルドは1つだけです。既にキューにあるか実行中のビルドがある状態で2つ目をトリガーしようとすると、ビルドが既に進行中です というメッセージで拒否されます。これは意図的な動作で、2つのビルドが同時に同じ出力を書き込むと、デプロイが中途半端な状態になってしまうためです。
接続解除
Disconnect をクリックして確認します。確認画面には影響範囲が明示されており、Git デプロイの設定とデプロイキーが削除され、サイトファイルには影響しないことが示されます。サイトは最後にデプロイされた内容を引き続き配信します。
その後、リポジトリ設定でデプロイキーと Webhook を削除して整理してください。これらは単に機能しなくなるだけですが、使われなくなったエントリを残しておくと、次回の監査が難しくなります。
トラブルシューティング
プッシュしても何も起こらない。 まず自動デプロイのトグルを確認し、次にリポジトリ側の Webhook を確認してください。ほとんどのプロバイダーは最近の配信とそのレスポンスコードを表示するため、リクエストがそもそもリポジトリから送信されたかどうかがすぐにわかります。
クローンに失敗する。 デプロイキーが未設定か、改行を含んだ状態で貼り付けられたか、間違ったリポジトリに追加されている可能性があります。テキストを手で選択するのではなく、キーをコピー ボタンで再度コピーしてください。
デプロイは成功するがサイトが変わらない。 出力ディレクトリが間違っている可能性が高いです。ビルドが dist に書き込んでいるのに出力ディレクトリが空の場合、ビルドされたファイルは公開先のルートに届きません。
すべて pending のまま動かない。 デプロイがキューに入ったものの、処理が開始されなかった状態です。手動で 今すぐデプロイ をトリガーし、Deploys ページでエラー行がないか確認してください。
次に読むべき記事
- プルリクエストのプレビューデプロイ では、このセットアップに加えて PR ごとの URL を追加する方法を説明しています。
- サイトのアプリシークレットの保存 では、ビルドとランタイムに必要な認証情報について説明しています。
- サイトアクティビティログ には、ここで行った設定変更が記録されます。