# URL パラメーターを使用したGitHub アプリの登録 URL クエリ パラメーターを使用すると、事前に選択した特定の構成を使用して、他のユーザーが新しい GitHub App をすばやく設定するのに役立ちます。 ## 登録用の URL パラメーターについて GitHub Apps URL パラメーターを使用して、新しい GitHub App 登録の構成設定を事前に選択し、カスタム リンクを他のユーザーと共有できます。 このリンクにより、ユーザーは GitHub App 登録ページに移動します。このページでは、URL に含めた URL パラメーターに従ってアプリの設定が事前に入力されます。 このアプローチは、特定の仕様を使用して個人のアカウントまたは組織にアプリを設定したいインテグレーターや、GitHub Enterprise ServerからアプリをインストールできないGitHub Marketplaceを使用しているお客様に役立ちます。 または、 GitHub App マニフェストを作成することもできます。 詳しくは、「[マニフェストからのGitHub アプリの登録](/ja/enterprise-server@3.22/apps/sharing-github-apps/registering-a-github-app-from-a-manifest)」をご覧ください。 ## クエリ パラメーターを使用したカスタム構成 URL の作成 個人または組織のアカウントで GitHub App のカスタム構成 URL を作成するには、次の基本 URL の後にクエリ パラメーターを追加します。 * 個人用アカウントでアプリを登録する場合は、`http(s)://HOSTNAME/settings/apps/new` に URL パラメーターを追加します * 組織アカウントでアプリを登録する場合は、`http(s)://HOSTNAME/organizations/ORGANIZATION/settings/apps/new` に URL パラメーターを追加します。 `ORGANIZATION` は、顧客にアプリを登録してもらいたい組織の名前に置き換えてください。 * Enterprise アカウントでアプリを登録する場合は、`http(s)://HOSTNAME/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) を要求するオプションが選ばれます。 ```text 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 構成パラメーター 次のクエリ パラメーターを使用して、 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 について](/ja/enterprise-server@3.22/apps/creating-github-apps/registering-a-github-app/about-the-user-authorization-callback-url)」をご覧ください。 | | `request_oauth_on_install` | `boolean` | アプリが OAuth フローを使ってユーザーを認可する場合、このオプションを `true` に設定して、ユーザーがインストール時にアプリを認可して、ステップを省略できるようにすることができます。 このオプションを選んだ場合、`setup_url` は利用できなくなり、ユーザーはアプリのインストール後に設定された `callback_url` にリダイレクトされます。 | | `setup_url` | `string` | アプリがインストール後に追加のセットアップを必要とする場合に、他のユーザーが GitHub App をインストールした後にリダイレクトする完全な URL。 詳しくは、「[セットアップ URL について](/ja/enterprise-server@3.22/apps/creating-github-apps/registering-a-github-app/about-the-setup-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 イベントでは、新しい`read`を登録する際にイベントを選択する前に、リソースに対する`write`またはGitHub Appのアクセス許可が必要です。 詳細については、「[webhook イベントのGitHub App](#github-app-webhook-events)」セクションを参照してください。 クエリ文字列では、複数のイベントを選択できます。 たとえば、「 `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 アプリのアクセス許可の選択](/ja/enterprise-server@3.22/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app)」を参照してください。 使用できるアクセス許可とパラメーター化された名前の一覧については、「[個人用アクセス トークンを管理する](/ja/enterprise-server@3.22/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#account-permissions)」を参照してください。 ## 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 のイベントとペイロード](/ja/enterprise-server@3.22/webhooks/webhook-events-and-payloads) を参照してください。 たとえば、コミット コメントに関連するアクティビティの webhook ペイロードを受信する GitHub App をサブスクライブするには、クエリ文字列に `&webhook_active=true&webhook_url=https://example.com&events[]=commit_comment`が含まれます。 `commit_comment` webhook イベントでは、GitHub Appが "Contents" リポジトリのアクセス許可に対して少なくとも読み取りレベルのアクセス権を持っている必要があることに注意してください。 そのため、クエリ文字列には、`contents` アクセス許可を `read` または `write` に設定するためのパラメーターも含める必要があります。 詳細については、「 [GitHub アプリのアクセス許可](#github-app-permissions)」を参照してください。 クエリ パラメーターを使用して Webhook シークレットの値を設定することはできません。 アプリで Webhook をセキュリティで保護するためにシークレットが必要な場合は、アプリを登録するユーザーが GitHub UI でシークレットの値を設定する必要があります。 webhook と GitHub Appsの詳細については、 [AUTOTITLE を](/ja/enterprise-server@3.22/apps/creating-github-apps/registering-a-github-app/using-webhooks-with-github-apps)参照してください。