GitHub App URL パラメータについて
個人または Organization アカウントで、GitHub App の構成を事前設定する以下の URL をクエリパラメータに追� できます。
- 個人アカウント:
http(s)://HOSTNAME/settings/apps/new
- Organization アカウント:
http(s)://HOSTNAME/organizations/:org/settings/apps/new
アプリケーションを作成するユーザは、アプリケーションをサブミットする前に GitHub App 登録ページから事前設定する値を編集できます。 URL クエリ文字列に name
などの必� �の値が含まれていない� �合は、アプリの作成者が、アプリを送信する前に値を入力する必要があります。
webhook を保護するためにシークレットが必要なアプリケーションの� �合、シークレットの値はクエリパラメータではなく、アプリケーションを作成する人がフォー� に設定する必要があります。 詳細については、「webhook のセキュリティ保護」をご覧く� さい。
次の URL では、事前構成された説明とコールバック URL を使って、octocat-github-app
という新しいパブリック アプリが作成されます。 また、この URL では、checks
に対して読み取りと書き込みのアクセス許可が選ばれ、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&events[]=check_run&events[]=check_suite
使用可能なクエリパラメータ、権限、およびイベントの完全なリストを、以下のセクションに記載します。
GitHub App configuration parameters
名前 | 型 | 説明 |
---|---|---|
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 のようにします。 |
request_oauth_on_install | boolean | アプリが OAuth フローを使ってユーザーを認可する� �合、このオプションを true に設定して、ユーザーがインストール時にアプリを認可して、ステップを省略できるようにすることができます。 このオプションを選ん� � �合、setup_url は利用できなくなり、ユーザーはアプリのインストール後に設定された callback_url にリダイレクトされます。 |
setup_url | string | GitHub App アプリケーションをインストール後に追� セットアップが必要な� �合に、リダイレクトする完全な URL。 |
setup_on_update | boolean | true に設定すると、たとえばリポジトリが追� や削除された後など、ユーザーはインストールが更新されたときのセットアップ URL にリダイレクトします。 |
public | boolean | GitHub App を公開する� �合は true に設定し、アプリの所有者のみがアクセスできるようにするには false に設定します。 |
webhook_active | boolean | Webhook を無効にするには、false に設定します。 Webhook は既定で有効になっています。 |
webhook_url | string | webhook イベントペイロードを送信する完全な URL。 |
events | array of strings | Webhook イベント。 一部の Webhook イベントでは、新しい GitHub App を登録するときにイベントを選ぶ前に、リソースに対する read または write アクセス許可が必要です。 利用可能なイベントと、それに必要なアクセス許可については、「GitHub App webhook イベント」セクションをご覧く� さい。 クエリ文字列では、複数のイベントを選択できます。 たとえば、events[]=public&events[]=label です。 |
domain | string | コンテンツ参照の URL。 |
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 の権限
以下の表にある権限名をクエリパラメータ名として、権限タイプをクエリの値として使用することで、クエリ文字列で権限を設定できます。 たとえば、contents
のユーザー インターフェイスで Read & write
アクセス許可を選ぶには、クエリ文字列に &contents=write
を含めます。 blocking
のユーザー インターフェイスで Read-only
アクセス許可を選ぶには、クエリ文字列に &blocking=read
を含めます。 checks
のユーザー インターフェイスで no-access
を選ぶには、クエリ文字列に checks
アクセス許可を含めないようにします。
権限 | 説明 |
---|---|
administration | Organization およびリポジトリ管理のためのさまざまなエンドポイントにアクセス権を付与します。 none 、read 、write のいずれかにすることができます。 |
checks | Checks API へのアクセスを許可します。 none 、read 、write のいずれかにすることができます。 |
content_references | "コンテンツ添付の作成" エンドポイントへのアクセスを許可します。 none 、read 、write のいずれかにすることができます。 |
contents | さまざまなエンドポイントにアクセス権を付与し、リポジトリのコンテンツを変更できるようにします。 none 、read 、または write のいずれかにすることができます。 |
deployments | Deployments API へのアクセスを許可します。 none 、read 、write のいずれかにすることができます。 |
emails | Emails API へのアクセスを許可します。 none 、read 、write のいずれかにすることができます。 |
followers | Followers API へのアクセスを許可します。 none 、read 、または write のいずれかにすることができます。 |
gpg_keys | GPG Keys API へのアクセスを許可します。 none 、read 、または write のいずれかにすることができます。 |
issues | IssuesKeys API へのアクセスを許可します。 none 、read 、または write のいずれかにすることができます。 |
keys | Public Keys API へのアクセスを許可します。 none 、read 、または write のいずれかにすることができます。 |
members | Organization のメンバーへのアクセス権を付与します。 none 、read 、write のいずれかにすることができます。 |
organization_hooks | Organization Webhooks API へのアクセスを許可します。 none 、read 、または write のいずれかにすることができます。 |
organization_plan | "Organization の取得" エンドポイントを使って Organization の計画に関する情� �を取得するためのアクセスを許可します。 none または read のいずれかにすることができます。 |
organization_projects | Projects API へのアクセスを許可します。 none 、read 、write 、admin のいずれかにすることができます。 |
pages | Pages API へのアクセスを許可します。 none 、read 、または write のいずれかにすることができます。 |
plan | "ユーザーの取得" エンドポイントを使ってユーザーの GitHub プランに関する情� �を取得するためのアクセスを許可します。 none または read のいずれかにすることができます。 |
pull_requests | さまざまなプルリクエストエンドポイントへのアクセス権を付与します。 none 、read 、または write のいずれかにすることができます。 |
repository_hooks | Repository Webhooks API へのアクセスを許可します。 none 、read 、または write のいずれかにすることができます。 |
repository_projects | Projects API へのアクセスを許可します。 none 、read 、write 、admin のいずれかにすることができます。 |
secret_scanning_alerts | Secret scanning API へのアクセスを許可します。 none 、read 、write のいずれかにすることができます。 |
security_events | Code scanning API へのアクセスを許可します。 none 、read 、write のいずれかにすることができます。 |
single_file | Contents API へのアクセスを許可します。 none 、read 、または write のいずれかにすることができます。 |
starring | Starring API へのアクセスを許可します。 none 、read 、または write のいずれかにすることができます。 |
statuses | Statuses API へのアクセスを許可します。 none 、read 、または write のいずれかにすることができます。 |
team_discussions | Team Discussions API と Team Discussion Comments API へのアクセスを許可します。 none 、read 、または write のいずれかにすることができます。 |
vulnerability_alerts | リポジトリ内の Dependabot alerts を受信するアクセス権を付与します。 詳しくは、「Dependabot alerts について」をご覧く� さい。 none または read のいずれかにすることができます。 |
watching | リストへのアクセス権を付与し、ユーザがサブスクライブするリポジトリの変更を許可します。 none 、read 、または write のいずれかにすることができます。 |
GitHub App webhook イベント
Webhook イベント名 | 必要な権限 | 説明 |
---|---|---|
check_run | checks | チェックランのアクティビティが発生しました。 アクティビティの種類は、ペイロード オブジェクトの action プロパティで指定されます。 詳細については、"チェック ラン" REST API を参照してく� さい。 |
check_suite | checks | チェックスイートのアクティビティが発生しました。 アクティビティの種類は、ペイロード オブジェクトの action プロパティで指定されます。詳細については、「チェック スイート」 REST API を参照してく� さい。 |
commit_comment | contents | コミットコメントが作成されました。 アクティビティの種類は、ペイロード オブジェクトの action プロパティで指定されます。 詳細については、「コミットのコメント」 REST API を参照してく� さい。 |
content_reference | content_references | 新しいコンテンツ参照は created です。 新しいコンテンツ参照は、IssueもしくはPull Requestのボディあるいはコメントが、設定されたコンテンツ参照ドメインにマッチする� �合に作成されます。 コンテンツ参照と添付ファイルの詳細については、「コンテンツの添付ファイルの使用」を参照してく� さい。 |
create | contents | Gitブランチもしくはタグが作成されました。 詳細については、「Git データベース」 REST API を参照してく� さい。 |
delete | contents | Gitブランチまたはタグが削除されました。 詳細については、「Git データベース」 REST API を参照してく� さい。 |
deployment | deployments | デプロイメントが作成されました。 アクティビティの種類は、ペイロード オブジェクトの action プロパティで指定されます。詳細については、"deployment" の REST API を参照してく� さい。 |
deployment_status | deployments | デプロイメントが作成されました。 アクティビティの種類は、ペイロード オブジェクトの action プロパティで指定されます。 詳細については、"deployments" の REST API を参照してく� さい。 |
fork | contents | ユーザがリポジトリをフォークします。 詳しい情� �については、「フォーク」 REST API を参照してく� さい。 |
gollum | contents | wikiページが作成もしくは更新されました。 詳細については、「ウィキについて」を参照してく� さい。 |
issues | issues | Issueに関連するアクティビティ。 アクティビティの種類は、ペイロード オブジェクトの action プロパティで指定されます。 詳細については、REST API の「Issue」を参照してく� さい。 |
issue_comment | issues | IssueあるいはPull Requestコメントに関連するアクティビティ。 アクティビティの種類は、ペイロード オブジェクトの action プロパティで指定されます。詳細については、「issue comments」の REST API を参照してく� さい。 |
label | metadata | ラベルに関連するアクティビティ。 アクティビティの種類は、ペイロード オブジェクトの action プロパティで指定されます。 詳細については、"labels" の REST API を参照してく� さい。 |
member | members | リポジトリのコラボレータに関連するアクティビティ。 アクティビティの種類は、ペイロード オブジェクトの action プロパティで指定されます。 詳細については、"collaborators" の REST API を参照してく� さい。 |
membership | members | Teamのメンバーシップに関連するアクティビティ。 アクティビティの種類は、ペイロード オブジェクトの action プロパティで指定されます。 詳細については、"team members" の REST API を参照してく� さい。 |
milestone | pull_request | マイルストーンに関連するアクティビティ。 アクティビティの種類は、ペイロード オブジェクトの action プロパティで指定されます。 詳細については、"milestones" の REST API を参照してく� さい。 |
organization | members | Organization及びそのメンバーと関連するアクティビティ。 アクティビティの種類は、ペイロード オブジェクトの action プロパティで指定されます。 詳細については、"organizations" の REST API を参照してく� さい。 |
page_build | pages | 成功か否かにかかわらず、GitHub Pagesサイトの試行されたビルドを表します。 このイベントは、GitHub Pages が有効化されたブランチ (プロジェクトのページなら gh-pages 、ユーザーおよび組織のページなら既定のブランチ) へのプッシュでトリガーされます。 |
project | repository_projects または organization_projects | プロジェクト ボード に関連するアクティビティ。 アクティビティの種類は、ペイロード オブジェクトの action プロパティで指定されます。 詳細については、「プロジェクト」 REST API を参照してく� さい。 |
project_card | repository_projects または organization_projects | プロジェクト ボード のカードに関連するアクティビティ。 アクティビティの種類は、ペイロード オブジェクトの action プロパティで指定されます。 詳細については、"project cards" の REST API を参照してく� さい。 |
project_column | repository_projects または organization_projects | プロジェクト ボード の列に関連するアクティビティ。 アクティビティの種類は、ペイロード オブジェクトの action プロパティで指定されます。 詳細については、「プロジェクト列」 REST API を参照してく� さい。 |
public | metadata | プライベートリポジトリがパブリックにされたとき。 間違いなく: 最高のGitHub Enterprise Serverイベント。 |
pull_request | pull_requests | Pull Requestに関連するアクティビティ。 アクティビティの種類は、ペイロード オブジェクトの action プロパティで指定されます。 詳細については、「pull request」 REST API を参照してく� さい。 |
pull_request_review | pull_request | Pull Requestレビューに関連するアクティビティ。 アクティビティの種類は、ペイロード オブジェクトの action プロパティで指定されます。詳細については、「pull request のレビュー」の REST API を参照してく� さい。 |
pull_request_review_comment | pull_request | Pull Requestの統合diff中のPull Requestレビューコメントに関連するアクティビティ。 アクティビティの種類は、ペイロード オブジェクトの action プロパティで指定されます。詳細については、「プルリクエストのレビュー コメント」の REST API を参照してく� さい。 |
pull_request_review_thread | pull_request | 解決済みまたは未解決とマークされている pull request のコメント スレッドに関連するアクティビティ アクティビティの種類は、ペイロード オブジェクトの action プロパティで指定されます。 |
push | contents | リポジトリのブランチもしくはタグに、1つ以上のコミットがプッシュされました。 |
release | contents | リリースに関連するアクティビティ。 アクティビティの種類は、ペイロード オブジェクトの action プロパティで指定されます。 詳細については、"リリース" REST API を参照してく� さい。 |
repository | metadata | リポジトリに関連するアクティビティ。 アクティビティの種類は、ペイロード オブジェクトの action プロパティで指定されます。 詳細については、「リポジトリ」 REST API を参照してく� さい。 |
status | statuses | Gitコミットのステータスが変化したとき。 詳しくは、「statuses」の REST API に関するページをご覧く� さい。 |
team | members | OrganizationのTeamに関連するアクティビティ。 アクティビティの種類は、ペイロード オブジェクトの action プロパティで指定されます。 詳細については、"teams" の REST API を参照してく� さい。 |
team_add | members | リポジトリがチー� に追� されたとき。 |
watch | metadata | 誰かがリポジトリにStarを付けたとき。 アクティビティの種類は、ペイロード オブジェクトの action プロパティで指定されます。詳細については、REST API の「starring」を参照してく� さい。 |