Deploy Hooksを使用したデプロイメントのトリガー

A deploy hook is a secret URL that queues a new deployment when something sends it an HTTP POST. There is no authentication header: the secrecy of the URL is the authentication. Use hooks to let a…

デプロイフックは、HTTP POSTリクエストを送信されたときに新しいデプロイメントをキューイングするシークレットURLです。認証ヘッダーはありません。URLのシークレット性が認証になります。フックを使用すると、ヘッドレスCMS、cronジョブ、CIパイプライン、またはその他のウェブフックによって、gitプッシュなしでプロジェクトを再構築できます。

デプロイフックの場所

フックには専用のタブがあります。/orbit/<project-id>/hooksでプロジェクトをOrbitalで開き、Hooksをクリックします。

同じDeploy hooksパネルはプロジェクトのSettingsタブの途中にも表示されるため、どちらからでも管理できます。

Orbitのデプロイフックパネル

デプロイフックの作成

Orbitを開いて、プロジェクト、その後Hooksを開きます。
Add deploy hookをクリックします。
6ヶ月後も意味のあるHook nameを入力してください。プレースホルダーは形式を示しています：「Contentful publish」、「Nightly cron」など。
Target environmentを選択します。デフォルトは**Production (default)**です。プロジェクトにステージング環境がある場合、フックをステージングに向けることができます。
Create hookをクリックします。

フックはリストに表示され、URL、Copy URLボタン、Delete hookボタンが表示されます。

フックURL

フックURLは次のようになります：

https://kpanel.kapsulehost.com/api/orbit/hooks/<token>

トークンはフック作成時に生成されたユニークなシークレットです。

フックURLはAPIキーと全く同じように扱ってください。それを持つ誰もが、プロジェクトのデプロイメントをトリガーできます。また、Orbitのデプロイゲートは何も止めません：デプロイロック、必須承認、CI必須チェック、必須ステージング成功はすべてプッシュトリガーデプロイのみに適用され、フックは直接パスします。フックURLをパブリックリポジトリ、共有ドキュメント、スクリーンショット、またはサポートチケットに貼り付けないでください。

フックのトリガー

POSTリクエストを送信します。本体とヘッダーは必須ではありません。

curl -X POST \
  https://kpanel.kapsulehost.com/api/orbit/hooks/<your-token>

OrbitはHTTP 202とデプロイメントIDで応答します。デプロイメントは数秒以内にDeploymentsタブに表示されます。

エンドポイントはPOSTのみを受け入れます。GETリクエストはデプロイメントをトリガーしません。一部の古いウェブフック統合はデフォルトでGETを使用するため、設定したフックが発火しない場合はメソッドを確認してください。

フックが実際にデプロイするもの

フックはターゲット環境（選択した環境、またはプロジェクトのプロダクション環境）を解決し、その環境のブランチを読み取り、gitプロバイダーにそのブランチの現在のヘッドコミットを要求します。その後、そのコミットのデプロイメントをキューイングします。

これには3つの結果があります：

フックは常にブランチヘッドをデプロイします。 リクエスト本体でコミットSHAまたはブランチ名を渡すことはできません。リクエスト本体は完全に無視されます。
フックは動作中のプロバイダー接続が必要です。 GitHub、GitLab、またはBitbucketを切断している場合、フックはブランチヘッドを読み取ることができず、エラーで失敗します（古いコードをデプロイする代わりに）。
フックは完全なビルドを再実行します。 これはロールバックではなく、プロモーションでもありません。これは現在ブランチ上にあるもののフレッシュビルドです。

繰り返しと重複する呼び出し

Orbitは、各呼び出しのビルドをキューイングするのではなく、バーストのフック呼び出しを適切に処理します。

その環境で同じコミットのデプロイメントが既に実行中の場合、フックは既存のデプロイメントを返し、応答をデデュプリケートされたとしてマークします。2番目のビルドは開始されません。
その環境で異なるコミットのビルドが実行中の場合、自動的にキャンセルされ、新しいコミットに置き換えられます。したがって、出力が既に置き換わったビルドの費用を支払うことはありません。

