Skip to main content

GitHub アプリのアクセス許可を選択する

GitHub アプリのアクセス許可によって、アプリが GitHub の API でできることと、アプリが受け取ることのできる Webhook が決まります。

GitHub Appの権限について

既定では、GitHub Apps にはアクセス許可はありません。 GitHub App を登録する際に、アプリのアクセス許可を選択できます。 選んだアクセス許可によって、アプリが GitHub の API でできることと、アプリがサブスクライブできる Webhook が決まります。 アプリに必要な最小限のアクセス許可を選ぶ必要があります。

既定では、GitHub Apps にはアクセス許可がありませんが、ユーザーの代わりに動作する場合にパブリック リソースを読み取るための暗黙的なアクセス許可はあります。 ユーザーに代わって動作することをユーザーがアプリに承認すると、GitHub App によって、結果のユーザー アクセス トークンが使われて、REST API と GraphQL API にパブリック リソース読み取りの要求が行われます。 ユーザーに代わって動作することについて詳しくは、「ユーザーに代わって GitHub アプリで認証する」をご覧ください。

アプリのアクセス許可は、リポジトリ、組織、またはアカウントのアクセス許可として分類されます。 リポジトリのアクセス許可を使うと、アプリは、アプリがインストールされているアカウントによって所有されているリポジトリに関連するリソースにアクセスできます。 組織のアクセス許可を使うと、アプリは、組織アカウントにインストールされている場合、インストールされている組織に関連するリソースにアクセスできます。 アカウントのアクセス許可を使うと、アプリは、ユーザーもアプリを承認している場合、ユーザーに関連するリソースにアクセスできます。 アプリのユーザー承認について詳しくは、「ユーザーに代わって GitHub アプリで認証する」をご覧ください。

ユーザーは、自分のアカウントまたは組織にアプリをインストールするときに、アプリが要求したリポジトリと組織のアクセス許可を確認して許可します。 アプリが個々のユーザーに対して要求できるアカウント アクセス許可の一覧も表示されます。 ユーザーは、自分の代わりに動作するアプリを承認するときに、アプリが要求したアカウントのアクセス許可を確認して許可します。

ユーザー アクセス トークンを使った API 要求が成功するかどうかは、ユーザーのアクセス許可とアプリのアクセス許可に依存します。 たとえば、アプリにリポジトリの内容を書き込むアクセス許可が付与されていても、ユーザーにできることが内容の読み取りだけである場合、ユーザー アクセス トークンではコンテンツの読み取りのみを行うことができます。 インストール アクセス トークンを使った API 要求が成功するかどうかは、アプリのアクセス許可のみに依存します。

アプリのアクセス許可はいつでも変更できます。 アクセス許可を変更すると、アプリがインストールされた各アカウントの所有者が、新しいアクセス許可の承認を求められます。 アカウント所有者が新しいアクセス許可を承認しない場合、インストールでは引き続き古いアクセス許可が使われます。

一部の Webhook と API のアクセスには、"管理" アクセス許可が必要です。 アプリで "管理" アクセス許可が必要な場合は、アプリのホームページでこの要件を説明することを検討してください。 これは、アプリに高レベルのアクセス許可が必要な理由をユーザーが理解するのに役立ちます。

GitHub App の登録時にアクセス許可を指定する方法について詳しくは、「GitHub App の登録」を参照してください。 アクセス許可の変更について詳しくは、「GitHub App 登録の変更」をご覧ください。

Webhook にアクセスするためのアクセス許可を選択する

Webhook のドキュメントでは、各 Webhook が GitHub Apps に使用できるかどうかが示されています。 サブスクライブする Webhook ごとに、Webhook のドキュメントを参照して、その Webhook をサブスクライブするために GitHub App で必要なアクセス許可を確認してください。 詳しくは、「Webhook のイベントとペイロード」を参照してください。

たとえば、アプリで team イベントをサブスクライブする場合、アプリには "メンバー" 組織アクセス許可が必要です。

GitHub App の登録ページで利用できる Webhook イベントは、アプリのアクセス許可を変更すると変更されます。 GitHub App でイベントをサブスクライブするのに十分なアクセス許可を選ばなかった場合、そのイベントはアプリ登録ページのオプションとして表示されません。

REST API にアクセスするためのアクセス許可を選択する

各エンドポイントの REST API リファレンス ドキュメントでは、エンドポイントが GitHub Apps で動作するかどうかを示し、アプリがエンドポイントを使用するために必要なアクセス許可を示しています。 一部のエンドポイントでは複数のアクセス許可が必要な場合があり、一部のエンドポイントでは複数のアクセス許可のうちの 1 つが必要な場合があります。 GitHub Apps が各アクセス許可でアクセスできる REST API エンドポイントの概要については、「GitHub Appに必要な権限」を参照してください。

たとえば、GET /orgs/{org}/dependabot/secrets エンドポイントを使うには、アプリに "組織 dependabot シークレット" アクセス許可に対する読み取りレベル以上のアクセス許可が必要です。

アプリが不十分なアクセス許可で REST API 要求を行った場合、API は 403 応答を返します。

REST API 応答で 受け取る X-Accepted-GitHub-Permissions ヘッダーで、適切なアクセス許可を選択するための情報が得られます。 このヘッダーは、エンドポイントにアクセスするために必要なアクセス許可を示します。 詳しくは、「REST API のトラブルシューティング」を参照してください。

GraphQL API にアクセスするためのアクセス許可を選択する

GraphQL 要求の場合は、アプリをテストして、実行したい GraphQL クエリと変更に必要なアクセス許可があることを確認する必要があります。

アプリが不十分なアクセス許可で GraphQL API のクエリまたはミューテーションを行った場合、API は 401 応答を返します。

Git にアクセスするためのアクセス許可を選択する

アプリでインストール トークンやユーザー アクセス トークンを使って HTTP ベースの Git アクセスを認証する場合は、"Contents" リポジトリのアクセス許可を要求する必要があります。 アプリで .github/workflows ディレクトリにある Actions ファイルへのアクセスまたは編集が特に必要になっている場合は、"Workflows" リポジトリのアクセス許可を要求します。

その後は、アクセス トークンを HTTP パスワードとして使うことができます。 TOKEN は、アクセス トークンに置き換えます。

git clone https://x-access-token:TOKEN@github.com/owner/repo.git