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