URL パラメーターを使用したGitHub アプリの登録

登録用の URL パラメーターについて GitHub Apps

URL パラメーターを使用して、新しい GitHub App 登録の構成設定を事前に選択し、カスタムリンクを他のユーザーと共有できます。このリンクにより、ユーザーは GitHub App 登録ページに移動します。このページでは、URL に含めた URL パラメーターに従ってアプリの設定が事前に入力されます。

このアプローチは、特定の仕様を使用して個人のアカウントまたは組織にアプリを設定したいインテグレーターや、GitHub Enterprise ServerからアプリをインストールできないGitHub Marketplaceを使用しているお客様に役立ちます。

または、 GitHub App マニフェストを作成することもできます。詳しくは、「マニフェストからのGitHub アプリの登録」をご覧ください。

メモ

この記事には、github.com ドメインを使うコマンドまたは例が含まれています。 GitHub など、別のドメインで octocorp.ghe.com にアクセスすることもできます。

クエリパラメーターを使用したカスタム構成 URL の作成

個人または組織のアカウントで GitHub App のカスタム構成 URL を作成するには、次の基本 URL の後にクエリパラメーターを追加します。

個人用アカウントでアプリを登録する場合は、https://github.com/settings/apps/new に URL パラメーターを追加します
組織アカウントでアプリを登録する場合は、https://github.com/organizations/ORGANIZATION/settings/apps/new に URL パラメーターを追加します。 ORGANIZATION は、顧客にアプリを登録してもらいたい組織の名前に置き換えてください。
Enterprise アカウントでアプリを登録する場合は、https://github.com/enterprises/ENTERPRISE/settings/apps/new に URL パラメーターを追加します。 ENTERPRISEを、顧客がアプリを登録する企業の名前に置き換えます。

アプリ登録ページ上で、アプリを登録するユーザーは、事前選択されている値を編集してから、アプリを送信することができます。 URL クエリ文字列に必須の値のパラメーター (name など) を含めない場合は、アプリを登録するユーザーが、アプリを登録する前に値を入力する必要があります。

たとえば、次の URL では、個人用アカウントで octocat-github-app という名前の新しいパブリックアプリを登録します。クエリパラメーターを使用すると、URL によって説明とコールバック URL が事前に構成されます。また、checks に対して読み取りと書き込みのアクセス許可が選ばれ、webhook_active パラメーターを使用して Webhook がアクティブにされ、check_run と check_suite の Webhook イベントにサブスクライブされ、インストール時にユーザーの認可 (OAuth) を要求するオプションが選ばれます。

https://github.com/settings/apps/new?name=octocat-github-app&description=An%20Octocat%20App&callback_urls[]=https://example.com&request_oauth_on_install=true&public=true&checks=write&webhook_active=true&events[]=check_run&events[]=check_suite

GitHub App 構成パラメーター

次のクエリパラメーターを使用して、 GitHub App 登録の特定の構成を選択できます。たとえば、アプリに "octocat-github-app" という名前を付ける場合、クエリ文字列には name=octocat-github-app が含められます。

