カスタム デプロイ保護規則の作成

カスタム デプロイ保護規則について

独自のカスタム保護規則を有効にして、サードパーティ サービスを使ったデプロイを制御できます。 たとえば、Datadog、Honeycomb、ServiceNow などのサービスを使って、GitHub.com へのデプロイに対して自動承認を提供できます。

カスタム デプロイ保護規則は GitHub Apps を利用しており、Webhook とコールバックに基づいて実行されます。 ワークフロー ジョブの承認または拒否は、deployment_protection_rule Webhook の使用に基づいています。 詳細については、「Webhook のイベントとペイロード」と「デプロイの承認または拒否」を参照してください。

カスタム デプロイ保護規則を作成し、リポジトリにインストールすると、リポジトリ内のすべての環境で自動的にカスタム デプロイ保護規則を使用できるようになります。

カスタム デプロイ保護規則を使ってデプロイを承認または拒否する

環境へのデプロイは、IT サービス管理 (ITSM) システムで承認されたチケット、依存関係に対する脆弱性スキャン結果、クラウド リソースの安定した正常性メトリックなど、任意の外部サービスで定義された条件に基づいて承認または拒否できます。 デプロイの承認または拒否の判断は、統合するサードパーティのアプリケーションと、その中で定義する制御条件によって決まります。 デプロイ保護規則を作成できるユース ケースの一部を次に示します。

• ITSM とセキュリティ オペレーション: デプロイの準備状況を確認する品質、セキュリティ、コンプライアンスのプロセスを確認することで、サービスの準備状況を確認できます。
• 監視システム: モニタリングまたは監視システム (Asset Performance Management Systems、ログ アグリゲーター、クラウド リソースの正常性検証システムなど) を参考にして、安全性とデプロイの準備状況を確認できます。
• コード品質とテスト ツール: 環境にデプロイする必要がある CI ビルドに対する自動テストを確認できます。

また、上記のユース ケースのいずれかに対して独自の保護規則を作成することや、運用前環境から運用環境へのデプロイを安全に承認または拒否するカスタム ロジックを定義することもできます。

GitHub Apps を使ったカスタム デプロイ保護規則の作成

1. GitHub App を作成します。 詳しくは、「GitHub App の登録」を参照してください。 次のように GitHub App を構成します。

   1. 必要に応じて [ユーザーの識別と認可] の下にある [コールバック URL] テキスト フィールドにコールバック URL を入力します。 詳しくは、「ユーザー承認コールバック URL について」を参照してください。
   2. [アクセス許可] で [リポジトリのアクセス許可] を選びます。
   3. [アクション] の右にあるドロップ ダウン メニューをクリックし、 [アクセス: 読み取り専用] を選びます。
      
   4. [デプロイ] の右側にあるドロップ ダウン メニューをクリックし、 [アクセス: 読み取りと書き込み] を選びます。
      
   5. [イベントへのサブスクライブ] で [デプロイ保護規則] を選びます。
      

2. カスタム デプロイ保護規則をリポジトリにインストールし、使用できるようにします。 詳しくは、「カスタム デプロイ保護規則の構成」を参照してください。

デプロイの承認または拒否

カスタム デプロイ保護規則を有効にした環境を参照するジョブにワークフローが到達すると、構成した URL 宛てに、GitHub から deployment_protection_rule ペイロードを含む POST 要求が送信されます。 deployment_protection_rule ペイロードに基づいてデプロイを承認または拒否する REST API 要求を自動的に送信するように、デプロイ保護規則を記述することができます。 次のように REST API 要求を構成します。

1. 受信 POST 要求を検証します。 詳しくは、「Webhook 配信を検証する」を参照してください。

2. JSON Web Token を使って GitHub App として認証を行います。 詳しくは、「GitHub Appとしての認証」を参照してください。

3. deployment_protection_rule Webhook ペイロードのインストール ID を使って、インストール トークンを生成します。 詳しくは、「GitHub アプリでの認証について」を参照してください。

   curl --request POST \
   --url "https://api.github.com/app/installations/INSTALLATION_ID/ACCESS_TOKENS" \
   --header "Accept: application/vnd.github+json" \
   --header "Authorization: Bearer {jwt}" \
   --header "Content-Type: application/json" \
   --data \
   '{ \
      "repository_ids": [321], \
      "permissions": { \
         "deployments": "write" \
      } \
   }'
   

4. 必要に応じて、GitHub.com に対して他のアクションを行わずに状態レポートを追加するには、POST 要求を /repos/OWNER/REPO/actions/runs/RUN_ID/deployment_protection_rule に送信します。 要求本文内では state を省略します。 詳しくは、「ワークフロー実行の REST API エンドポイント」を参照してください。 同じデプロイに関する状態レポートは、最大 10 回まで投稿できます。 状態レポートは Markdown 形式をサポートしており、最大 1,024 文字まで使用できます。

5. 要求を承認または拒否するには、POST 要求を /repos/OWNER/REPO/actions/runs/RUN_ID/deployment_protection_rule に送信します。 要求本文で、state プロパティを approved または rejected に設定します。 詳しくは、「ワークフロー実行の REST API エンドポイント」を参照してください。

6. 必要に応じて、GET 要求を /repos/OWNER/REPOSITORY_ID/actions/runs/RUN_ID/approvals に送信して、ワークフロー実行の承認状態を要求します。 詳しくは、「ワークフロー実行の REST API エンドポイント」を参照してください。

7. 必要に応じて、GitHub.com 上のデプロイを確認します。 詳しくは、「デプロイメントのレビュー」を参照してください。

GitHub Marketplace でのカスタム デプロイ保護規則の発行

開発者が適切な保護規則を見つけて自分の GitHub App リポジトリにインストールできるように、GitHub Marketplace に GitHub を発行することができます。 また、ニーズに合わせて既存のカスタム デプロイ保護規則を参照することもできます。 詳細については、「アプリの GitHub Marketplace について」および「GitHub Marketplace上でのアプリケーションのリスト」を参照してください。