マニフェストから GitHub App を登録する

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

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

Probot を使用して、GitHub App マニフェストの作業を開始したり、実装例を確認したりできます。詳細については、「Probot を使用して GitHub App マニフェストフローを実装する」を参照してください。

GitHub App マニフェストを使って事前構成済みのアプリを登録するシナリオを次にいくつか挙げます。

GitHub Apps を開発時に、新しい Team メンバーが迅速に取りかかれるようにする。
他のユーザーが GitHub API を使用して、アプリを構成せずに GitHub App を拡張できるようにする。
GitHub コミュニティで共有する GitHub App の参照デザインを作成する。
開発環境と本番環境で確実に同じ構成を使用して GitHub Apps をデプロイする。
GitHub Appの構成に対するリビジョンを追跡する。

GitHub App マニフェストフローを実装する。

GitHub App マニフェストフローでは、OAuth フローに似たハンドシェイクプロセスが使用されます。このフローでは、マニフェストを使用して GitHub App を登録し、アプリの秘密キー、Webhook シークレット、ID の取得に使用される一時的な code を受け取ります。

Note

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

GitHub App マニフェストフローを実装するには、以下の 3 つのステップに従います。

ユーザーを 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 パラメーターに含めたアプリの名前をユーザーが編集できる入力フィールドがあります。 manifest に name を含めない場合は、ユーザーがこのフィールドでアプリの独自の名前を設定できます。

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

名前	種類	説明
`name`	`string`	GitHub App の名前。
`url`	`string`	必須。 GitHub App のホームページ。
`hook_attributes`	`object`	GitHub App の Webhook の構成。
`redirect_url`	`string`	ユーザーがマニフェストから GitHub App の登録を開始した後にリダイレクトする完全な URL。
`callback_urls`	`array of strings`	インストールの承認後にリダイレクトする完全な URL。最大 10 個のコールバック URL を指定できます。
`setup_url`	`string`	追加設定が必要な場合、GitHub App をインストールした後にユーザーをリダイレクトする先の完全な URL。
`description`	`string`	GitHub App の説明。
`public`	`boolean`	GitHub App を公開する場合は `true` に設定し、アプリの所有者のみがアクセスできるようにするには `false` に設定します。
`default_events`	`array`	GitHub App からサブスクライブされるイベントのリスト。
`default_permissions`	`object`	GitHub App で必要な権限セット。このオブジェクトの形式は、キーとしてアクセス許可の名前 (たとえば `issues`) を、値としてアクセスの種類 (たとえば `write`) を使います。詳しくは、「GitHub アプリのアクセス許可を選択する」を参照してください。
`request_oauth_on_install`	`boolean`	`true` に設定すると、GitHub App がインストールされた後に、GitHub App を承認するようにユーザーに要求します。
`setup_on_update`	`boolean`	`true` に設定すると、GitHub App のインストールを更新した後、ユーザーを `setup_url` にリダイレクトします。

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

Name	種類	説明
`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 を作成] がクリックされると、コードパラメーター内の一時的な code で GitHub がredirect_urlにリダイレクトします。次に例を示します。

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

state パラメーターを指定した場合は、そのパラメーターも redirect_url に表示されます。たとえば次のような点です。

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

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

ハンドシェイクを完了するには、「マニフェストから GitHub App を作成する」のエンドポイントに対して POST 要求で一時的な code を送信します。応答には、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 は Node.js で構築されたフレームワークです。Webhook の検証や認証の実行など、すべての GitHub Apps で必要になるタスクの多くを実行できます。 Probot に GitHub App マニフェストフローが導入されると、GitHub コミュニティで GitHub App のリファレンスデザインの作成と共有がしやすくなります。

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

新しい GitHub App を作成します。
作成したプロジェクトを開き、app.yml ファイルの設定をカスタマイズします。 Probot では、app.yml の設定が GitHub App マニフェストパラメーターとして使用されます。
アプリケーションのカスタムコードを追加します。
GitHub App をローカルで実行するか、任意の場所でホストします。ホストされたアプリの URL に移動すると、 [GitHub App を登録] ボタンがある Web ページが表示され、これをクリックすると事前構成済みのアプリを登録できます。

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

Glitch でアプリケーションをホストする

アプリをホストおよび共有するために Glitch を使用した Probot アプリの例を確認できます。この例では、Checks API を使用し、app.yml ファイルで必要な Checks API イベントとアクセス許可を選択します。 Glitch は、既存のアプリケーションを流用して独自のアプリケーションを作成 (リミックス) できるツールです。アプリケーションをリミックスすると、アプリケーションのコピーが作成され、Glitch はそれをホストしてデプロイします。 Glitch アプリのリミックスについては、Glitch の概要に関するページを参照してください。

マニフェストから GitHub App を登録する

この記事の内容