これにより、フックはパブリッシュされたエントリごとにウェブフックを発火するCMSに対して安全になります。1分間に6ページを公開すると、6ではなく1つのビルドが生成され、6つのビルド分の時間を消費しません。

ヘッドレスCMSの接続

ほとんどのヘッドレスCMSには「パブリッシュ時のウェブフック」機能があります。パターンは常に同じです：ウェブフックをフックURLに指し、POSTを使用し、認証設定を空のままにします。

Contentful

Settingsに移動して、Webhooks、Add webhookに移動します。
URLをOrbitフックURLに設定します。
メソッドをPOSTに設定します。
トリガーをPublish、またはサイトを再構築する必要があるコンテンツイベントに設定します。
保存します。

Sanity

プロジェクトダッシュボードで、API、Webhooks、Create webhookに移動します。URLをフックURLに、メソッドをPOSTに設定し、データセットとトリガーイベントを選択します。

Prismic

ダッシュボードで、Settings、Webhooksに移動し、フックURLを追加します。Prismicはすべてのドキュメント公開時に呼び出します。

CronジョブまたはCIパイプラインの接続

HTTPリクエストを実行できるスケジューラは何でも動作します：

# crontab: rebuild every night at 2am
0 2 * * * curl -fsS -X POST https://kpanel.kapsulehost.com/api/orbit/hooks/<your-token>

CIの場合、デプロイフックは、パイプラインがデプロイメントが発生するかどうかを決定する場合の最も単純なオプションです。これはBitbucket Pipelinesに推奨されるアプローチです。なぜなら、OrbitのCI必須チェック設定はGitHub ActionsジョブまたはGitLabパイプラインではなく、Bitbucketでは異なるため、Orbitはゲートされません。

「ブランチヘッドをデプロイする」以上のことが必要な場合は、フックの代わりにAPIトークンを使用します。Orbit、Tokensは、文書化されたREST APIと既製のGitHub Actionsワークフロー付きのCI/CDの範囲を限定されたベアラートークンを作成します。APIアクセスはApexプランに含まれています。

フックなしでスケジュールで再構築する

定期的な再構築が必要なだけの場合は、フックまったく必要ありません。SettingsのRuntimeの下のScheduled rebuildは、プロダクションを1時間、6時間、12時間、毎日、2日ごと、または週ごとに自動的に再構築します。これは正確にCMS駆動型サイトの場合のために構築されており、保護するシークレットURLはありません。

フックアクティビティの確認

各フック行は、「Used 14 times, last 3 Jul」の形式で使用された回数と最後に使用された時期を表示します。これは、CMSが実際にあなたが思っている時にフックを呼び出しているかを確認する最速の方法です。

カウントが上昇していない場合、問題は呼び出し側にあります：メソッドがPOSTであること、URLが正確であること、統合がTLSまたはファイアウォールエラーで静かに失敗していないことを確認してください。

フックの削除

行のDelete hookをクリックして確認します。ダイアログは、それを使用しているサービスが動作を停止することを警告します。これはまさに起こることです。

フックのトークンをインプレースで回転する方法はありません。URLが漏洩した場合、フックを削除して新しいフックを作成し、古いURLを使用したすべてのシステムを更新します。削除は即座に有効になるため、削除後ではなく、削除前にスワップを計画します。

トラブルシューティング

フックを呼び出しても何も起こりません。 メソッドがPOSTであることを確認してください。URLをトークンを含めて文字単位で確認してください。フックスタブでフックの使用カウントを確認してください。増加していない場合、リクエストが到達しませんでした。

フックが最新コミットについてのエラーを返します。 Orbitはgitプロバイダーからブランチヘッドを読み取ることができませんでした。Orbit、New project、Reconnectからプロバイダーを再接続し、リポジトリがまだアクセス可能であることを確認します。

フックがターゲット環境についてのエラーを返します。 フックが指し示していた環境がもう存在しません。ほとんどの場合、ステージング環境が削除されたためです。フックを削除し、ライブ環境に対して新しいフックを作成します。

フックが発火しますが、デプロイメントは最後と同じです。 これはデデュプリケーション動作です：ブランチヘッドが変更されていないため、構築する新しいものはありません。コミットをプッシュするか、Deploy nowを使用して、同じコミットを再構築したい場合は使用してください。