LoginSignup
3
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@reoring(れおりん)inCraftsman Software

GitHub Appマニフェストを使用したGitHub Appの登録方法の詳細

Posted at

GitHub Appマニフェストとは

GitHub Appマニフェストとは、あらかじめ設定済みのGitHub Appの登録情報を共有できる仕組みです (マニフェストから GitHub App を登録する - GitHub Docs)。マニフェストにはアプリの権限やイベント、Webhook URLなど必要な設定内容が含まれており、それを使ってユーザーが素早く新しいGitHub Appを作成（登録）できます (Registering a GitHub App from a manifest - GitHub Docs) (マニフェストから GitHub App を登録する - GitHub Docs)。マニフェスト経由でGitHub Appを登録すると、GitHub側で自動的にそのアプリのWebhookシークレット（秘密のトークン）、プライベートキー（PEM形式）、クライアントシークレット、およびGitHub App IDが生成されます (マニフェストから GitHub App を登録する - GitHub Docs)。このようにマニフェストを使うことで、ユーザーは複雑な設定を一から入力する手間を省き、決められた構成でアプリを登録できるのが特徴です。

マニフェストを使ったGitHub App登録フロー

GitHub Appマニフェストを用いた登録フローは、OAuth認証に似た3段階のハンドシェイク手順で行われます (マニフェストから GitHub App を登録する - GitHub Docs)。以下のステップに従って、新しいGitHub Appをマニフェストから登録します。

  1. GitHubへのリダイレクトとマニフェスト送信 – ユーザーをGitHubのアプリ作成ページにリダイレクトし、そこでマニフェスト（JSON形式の設定情報）を送信します。具体的には、個人アカウントの場合はhttps://github.com/settings/apps/new（Organizationに作成する場合はhttps://github.com/organizations/組織名/settings/apps/new）に対して、HTTP POSTでmanifestというパラメーターを含めてリクエストします (Registering a GitHub App from a manifest - GitHub Docs)。manifestパラメーターの値はJSONエンコードされた文字列で、これにGitHub Appの設定内容を記述します (Registering a GitHub App from a manifest - GitHub Docs)。必要に応じて、CSRF対策用のstateパラメーター（推測困難なランダム文字列）も付与できます (Registering a GitHub App from a manifest - GitHub Docs) (マニフェストから GitHub App を登録する - GitHub Docs)。ユーザーがリンクをクリックするとGitHubの「新規GitHub App作成」ページが開き、そこに事前に指定された内容が反映されます（アプリ名はマニフェストで指定していれば編集可能な形で表示され、未指定の場合はユーザーが入力できます (Registering a GitHub App from a manifest - GitHub Docs)）。

    ※上記JSON全体を文字列にエンコードしてmanifestパラメータに設定します。必要な項目をあらかじめ指定しておくことで、ユーザーは最小限の入力（主にアプリ名の確認程度）で済むようになります。例えば、次のようなマニフェストJSONを組み立てて送信できます (Use GitHub App manifests to symplify your GitHub App registration flow - RunsOn) (Use GitHub App manifests to symplify your GitHub App registration flow - RunsOn):

    {
  "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"]
}

  2. GitHubからのリダイレクト受信 – ユーザーがGitHub上で「Create GitHub App」（アプリ作成）を実行すると、GitHubは先ほどマニフェストで指定したredirect_urlにユーザーのブラウザをリダイレクトします (Registering a GitHub App from a manifest - GitHub Docs)。このリダイレクト先URLには、クエリパラメータとして一時的なcode（コード）が付与されます (Registering a GitHub App from a manifest - GitHub Docs)。例えば次のように、https://example.com/redirect?code=...という形式でコードが渡されます (Registering a GitHub App from a manifest - GitHub Docs)。もし先ほどstateパラメータを付けていれば、それも同様に返ってくるので、リダイレクト先で受け取ったstate値が送信前のものと一致するか確認することでセキュリティ検証を行います (Registering a GitHub App from a manifest - GitHub Docs)。

    このcodeは一度きりかつ**短時間（1時間以内）**のみ有効なコードであり、後述の手順でアプリ情報を取得するために使用します (マニフェストから GitHub App を登録する - GitHub Docs) (マニフェストから GitHub App を登録する - GitHub Docs)。

  3. 一時コードの交換とアプリ情報の取得 – サービス（あなたのアプリケーション）のサーバー側では、受け取ったcodeを使ってGitHubのAPIエンドポイントにPOSTリクエストを送り、先ほど作成されたGitHub Appの詳細情報を取得します (Registering a GitHub App from a manifest - GitHub Docs)。このAPIは**「Create a GitHub App from a manifest」**と呼ばれるエンドポイントで、URLは次の形式になります (REST API endpoints for GitHub Apps - GitHub Docs):

    POST https://api.github.com/app-manifests/＜コード＞/conversions

    （＜コード＞の部分は受け取った一時コードに置き換えてください。）このリクエストに成功すると、応答(JSON)の中に先ほど作成されたGitHub Appの情報が含まれています。具体的には、アプリID (id)、アプリのスラッグ名 (slug)、クライアントIDおよびクライアントシークレット（OAuth用）、Webhookシークレット、そしてプライベートキー（pem）などが返ってきます (REST API endpoints for GitHub Apps - GitHub Docs) (REST API endpoints for GitHub Apps - GitHub Docs)。GitHubはWebhookシークレットを自動生成し、プライベートキーもこの時点で発行します (マニフェストから GitHub App を登録する - GitHub Docs)。これらの値はサーバー側で安全に保管し、後続の処理（例えば環境変数に設定してアプリで利用する等）に使用します (Registering a GitHub App from a manifest - GitHub Docs) (マニフェストから GitHub App を登録する - GitHub Docs)。なお、このcodeを使った交換（変換）処理は1時間以内に完了させる必要があります (マニフェストから GitHub App を登録する - GitHub Docs)。時間が経過するとコードは無効となり、再度最初からやり直す必要があります。

    ※上記エンドポイントへのアクセスは、GitHubユーザーの適切な認証コンテキストで行う必要があります（通常、GitHubにログイン済みのユーザーが自分のアカウントにアプリを作成するので、そのユーザー権限でのAPI呼び出しとなります）。エンドポイントは乱用防止のためレート制限があります (Registering a GitHub App from a manifest - GitHub Docs)。