パラメーター名	タイプ	説明
`name`	`string`
GitHub Appの名前。アプリケーションには簡潔で明快な名前を付けましょう。アプリが独自のユーザーまたは組織名でない限り、既存の GitHub ユーザーと同じ名前を持つことはできません。インテグレーションが動作すると、ユーザインターフェース上にアプリケーション名のスラッグが表示されます。
`description`	`string`
GitHub Appの説明。
`url`	`string`
GitHub Appの Web サイトホームページの完全な URL。
`callback_urls`	`array of strings`	インストールの承認後にリダイレクトする完全な URL。最大 10 個のコールバック URL を指定できます。これらの URL は、アプリでユーザーアクセストークンを生成する必要がある場合に使用されます。たとえば、「 `callback_urls[]=https://example.com&callback_urls[]=https://example-2.com` 」のように入力します。詳しくは、「ユーザー承認コールバック URL について」をご覧ください。
`request_oauth_on_install`	`boolean`	アプリが OAuth フローを使ってユーザーを認可する場合、このオプションを `true` に設定して、ユーザーがインストール時にアプリを認可して、ステップを省略できるようにすることができます。このオプションを選んだ場合、`setup_url` は利用できなくなり、ユーザーはアプリのインストール後に設定された `callback_url` にリダイレクトされます。
`setup_url`	`string`	アプリがインストール後に追加のセットアップを必要とする場合に、他のユーザーが GitHub App をインストールした後にリダイレクトする完全な URL。詳しくは、「セットアップ URL について」をご覧ください。
`setup_on_update`	`boolean`
`true` に設定すると、たとえばリポジトリが追加や削除された後など、ユーザーはインストールが更新されたときのセットアップ URL にリダイレクトします。
`public`	`boolean`	アプリが公開されている場合は`true`に設定し、アプリの所有者のみがアクセスできる場合はGitHub Appに設定します。このパラメーターは、Enterprise が所有するアプリには適用されません。
`webhook_active`	`boolean`	Webhook を有効にするには、`true` に設定します。既定では、Webhook は無効になっています。
`webhook_url`	`string`	webhook イベントペイロードを送信するための宛先となる完全な URL。
`events`	`array of strings`	Webhook イベント。一部の webhook イベントでは、新しいGitHub Appを登録する際にイベントを選択する前に、リソースに対する`read`または`write`のアクセス許可が必要です。詳細については、「webhook イベントのGitHub App」セクションを参照してください。クエリ文字列では、複数のイベントを選択できます。たとえば、「 `events[]=public&events[]=label` 」のように入力します。
`single_file_name`	`string`	これは、アプリケーションが任意のリポジトリの単一のファイルにアクセスできるようにするための、スコープの狭い権限です。
`single_file`アクセス許可を`read`または`write`に設定すると、このフィールドには、GitHub Appが管理する 1 つのファイルへのパスが表示されます。複数のファイルを管理する必要がある場合は、下の `single_file_paths` をご覧ください。
`single_file_paths`	`array of strings`	アプリケーションが、リポジトリ内の指定した最大 10 ファイルにアクセスできるようにします。
`single_file`アクセス許可を`read`または`write`に設定すると、この配列には、GitHub Appが管理する最大 10 個のファイルのパスを格納できます。これらのファイルには、それぞれ別のアクセス許可があたえられるでのではなく、すべてに `single_file` で設定されている同じアクセス許可が与えられます。 2 つ以上のファイルが構成されていると、API は `multiple_single_files=true` を返し、それ以外の場合は `multiple_single_files=false` を返します。

GitHub App アクセス許可

クエリパラメーターを使用して、 GitHub App 登録のアクセス許可を選択できます。 URL クエリパラメーターの場合は、クエリパラメーター名としてアクセス許可名を使用し、クエリ値をそのアクセス許可セットに使用できる値のいずれかに設定します。

たとえば、contents のユーザーインターフェイスで "読み取りと書き込みのアクセス許可" を選ぶには、クエリ文字列に contents=write を含めます。 blocking のユーザーインターフェイスで "読み取りと書き込みのアクセス許可" を選ぶには、クエリ文字列に blocking=read を含めます。 checksのユーザーインターフェイスで [アクセスなし] を選択する場合、クエリ文字列にchecksアクセス許可は含まれません。

所有しているアカウントが企業または企業所有の組織でない場合は、エンタープライズアクセス許可を要求できません。

アクセス許可と GitHub Appsの詳細については、「 GitHub アプリのアクセス許可の選択」を参照してください。使用できるアクセス許可とパラメーター化された名前の一覧については、「個人用アクセストークンを管理する」を参照してください。

GitHub App Webhook イベント

クエリパラメーターを使用すると、 GitHub App webhook を有効にしたり、webhook URL を指定したり、アプリをサブスクライブして特定のイベントの Webhook ペイロードを受信したりできます。

GitHub App webhook を有効にするには、クエリ文字列でwebhook_active=trueを使用します。 Webhook イベントペイロードの送信先とする URL を完全に指定するには、クエリ文字列内で webhook_url を使用します。アプリを特定の Webhook ペイロードイベントにサブスクライブするには、クエリパラメーター名として events[] を使用し、クエリ値を Webhook イベントの名前に設定します。使用可能な Webhook イベントと、各イベントをサブスクライブするために必要な GitHub App アクセス許可の詳細については、 Webhook のイベントとペイロードを参照してください。

たとえば、コミットコメントに関連するアクティビティの webhook ペイロードを受信する GitHub App をサブスクライブするには、クエリ文字列に &webhook_active=true&webhook_url=https://example.com&events[]=commit_commentが含まれます。 commit_comment webhook イベントでは、GitHub Appが "Contents" リポジトリのアクセス許可に対して少なくとも読み取りレベルのアクセス権を持っている必要があることに注意してください。そのため、クエリ文字列には、contents アクセス許可を read または write に設定するためのパラメーターも含める必要があります。詳細については、「 GitHub アプリのアクセス許可」を参照してください。

クエリパラメーターを使用して Webhook シークレットの値を設定することはできません。アプリで Webhook をセキュリティで保護するためにシークレットが必要な場合は、アプリを登録するユーザーが GitHub UI でシークレットの値を設定する必要があります。

webhook と GitHub Appsの詳細については、 AUTOTITLE を参照してください。