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 上の既存ユーザーと同じ名前をアプリに使うことはできません。 インテグレーションが動作すると、ユーザインターフェース上にアプリケーション名のスラッグが表示されます。
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 に設定します。 このパラメーターは、Enterprise が所有するアプリには適用されません。
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 の使用」をご覧ください。