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

GitHub App Manifest について

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

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

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

GitHub App を開発時に、新しい Team メンバーが迅速に取りかかれるようにする。
他のユーザーがアプリケーションを構成する必要なく、GitHub API を使用して GitHub App を拡張できるようにする。
GitHub コミュニティに共有するため、GitHub App リファレンスデザインを作成する。
開発環境と本番環境で確実に同じ構成を使用して GitHub App をデプロイする。
GitHub App の構成のリビジョンを追跡する。

GitHub App Manifest フローを実装する

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

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

GitHub App Manifest フローを実装するには、以下の 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 Manifest パラメーターを、JSON でエンコードされた文字列として manifest というパラメーターに含める必要があります。また、セキュリティを強化するために state パラメーターを含めることもできます。

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

GitHub App Manifest のパラメータ

名前	種類	説明
`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 アプリに必要なアクセス許可のセット。このオブジェクトの形式は、キーとしてアクセス許可の名前 (たとえば `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 アプリの作成] をクリックすると、GitHub によって、コードパラメーターに一時的な code を含む redirect_url にリダイレクトされます。たとえば次のような点です。

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

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

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

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

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

GitHub App Manifest フローのこのステップを、1 時間以内に完了する必要があります。

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

POST /app-manifests/{code}/conversions

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

マニフェストフローの最後の手順を完了すると、フローからアプリを登録したユーザーは登録した GitHub App の所有者となり、そのユーザーの任意の個人用リポジトリにインストールできます。所有者は、GitHub API を使用してアプリケーションを拡張したり、所有権を他のユーザに移譲したり、任意の時に削除したりできます。

Probot を使用してGitHub App Manifest フローを実装する

Probot は Node.js で構築されたフレームワークです。Webhook の検証や認証の実行など、すべての GitHub アプリで必要になるタスクの多くを実行できます。 Probot によって GitHub App Manifest フローが実装され、簡単に GitHub アプリのリファレンスデザインを作成し、GitHub コミュニティと共有できます。

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

新しい GitHub アプリを生成します。
作成したプロジェクトを開き、app.yml ファイルの設定をカスタマイズします。 Probot では、app.yml の設定が GitHub App Manifest パラメーターとして使用されます。
アプリケーションのカスタムコードを追加します。
GitHub アプリをローカルで実行するか、任意の場所でホストします。ホストされたアプリの 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 の概要に関するページを参照してください。

この記事の内容