以上がマニフェストフローの基本的な流れです。まとめると、事前定義されたアプリ設定(マニフェスト)をユーザー経由でGitHubに送り、一時コードを受け取り、そのコードを使ってアプリの認証情報を取得するというプロセスになります。この手順により、ユーザーは自分のアカウント（またはOrganization）に新しいGitHub Appを登録し、そのクレデンシャル情報を開発者側（あなたのサービス）が受け取ることができます。

具体的な使用例と実装パターン

上記のマニフェストフローは、実際のWebアプリケーションや統合サービスで広く利用されています。以下に、GitHub APIを活用した実装例や活用シナリオを紹介します。

  • 実装例: サーバー側でのコード交換処理 – マニフェストからの登録完了後に受け取るコードを、実際にAPI経由で変換する手順を簡単なスクリプトで示します。例えば、受け取ったcodeを使ってcURLコマンドでGitHub APIにリクエストする場合、以下のようになります（必要に応じて認証ヘッダーやAPIバージョンヘッダーを付与）:

    curl -X POST -H "Accept: application/vnd.github+json" \
     https://api.github.com/app-manifests/<取得したコード>/conversions

    上記のようにリクエストを送信すると、ステータス201（Created）とともにJSON形式の応答が返ってきます (REST API endpoints for GitHub Apps - GitHub Docs) (REST API endpoints for GitHub Apps - GitHub Docs)。応答には先述の通り、id, slug, html_url（GitHub上のアプリページURL）、client_id, client_secret, webhook_secret, pemなどのフィールドが含まれます (REST API endpoints for GitHub Apps - GitHub Docs) (REST API endpoints for GitHub Apps - GitHub Docs)。これらをパースして保存することで、プログラム上でGitHub Appの認証情報を扱えるようになります。例えばNode.js製のフレームワークProbotでは、このAPI応答を受け取って.envファイルにAPP_IDやPRIVATE_KEY（pem）、WEBHOOK_SECRETを自動で書き込み、アプリがすぐに動作できるようにしています (Registering a GitHub App from a manifest - GitHub Docs)。

  • 使用シナリオ: Probotによる開発と共有 – ProbotはGitHub App開発向けのNode.jsフレームワークで、マニフェストフローを簡単に利用できるようにしています (Registering a GitHub App from a manifest - GitHub Docs)。Probotでアプリを作成すると、プロジェクト内のapp.ymlファイルに今回説明したマニフェストの内容（権限やイベント等）を記述します (Registering a GitHub App from a manifest - GitHub Docs)。Probotが生成するローカルのウェブページには「Register GitHub App」というボタンが用意されており、開発者や利用者はそれをクリックするだけでマニフェストに基づいたGitHub Appを自分のアカウントに登録できます (Registering a GitHub App from a manifest - GitHub Docs)。登録後、Probotは自動的に返されたAPP_IDやPRIVATE_KEYなどを取得し、環境変数経由でアプリケーションにセットします (Registering a GitHub App from a manifest - GitHub Docs)。これにより、開発者は手動でキーをコピーすることなく、すぐにアプリ開発や動作検証を始められます。

  • 使用シナリオ: 社内ツールによる大量アプリ作成 – マニフェストフローは社内向けツールでも活用されています。ある事例では、JenkinsとGitHubを統合するために多数のGitHub Appを作成する必要がありましたが、手作業でアプリを一つひとつ登録するのは煩雑でミスが起こりがちでした (Create a GitHub App from a manifest)。そこで社内Webアプリを用意し、GitHub Appマニフェストを利用して必要な設定が事前に施されたアプリを自動作成する仕組みを導入しました (Create a GitHub App from a manifest) (Create a GitHub App from a manifest)。このツールでは、ユーザー（社内管理者）がWeb UI上で必要事項を選ぶと裏側でマニフェストを生成し、GitHubのアプリ作成ページにリダイレクトします。ユーザーがGitHub上で承認すると自社サービスにコードが返り、ツールがそのコードを使って自動的にアプリのIDや秘密鍵を取得・安全な保管まで行います (Create a GitHub App from a manifest)。このようにして各チーム専用のGitHub Appを次々と迅速に作成し、権限設定ミスも防止しています (Create a GitHub App from a manifest)。

  • 使用シナリオ: サードパーティサービスでの簡単インストール – 外部の統合サービスでも、マニフェストフローによりユーザーにスムーズな設定体験を提供している例があります。例えば、自前のGitHub Actionsランナーを管理するサービス「RunsOn」では、利用者が2〜3回クリックするだけで自分のOrganizationに必要なGitHub Appを登録できるようマニフェストを活用しています (Use GitHub App manifests to symplify your GitHub App registration flow - RunsOn)。ユーザーがサービス上で「GitHub Appを設定する」といったボタンを押すと、裏でマニフェストがGitHubに送られ、すぐにコードが返されます。サービス側でそのコードを交換してアプリの秘密鍵などを取得し、自動的に設定を完了してくれるため、ユーザーは複雑な手順を意識せず統合を利用開始できます (Use GitHub App manifests to symplify your GitHub App registration flow - RunsOn)。

