自動デプロイ

自動デプロイの仕組み

自動デプロイは、アプリが追跡するブランチに対して GitHub が push イベントを送信するたびに、その GitHub アプリを再デプロイします。Server Compass はサーバー上に常時稼働のゲートウェイと非公開のデプロイ worker をインストールし、リポジトリの webhook を作成し、GitHub の署名付きテスト配信を検証し、その正確な commit をデプロイのためにキューへ入れます。

セットアップ後、Server Compass デスクトップアプリを開いたままにしておく必要はありません。サーバー側のランタイムは Docker とともに再起動し、webhook の受信、アプリのビルド、デプロイ履歴の記録を続けます。SSH ポートは非公開のままで構いません。GitHub から HTTPS で到達できる必要があるのは webhook のホスト名だけです。

要件

開始する前に、次のものが揃っていることを確認してください：

• GitHub リポジトリからすでにデプロイ済みの Docker アプリ
• ビルド場所として Build on VPS を選択していること。GitHub Actions によるビルドは webhook 自動デプロイ v1 ではサポートされていません
• アプリの Server Compass ディレクトリ内にある管理された Git チェックアウト
• リポジトリの webhook を作成する権限を持つ、連携済みの GitHub アカウント
• サーバー上の Docker Engine と Docker Compose
• deploy.example.com のような専用の公開 HTTPS ホスト名
• そのホスト名から webhook ゲートウェイへのルート

自動デプロイは、デプロイ済みアプリに保存されたブランチに従います。その正確なブランチへの push はそれぞれ、GitHub イベントに含まれる commit をキューへ入れます。他のブランチへの push は無視されます。

アプリのセットアップ

1. Server Compass で、リポジトリを GitHub アプリとしてデプロイします。
2. デプロイ時に Build on VPS を選択します。
3. デプロイ済みのアプリを開き、Deployments に移動します。
4. 自動デプロイ のカードを見つけ、Set up Auto Deploy をクリックします。
5. 公開 webhook ホスト名を入力します。ホスト名または HTTPS オリジンのみを使用してください（例：deploy.example.com または https://deploy.example.com）。パス、クエリ文字列、カスタムポートは追加しないでください。

このホスト名は GitHub の公開入口です。ドメインだけでは不十分です。DNS、TLS、ファイアウォールや NAT のルール、そしてプロキシまたはトンネルが、サーバー上のゲートウェイまでの完全なルートを構成する必要があります。

GitHub がサーバーに到達する方法を選ぶ

3 つのルートオプションはいずれも同じ署名付き webhook と非公開のデプロイ worker を使用します。異なるのは公開ルートだけです。

Server Compass 管理の Traefik

Server Compass 管理の Traefik がすでにサーバー上の公開リバースプロキシになっている場合に使用します。ホスト名の DNS レコードをサーバーに向け、受信ポート 80 と 443 が到達できるようにします。Server Compass は webhook ゲートウェイを既存の traefik-public Docker ネットワークに接続し、HTTPS ホストルートを構成します。

これは公開 VPS では通常最もシンプルな選択肢です。ルーターがポート 80 と 443 を対象のサーバーに転送し、ホスト名がルーターの公開 IP に解決される場合は、LAN サーバーでも使用できます。

既存のリバースプロキシ

Nginx、Caddy、Traefik、HAProxy などのプロキシがすでにホスト名を処理している場合に使用します。Check server をクリックして生成されたループバックターゲットを取得し、webhook ホスト名を表示されたアドレス（例：http://127.0.0.1:42315）へルーティングします。

ゲートウェイが HMAC 署名を検証できるよう、プロキシは生のリクエストボディと GitHub webhook のヘッダーを保持する必要があります。このルートの前にログインミドルウェア、Cloudflare Access、その他の対話的な認証ページを配置しないでください。

プロキシが Docker 内で動作している場合、プロキシコンテナ内の 127.0.0.1 はそのコンテナ自身を指すことに注意してください。代わりにホストネットワーク、host-gateway アドレス、または適切な共有 Docker ネットワークを使用してください。

安定したトンネル

LAN サーバー、非公開 VPS、CGNAT 接続、または受信ポートを開けたくないサーバーでは、これを使用します。永続的な名前付き Cloudflare Tunnel または同等のトンネルを作成し、そのコネクタをサーバー上で実行し、公開ホスト名を Check server が表示するループバックターゲット（例：http://127.0.0.1:42315）にマッピングします。

