URL パラメーターを使って GitHub App を登録する

GitHub Apps

を登録するための URL パラメーターについて

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

このアプローチを有効に利用できるのは、顧客に特定の仕様で個人用アカウントまたは organization にアプリを設定してもらいたいインテグレーター、または GitHub Marketplace からアプリをインストールできない GitHub Enterprise Server を使用している顧客となります。

あるいは、GitHub App マニフェストを作成することもできます。詳しくは、「マニフェストから GitHub App を登録する」を参照してください。

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

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

個人用アカウントでアプリを登録する場合は、http(s)://HOSTNAME/settings/apps/new に URL パラメーターを追加します
組織アカウントでアプリを登録する場合は、http(s)://HOSTNAME/organizations/ORGANIZATION/settings/apps/new に URL パラメーターを追加します。 ORGANIZATION は、顧客にアプリを登録してもらいたい組織の名前に置き換えてください。

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

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

http(s)://HOSTNAME/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 configuration parameters

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

パラメーター名	タイプ	説明
`name`	`string`	GitHub App の名前。アプリケーションには簡潔で明快な名前を付けましょう。アプリケーションの名前は、既存の GitHub ユーザと同じ名前にできません。ただし、その名前があなた自身のユーザ名や Organization 名である場合は例外です。インテグレーションが動作すると、ユーザインターフェース上にアプリケーション名のスラッグが表示されます。
`description`	`string`	GitHub App の説明。
`url`	`string`	GitHub App のホームページの完全な 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`	GitHub App を公開する場合は `true` に設定し、アプリの所有者のみがアクセスできるようにするには `false` に設定します。
`webhook_active`	`boolean`	Webhook を有効にするには、`true` に設定します。既定では、Webhook は無効になっています。
`webhook_url`	`string`	webhook イベントペイロードを送信する完全な URL。
`events`	`array of strings`	Webhook イベント。一部の Webhook イベントでは、新しい GitHub App を登録するときにイベントを選ぶ前に、リソースに対する `read` または `write` アクセス許可が必要です。詳しくは、「GitHub App Webhook イベント」セクションを参照してください。クエリ文字列では、複数のイベントを選択できます。たとえば、「 `events[]=public&events[]=label` 」のように入力します。
`single_file_name`	`string`	これは、アプリケーションが任意のリポジトリの単一のファイルにアクセスできるようにするための、スコープの狭い権限です。 `single_file` アクセス許可を `read` または `write` に設定すると、このフィールドは GitHub App が管理する単一のファイルへのパスを指定します。複数のファイルを管理する必要がある場合は、下の `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 のイベントとペイロード」を参照してください。

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

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

Webhook と GitHub Apps について詳しくは、「GitHub Apps での Webhook の使用」をご覧ください。