これらの例から分かるように、GitHub Appマニフェストによる登録は開発者やサービス提供者にとって非常に便利な手段であり、ユーザーにとってもシンプルな操作で必要なアプリ連携を行えるメリットがあります。

マニフェスト利用のメリット

GitHub Appマニフェストを活用することで得られる主なメリットは以下のとおりです。

以上のように、マニフェストによる方法は迅速・確実なセットアップとシームレスなシークレット共有を実現し、開発・運用上の利点が大きいです。

他のGitHub App登録方法との比較

GitHub Appを登録する方法にはマニフェスト以外にもいくつか選択肢があります。それぞれの特徴を比較すると次の通りです。

  • 手動での登録（GitHub設定画面で作成）: GitHubの「Developer settings > GitHub Apps」から新規アプリを作成する従来の方法です。フォームに名称や説明、コールバックURL、Webhook URL、必要な権限・イベント等をすべて自分で入力します (Create a GitHub App from a manifest)。作成後、プライベートキーの生成やWebhookシークレットのコピーも自分で行う必要があります。メリットはGitHub上で直接設定できる安心感がありますが、手順が煩雑で入力ミスの可能性があります。また多数のアプリを一貫した設定で作成するには不向きです (Create a GitHub App from a manifest)。

  • URLクエリパラメーターによる事前設定: マニフェストほどではありませんが、あらかじめ設定を埋め込んだカスタムURLを共有してアプリ登録を簡略化する方法もあります (Registering a GitHub App using URL parameters - GitHub Enterprise Server 3.11 Docs)。例えば、必要なパラメータ（nameやdescription、callback_url、各種権限指定など）をクエリ文字列に含めた専用URLをユーザーに提供すると、そのリンクから開かれるGitHubの登録ページでは値が事前入力された状態になります (Registering a GitHub App using URL parameters - GitHub Enterprise Server 3.11 Docs) (Registering a GitHub App using URL parameters - GitHub Enterprise Server 3.11 Docs)。ユーザーは不足項目を補って送信するだけで済むため多少の手間削減になります。ただし秘密情報の自動取得はできないため、結局ユーザーが作成後に自分で秘密鍵を取得してサービス側に登録する必要があります。また、マニフェストのようなコード交換のステップがないため、開発者側が登録完了を自動検知したり情報を直接得たりすることはできません (Create a GitHub App from a manifest)。簡易的なリンク共有で済む反面、完全な自動化にはつながらない点がマニフェストとの違いです。

  • マニフェスト（今回紹介した方法）: 上記の通り、ユーザー操作の簡略さと開発者側での自動処理の双方を実現する方法です (マニフェストから GitHub App を登録する - GitHub Docs) (Create a GitHub App from a manifest)。リンク先に事前設定を埋め込みつつ、コードハンドシェイクにより秘密情報を安全に取得できる点で他の方法より優れています。唯一の欠点は、完全にプログラムだけでアプリを登録することはできずユーザーの関与が必要なことです（ユーザーがGitHub上で「作成」を承認するステップは省略できません） (Create a github app programmatically without user interaction? - Stack Overflow)。しかしこれはGitHubのセキュリティポリシー上避けられない部分であり、裏を返せばユーザーに明示的な許可を得たうえで安全にアプリを発行できるとも言えます。

まとめると、手動登録は柔軟ですが手間がかかり、URLパラメーター方式は一部自動化できるものの秘密情報取得には対応していません。それに対してマニフェスト方式はユーザー体験と自動化のバランスが良く、他の方法よりも迅速かつ正確にGitHub Appを展開できる点で優れています (Use GitHub App manifests to symplify your GitHub App registration flow - RunsOn) (Create a GitHub App from a manifest)。用途に応じて使い分けられますが、再現性のある設定や多数展開が求められる場合、マニフェストからの登録が有力な選択肢となるでしょう。 (Registering a GitHub App using URL parameters - GitHub Enterprise Server 3.11 Docs)

3
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
3
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?