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
を受け取ります。
注釈: 1 時間以内に、GitHub App Manifest フローの以下の 3 つのステップすべてを完了する必要があります。
GitHub App Manifest フローを実装するには、以下の 3 つのステップに従います。
- GitHub にユーザをリダイレクトして新しい GitHub App を作成する。
- GitHub がユーザをリダイレクトしてサイトに戻す。
- 一時コードをやり取りして、アプリケーションの構成を取得する。
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 を作成するには、次の手順に従います。
- 新しい GitHub App を作成します。
- 作成したプロジェクトを開き、
app.yml
ファイルの設定をカスタマイズします。 Probotは、app.yml
の設定を GitHub App Manifest パラメータとして使用します。 - アプリケーションのカスタムコードを追加します。
- 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 について」を参照してください。