マニフェストから GitHub App を作成する

GitHub App Manifest について

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

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

GitHub App Manifest を使用して構成済みのアプリケーションを作成するシナリオをいくつか挙げます。

• 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 にユーザをリダイレクトして新しい GitHub App を作成する。
2. GitHub がユーザをリダイレクトしてサイトに戻す。
3. 一時コードをやり取りして、アプリケーションの構成を取得する。

1. GitHub にユーザーをリダイレクトして新しい GitHub アプリを作成する

ユーザーをリダイレクトして新しい GitHub アプリを作成するには、クリックすると個人アカウントの� �合は https://github.com/settings/apps/new に、組織アカウントの� �合は https://github.com/organizations/ORGANIZATION/settings/apps/new に対して POST 要求を送信するリンクを提供します。ORGANIZATION は、アプリを作成する組織アカウントの名前に置き換えます。

GitHub App Manifest パラメーターを、JSON でエンコードされた文字列として manifest というパラメーターに含める必要があります。 また、セキュリティを強化するために state パラメーターを含めることもできます。

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

GitHub App Manifest のパラメータ

名前	型	説明
name	string	GitHub App の名前。
url	string	必� �。 GitHub アプリのホー� ページ。
hook_attributes	object	GitHub App の webhook の構成。
redirect_url	string	ユーザーがマニフェストから GitHub アプリの作成を開始した後にリダイレクトする完全な URL。
callback_urls	array of strings	インストールの承認後にリダイレクトする完全な URL。 最大 10 個のコールバック URL を指定できます。
description	string	GitHub App の説明。
public	boolean	GitHub アプリを公開する� �合は true に設定し、アプリの所有者のみがアクセスできるようにするには false に設定します。
default_events	array	GitHub アプリがサブスクライブするイベントのリスト。
default_permissions	object	GitHub アプリに必要なアクセス許可のセット。 このオブジェクトの形式は、キーとしてアクセス許可の名前 (たとえば issues) を、値としてアクセスの種類 (たとえば write) を使います。

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"> Create 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"> Create 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 App をインストールできます。 所有者は、GitHub API を使用してアプリケーションを拡張したり、所有権を他のユーザに移譲したり、任意の時に削除したりできます。

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

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

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

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

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

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

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