GitHub Appの権限について
既定では、GitHub Apps にはアクセス許可はありません。 GitHub App を登録する際に、アプリのアクセス許可を選択できます。 選んだアクセス許可によって、アプリが GitHub の API でできることと、アプリがサブスクライブできる Webhook が決まります。 アプリに必要な最小限のアクセス許可を選ぶ必要があります。
既定では、GitHub Apps にはアクセス許可がありませんが、ユーザーの代わりに動作する場合にパブリック リソースを読み取るための暗黙的なアクセス許可はあります。 ユーザーに代わって動作することをユーザーがアプリに認可すると、GitHub App によって、結果のユーザー アクセス トークンが使われて、REST API と GraphQL API にパブリック リソース読み取りの要求が行われます。 ユーザーに代わって動作することの詳細については、「ユーザーに代わって GitHub アプリで認証する」を参照してください。
アプリのアクセス許可は、リポジトリ、organization、Enterprise、、またはアカウントのアクセス許可に分類されます。
- リポジトリのアクセス許可を使うと、アプリは、アプリがインストールされているアカウントによって所有されているリポジトリに関連するリソースにアクセスできます。
- 組織のアクセス許可を使うと、アプリは、組織アカウントにインストールされている場合、インストールされている組織に関連するリソースにアクセスできます。
- Enterprise アクセス許可がアプリに付与されていて、Enterprise アカウントにインストールされている場合、アプリは Enterprise を管理できます。
- アカウントのアクセス許可を使うと、アプリは、ユーザーもアプリを承認している場合、ユーザーに関連するリソースにアクセスできます。 アプリのユーザー認可の詳細については、「ユーザーに代わって GitHub アプリで認証する」を参照してください。
Enterprise アクセス許可は、Enterprise アカウントまたは Enterprise 所有の organization でアプリを作成する場合にのみ使用できます。 Enterprise アクセス許可を持つアプリを Enterprise アカウントにインストールするには、public または internal である必要があります。 インストールできるのは、アプリを所有する Enterprise またはアプリを所有する organization のみですが、インストールできる organization または個人用アカウントについては追加の制限はありません。
ユーザーが自分のユーザー アカウントまたは organization にアプリをインストールすると、アプリが要求したリポジトリと organization のアクセス許可が表示され、付与されます。ユーザーが自分の Enterprise にインストールすると、アプリから要求された Enterprise アクセス許可のみが表示され、付与されます。 また、アプリが個々のユーザーに対して要求できるアカウント アクセス許可の一覧も表示されます。 ユーザーは、自分の代わりに動作するアプリを承認するときに、アプリが要求したアカウントのアクセス許可を確認して許可します。
ユーザー アクセス トークンを使った API 要求が成功するかどうかは、ユーザーのアクセス許可とアプリのアクセス許可に依存します。 たとえば、アプリにリポジトリの内容を書き込むアクセス許可が付与されていても、ユーザーにできることが内容の読み取りだけである場合、ユーザー アクセス トークンではコンテンツの読み取りのみを行うことができます。 インストール アクセス トークンを使った API 要求が成功するかどうかは、アプリのアクセス許可のみに依存します。
GitHub App の登録時にアクセス許可を指定する方法の詳細については、「GitHub App の登録」を参照してください。
一部の Webhook と API のアクセスには、"管理" アクセス許可が必要です。 アプリで "管理" アクセス許可が必要な場合は、アプリのホームページでこの要件を説明することを検討してください。 これは、アプリに高レベルのアクセス許可が必要な理由をユーザーが理解するのに役立ちます。
アクセス許可の変更について
所有または管理するアプリのアクセス許可はいつでも変更できます。
- Enterprise アカウントが所有するアプリのアクセス許可を Enterprise 所有者が変更すると、その変更は Enterprise 内の organization によって自動的に承認されます。
- Enterprise アカウントが所有するアプリのアクセス許可を Enterprise アプリ マネージャーが変更すると、その変更は、アプリ マネージャーが organization 所有者でもある Enterprise 内の organization によって自動的に承認されます。
- 所有者がユーザーまたは organization であるアプリのアクセス許可を変更すると、そのアプリがインストールされている各アカウントの所有者は、新しいアクセス許可を承認するように求められます。 アカウント所有者が新しいアクセス許可を承認しない場合、インストールでは引き続き古いアクセス許可が使われます。
アクセス許可の変更の詳細については、「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 App が各アクセス許可でアクセスできる 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