マニフェストからのGitHub アプリの登録

          GitHub App マニフェストについて

メモ

GitHub App マニフェストは、エンタープライズ所有の GitHub Appsでは使用できません。

マニフェストから GitHub App を登録するユーザーは、URL に従ってアプリに名前を付けるだけで済みます。マニフェストには、アプリケーションを自動的に登録するために必要な権限、イベント、webhook URL が含まれています。マニフェストフローは、 GitHub App 登録を作成し、アプリの webhook シークレット、秘密キー (PEM ファイル)、クライアントシークレット、および GitHub App ID を生成します。マニフェストから GitHub App 登録を作成するユーザーは、 GitHub App 登録を所有し、登録の設定の編集、削除、または GitHub上の別のユーザーへの転送を選択できます。

          [Probot](https://probot.github.io/) を使用して、GitHub App マニフェストの使用を開始したり、実装例を確認したりできます。 詳細については、「 [Probot を使用した GitHub App マニフェスト フローの実装](#using-probot-to-implement-the-github-app-manifest-flow) 」を参照してください。

          GitHub App マニフェストを使用して事前構成済みのアプリを登録するシナリオを次に示します。

GitHub Appsを開発するときに、新しいチームメンバーが迅速に習得できるように支援します。
他のユーザーがアプリを構成しなくても、GitHub App API を使用してGitHubを拡張できるようにします。
GitHub App参照デザインを作成して、GitHub コミュニティと共有します。
同じ構成を使用して、 GitHub Apps を開発環境と運用環境にデプロイしてください。
GitHub App構成の変更履歴を追跡します。

          GitHub App マニフェスト フローの実装

          GitHub App マニフェスト フローでは、[OAuth フロー](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps)と同様のハンドシェイク プロセスが使用されます。 このフローでは、マニフェストを使用して[GitHub Appを登録](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)し、アプリの秘密キー、webhook シークレット、ID を取得するために使用される一時的な`code`を受け取ります。

メモ

GitHub App マニフェストフローの 3 つの手順をすべて 1 時間以内に完了する必要があります。

          GitHub App マニフェスト フローを実装するには、次の手順に従います。

ユーザーを GitHub にリダイレクトして、新しい GitHub Appを登録します。

       GitHub は、ユーザーをサイトにリダイレクトします。

一時コードをやり取りして、アプリケーションの構成を取得する。

1. ユーザーを GitHub にリダイレクトして新規登録する GitHub App

新しいGitHub Appを登録するようにユーザーをリダイレクトするには、個人アカウントのまたは組織アカウントのPOSTにhttps://github.com/settings/apps/new要求を送信するリンクをユーザーにhttps://github.com/organizations/ORGANIZATION/settings/apps/newし、ORGANIZATIONをアプリが登録される組織アカウントの名前に置き換えます。

インクルードする必要があるのは、パラメーター GitHub App にマニフェストパラメーターを JSON エンコード文字列として含むパラメーター manifest です。また、セキュリティを強化するために stateパラメーターを含めることもできます。

アプリを登録しているユーザーは、GitHub パラメーターに含めたアプリの名前を編集できる入力フィールドを持つmanifest ページにリダイレクトされます。 name に manifest を含めない場合は、ユーザーがこのフィールドでアプリの独自の名前を設定できます。

          GitHub App マニフェスト パラメーター

名前	タイプ	説明
`name`	`string`

          GitHub Appの名前。

          `hook_attributes` オブジェクトには、次のキーがあります。

名前	タイプ	説明
`url`	`string`

          **必須。** Webhook の `POST` 要求を受け取るサーバーの URL。

active | boolean | フックがトリガーされた時に、イベントの内容が配信される (デフォルトはtrue)。

パラメーター

名前	タイプ	説明
`state`	`string`	推測不能なランダムの文字列。クロスサイトリクエストフォージェリ攻撃に対する保護として使われます。

例一覧

次の例では、個人アカウントに対して POST 要求をトリガーするボタンがある Web ページ上のフォームを使用します。

<form action="https://github.com/settings/apps/new?state=abc123" method="post">
 Register a GitHub App Manifest: <input type="text" name="manifest" id="manifest"><br>
 <input type="submit" value="Submit">
</form>

<script>
 input = document.getElementById("manifest")
 input.value = JSON.stringify({
   "name": "Octoapp",
   "url": "https://www.example.com",
   "hook_attributes": {
     "url": "https://example.com/github/events",
   },
   "redirect_url": "https://example.com/redirect",
   "callback_urls": [
     "https://example.com/callback"
   ],
   "public": true,
   "default_permissions": {
     "issues": "write",
     "checks": "write"
   },
   "default_events": [
     "issues",
     "issue_comment",
     "check_suite",
     "check_run"
   ]
 })
</script>

次の例では、組織アカウントに対して POST 要求をトリガーするボタンがある Web ページ上のフォームを使用します。 ORGANIZATION は、アプリを登録したい組織アカウントの名前に置き換えてください。

<form action="https://github.com/organizations/ORGANIZATION/settings/apps/new?state=abc123" method="post">
 register a GitHub App Manifest: <input type="text" name="manifest" id="manifest"><br>
 <input type="submit" value="Submit">
</form>

<script>
 input = document.getElementById("manifest")
 input.value = JSON.stringify({
   "name": "Octoapp",
   "url": "https://www.example.com",
   "hook_attributes": {
     "url": "https://example.com/github/events",
   },
   "redirect_url": "https://example.com/redirect",
   "callback_urls": [
     "https://example.com/callback"
   ],
   "public": true,
   "default_permissions": {
     "issues": "write",
     "checks": "write"
   },
   "default_events": [
     "issues",
     "issue_comment",
     "check_suite",
     "check_run"
   ]
 })
</script>

2. ユーザーをサイトにリダイレクトGitHub

ユーザーが [GitHub Appの作成] をクリックすると、GitHubコードパラメーターに一時的なredirect_urlを含むcodeにリダイレクトされます。次に例を示します。

https://example.com/redirect?code=a180b1a3d263c81bc6441d7b990bae27d4c10679

          `state` パラメーターを指定した場合は、そのパラメーターも `redirect_url` に表示されます。 次に例を示します。

https://example.com/redirect?code=a180b1a3d263c81bc6441d7b990bae27d4c10679&state=abc123

3. 一時的なコードを交換してアプリの構成を取得する

ハンドシェイクを完了するには、一時的なcodeをPOST要求に含め、マニフェストからGitHub Appを作成するエンドポイントに送信します。応答には、 id (GitHub App ID)、 pem (秘密キー)、および webhook_secretが含まれます。 GitHub は、アプリの Webhook シークレットを自動的に作成します。これらの値は、アプリケーションのサーバーの環境変数に格納できます。たとえば、アプリで dotenv を使用して環境変数を格納する場合は、アプリの .env ファイルに変数を格納します。

          GitHub App マニフェスト フローのこの手順は、1 時間以内に完了する必要があります。

メモ

このエンドポイントはレート制限されています。現在のレート制限状態を確認する方法については、「レート制限」を参照してください。

POST /app-manifests/{code}/conversions

エンドポイントの応答の詳細については、「マニフェストから GitHub App を作成する」を参照してください。

マニフェストフローの最後の手順が完了すると、フローからアプリを登録するユーザーは、任意のアカウントにインストールできる登録済み GitHub App の所有者になります。 GitHub API を使用してアプリを拡張したり、所有権を他のユーザーに譲渡したり、いつでも削除したりできます。

Probot を使用して GitHub App マニフェストフローを実装する

          [Probot](https://probot.github.io/) は [ 、 ](https://nodejs.org/) webhook の検証や認証の実行など、すべての GitHub Appsで必要なタスクの多くを実行するNode.jsで構築されたフレームワークです。 Probot は[、GitHub App マニフェスト フロー](#implementing-the-github-app-manifest-flow)を実装し、GitHub App参照デザインを簡単に作成し、GitHub コミュニティと共有できるようにします。

共有する Probot App を作成するには、次の手順に従います。

       [新しいGitHub Appを生成](https://probot.github.io/docs/development/#generating-a-new-app)します。

作成したプロジェクトを開き、app.yml ファイルの設定をカスタマイズします。 Probot は、app.ymlマニフェストパラメーターとしてGitHub Appの設定を使用します。
アプリケーションのカスタムコードを追加します。

       [
       GitHub Appをローカルで実行](https://probot.github.io/docs/development/#running-the-app-locally)するか、任意の場所でホストします。 ホストされているアプリの URL に移動すると、[ **Register GitHub App** ]\(登録\) ボタンが表示された Web ページが表示され、ユーザーがクリックして事前構成済みアプリを登録できます。

Probot では、dotenv を使用して、.env ファイルを作成し、APP_ID、PRIVATE_KEY、WEBHOOK_SECRET 環境変数をアプリ構成から取得した値を使用して設定します。

この記事で

1. ユーザーを GitHub にリダイレクトして新規登録する GitHub App

パラメーター

例一覧

2. ユーザーをサイトにリダイレクトGitHub

3. 一時的なコードを交換してアプリの構成を取得する

Probot を使用して GitHub App マニフェスト フローを実装する

Probot を使用して GitHub App マニフェストフローを実装する