マニフェストから 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 を作成する

To redirect people to create a new GitHub App, provide a link for them to click that sends a POST request to https://github.com/settings/apps/new for a personal account or https://github.com/organizations/ORGANIZATION/settings/apps/new for an organization account, replacing ORGANIZATION with the name of the organization account where the app will be created.

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	The full URL to redirect to after a user initiates the creation of a GitHub App from a manifest.
callback_urls	array of strings	インストールの承認後にリダイレクトする完全な URL。 最大 10 個のコールバック 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	推測不能なランダ� の文字列。 クロスサイトリクエストフォージェリ攻撃に対する保護として使われます。

サンプル

This example uses a form on a web page with a button that triggers the POST request for a personal account:

<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>

この例では、ウェブページ上に 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_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 がユーザをリダイレクトしてサイトに戻す

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 について」を参照してく� さい。