Skip to main content

このバージョンの GitHub Enterprise はこの日付をもって終了となりました: 2023-01-18. 重大なセキュリティの問題に対してであっても、パッチリリースは作成されません。 パフォーマンスの向上、セキュリティの向上、新機能の向上を図るために、最新バージョンの GitHub Enterprise にアップグレードします。 アップグレードに関するヘルプについては、GitHub Enterprise サポートにお問い合わせく� さい

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

GitHub App Manifest は、アプリケーションを個人のリポジトリで使いたい人と共有できる、構成済みの GitHub App です。 マニフェストフローにより、ユーザはアプリケーションを登録したり、ホストされたアプリケーションコードに登録を接続したりすることなく、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 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 パラメーターに含めたアプリの名前をユーザーが編集できる入力フィールドがあります。 manifestname を含めない� �合は、ユーザーがこのフィールドでアプリの独自の名前を設定できます。

GitHub App Manifest の作成

GitHub App Manifest のパラメータ

名前Type説明
namestringGitHub App の名前。
urlstring必� �。 GitHub アプリのホー� ページ。
hook_attributesobjectGitHub App の webhook の構成。
redirect_urlstringユーザーがマニフェストから GitHub アプリの作成を開始した後にリダイレクトする完全な URL。
callback_urlsarray of stringsインストールの承認後にリダイレクトする完全な URL。 最大 10 個のコールバック URL を指定できます。
setup_urlstring追� 設定が必要な� �合、GitHub アプリをインストールした後にユーザーをリダイレクトする先の完全な URL。
descriptionstringGitHub App の説明。
publicbooleanGitHub アプリを公開する� �合は true に設定し、アプリの所有者のみがアクセスできるようにするには false に設定します。
default_eventsarrayGitHub アプリがサブスクライブするイベントのリスト。
default_permissionsobjectGitHub アプリに必要なアクセス許可のセット。 このオブジェクトの形式は、キーとしてアクセス許可の名前 (たとえば issues) を、値としてアクセスの種類 (たとえば write) を使います。

hook_attributes オブジェクトには、次のキーがあります。

名前Type説明
urlstring必� �。 Webhook の POST 要求を受け取るサーバーの URL。
activebooleanフックがトリガーされた時に、イベントの内容が配信される (デフォルトはtrue)。

パラメーター

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

次の例では、個人アカウントに対して 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 フローを実装する

ProbotNode.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 GitHub App の登録

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

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

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