トンネルは安定していて、再起動後に自動的に開始する必要があります。GitHub は webhook URL を保存するため、一時的な Quick Tunnel や再起動時に変わる ngrok URL は適していません。コネクタが Docker 内で動作している場合は、ホスト上のゲートウェイに実際に到達できるホストネットワークや別のルートを与えてください。

サーバーを確認して有効化する

1. Check server をクリックします。
2. Docker Engine、Docker Compose、および推奨されるゲートウェイポートが準備状況チェックに合格することを確認します。
3. 管理された Traefik を選択した場合は、traefik-public ネットワークも合格することを確認します。
4. 既存のプロキシまたは安定したトンネルを選択した場合は、結果に表示された正確なループバックポートへの外部ルートを完成させます。
5. Activate Auto Deploy をクリックします。

Server Compass はゲートウェイと worker をインストールし、非公開の webhook URL を作成し、署名シークレットをサーバーに保存し、GitHub に webhook を作成し、GitHub の ping を送信し、署名付き配信の成功を待ちます。ステータスは Installed、Routed、Hooked、Verified、Active の順に進みます。

セットアップが Awaiting route で止まった場合、ランタイムはすでにインストールされていますが、GitHub がまだ到達できていません。DNS、TLS、ファイアウォール/NAT、プロキシ、またはトンネルのルートを完成または修正してから、Continue setup をクリックします。アプリを再インストールする必要はありません。

自動デプロイを検証する

まず、公開ヘルスエンドポイントが Server Compass ゲートウェイに到達することを確認します：

curl -fsS https://deploy.example.com/healthz

次に、デプロイの一連の流れ全体を検証します：

1. GitHub でリポジトリを開き、Settings > Webhooks に移動します。
2. Server Compass が作成した webhook を開き、最新の配信が 2xx 応答を返したことを確認します。
3. 追跡中のブランチに小さな commit を push します。
4. Server Compass でアプリのデプロイ履歴を開き、webhook ジョブが push された commit を使用したことを確認します。
5. デプロイされたアプリケーションにその変更が含まれていることを確認します。

最後のテストとして、Server Compass を完全に終了し、追跡中のブランチにもう 1 つ commit を push して、再度アプリケーションを検証します。ゲートウェイ、キュー、worker はサーバー上で動作しているため、デプロイは問題なく完了するはずです。

有効な webhook を管理する

自動デプロイのカードには、次のアクションがあります：

• Test webhook は GitHub のテスト配信をもう一度送信し、そのステータスを更新します。
• Rotate secret はサーバーと GitHub webhook の両方の署名シークレットを置き換えます。
• Pause はターゲットと履歴を保持したまま自動デプロイを停止します。Resume で再び有効になります。
• Remove は GitHub webhook とそのリモートターゲットポリシーを削除しますが、デプロイ履歴は保持します。

追跡するリポジトリまたはブランチを変更するには、まず自動デプロイを削除し、新しいリポジトリまたはブランチでアプリを更新して再デプロイし、その後もう一度自動デプロイをセットアップします。

トラブルシューティングとセキュリティ

• ヘルスエンドポイントが失敗する、または 502/404 を返す： DNS と TLS を確認し、プロキシまたはトンネルが現在のループバックポートを指していることを確認し、ゲートウェイコンテナが実行中であることを確認します。
• GitHub の配信が 2xx でない： その webhook の最近の配信を調べ、認証レイヤーが GitHub をブロックしていないことを確認し、プロキシが生のボディを変更したり GitHub ヘッダーを削除したりしていないことを確認します。
• push してもデプロイされない： 自動デプロイが Paused ではなく Active であること、そして push が正確な追跡ブランチに対して行われたことを確認します。
• 再起動までトンネルが機能していた： 名前付きトンネルのコネクタをシステムサービスまたは再起動可能なコンテナとして構成します。一時的な URL は使用しないでください。
• デスクトップが閉じているとデプロイが失敗する： サーバーがオンラインであること、および Server Compass のゲートウェイと worker のコンテナが実行中であることを確認します。

webhook URL には非公開のルートトークンが含まれており、公開すべきではありません。GitHub の配信は、サーバー上で生成・保存され UI には決して表示されない HMAC 署名シークレットで認証されます。SSH、Docker ソケット、または非公開の worker をインターネットに公開する必要はありません。