GitHub Apps
を登録するための URL パラメーターについて
URL パラメーターを使うと、新しい GitHub App 登録の構成設定を事前に選択し、カスタム リンクを他のユーザーと共有できます。 このリンクを使うと、ユーザーは GitHub App の登録ページに移動します。そこでは、URL に含めた URL パラメーターに従ってアプリ設定が事前入力されています。
このアプローチを有効に利用できるのは、顧客に特定の仕様で個人用アカウントまたは organization にアプリを設定してもらいたいインテグレーター、または GitHub Marketplace からアプリをインストールできない GitHub Enterprise Server を使用している顧客となります。
あるいは、GitHub App マニフェストを作成することもできます。 詳しくは、「マニフェストから GitHub App を登録する」を参照してください。
Note
この記事には、github.com
ドメインを使うコマンドまたは例が含まれています。 octocorp.ghe.com
など、別のドメインで GitHub にアクセスすることもできます。
クエリ パラメーターを使用したカスタム構成 URL の作成
個人用または Organization アカウント上で GitHub App 用のカスタム構成 URL を作成するには、次のベース URL の後にクエリ パラメーターを追加します。
-
個人用アカウントでアプリを登録する場合は、
https://github.com/settings/apps/new
に URL パラメーターを追加します -
組織アカウントでアプリを登録する場合は、
https://github.com/organizations/ORGANIZATION/settings/apps/new
に URL パラメーターを追加します。ORGANIZATION
は、顧客にアプリを登録してもらいたい組織の名前に置き換えてください。Note
GitHub App を登録するための URL パラメーターは、Enterprise が所有するアプリでも使用できます。 Enterprise 所有のアプリは、その Enterprise 内の組織にのみインストールできるため、組織のカスタム構成 URL を使用できます。
アプリ登録ページ上で、アプリを登録するユーザーは、事前選択されている値を編集してから、アプリを送信することができます。 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 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 の使用」をご覧ください。