マニフェストから 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 App を登録 し、アプリケーションの秘密鍵、webhook シークレット、およびID を取得するための一時 code を受け取ります。

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

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

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

新しい GitHub App を作成するためユーザをリダイレクトするには、ユーザアカウントが https://github.com/settings/apps/new に、または Organization アカウントが https://github.com/organizations/ORGANIZATION/settings/apps/new に POST リクエストをクリックして送信するためのリンクを指定します。ORGANIZATION は、アプリケーションが作成される Organization アカウントの名前で置き換えてください。

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

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

GitHub App Manifest のパラメータ

名前	種類	説明
name	string	GitHub App の名前。
url	string	必須。GitHub App のホームページ。
hook_attributes	オブジェクト	GitHub App の webhook の構成。
redirect_url	string	ユーザがマニフェストから GitHub App の作成を開始した後にリダイレクトする完全な URL。
callback_url	string	インストールの承認後にリダイレクトする完全な URL。
説明	string	GitHub App の説明。
public	boolean	GitHub App を公開する場合には true に、アプリケーションの所有者のみがアクセスできるようにするには false を設定。
default_events	array	GitHub App がサブスクライブするイベントのリスト。
default_permissions	オブジェクト	GitHub App が必要とする権限のセット。 オブジェクトのフォーマットでは、キーの権限名 (issues など) と、値のアクセスタイプ (write など) を使用します。

hook_attributes オブジェクトは、以下のキーを持っています。

名前	種類	説明
url	string	必須。webhook の POST リクエストを受信するサーバーの URL です。
active	boolean	フックがトリガーされた時に、イベントの内容が配信される (デフォルトはtrue)。

パラメータ

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

サンプル

この例では、ウェブページ上にユーザアカウントに対して POST リクエストをトリガするボタンがあるフォームを使用します。

<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_url": "https://example.com/callback",
   "public": true,
   "default_permissions": {
     "issues": "write",
     "checks": "write"
   },
   "default_events": [
     "issues",
     "issue_comment",
     "check_suite",
     "check_run"
   ]
 })
</script>

この例では、ウェブページ上に Organization アカウントに対して POST リクエストをトリガするボタンがあるフォームを使用します。 ORGANIZATION は、アプリケーションを作成する場所の 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_url": "https://example.com/callback",
   "public": true,
   "default_permissions": {
     "issues": "write",
     "checks": "write"
   },
   "default_events": [
     "issues",
     "issue_comment",
     "check_suite",
     "check_run"
   ]
 })
</script>

2. GitHub がユーザをリダイレクトしてサイトに戻す

Create GitHub App をクリックすると、GitHub はコードパラメータに一時的 code を付けて redirect_url にリダイレクトして戻します。 例:

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

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

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

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

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

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

POST /app-manifests/{code}/conversions

エンドポイントのレスポンスに関する詳しい情報については、マニフェストから GitHub App を作成するを参照してください。

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

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

Probot は Node.js で構築されたフレームワークで、webhook の検証や認証の実行といった、あらゆる GitHub App が必要とする多くのタスクを実行します。 Probot は GitHub App マニフェストフローを実装し、GitHub App のリファレンスデザインを作成し、GitHub コミュニティで共有することを容易化します。

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

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

dotenv を使用して、Probot は .env ファイルを作成し、APP_ID、PRIVATE_KEY、WEBHOOK_SECRET の環境変数に、アプリケーションの設定から取得した変数を設定します。

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

Probot アプリケーションのサンプルで、Glitch でアプリケーションをホストして共有する例を見ることができます。 この例では、Checks API を使用し、app.yml ファイルで、必要な Checks API イベントと権限を選択しています。 Glitch は、既存のアプリケーションを流用して独自のアプリケーションを作成 (リミックス) できるツールです。 アプリケーションをリミックスすると、アプリケーションのコピーが作成され、Glitch はそれをホストしてデプロイします。 Glitch アプリケーションのリミックスについては、「Glitch について」を参照してください。