Note
OAuth app ではなく GitHub App を構築することを検討してください。 GitHub Apps では、スコープではなくきめ細かいアクセス許可が使われるため、アプリで実行できる操作をより細かく制御できます。 詳細については、「GitHub Apps と OAuth アプリの違い」および「GitHub App の作成について」を参照してください。
OAuth app を GitHub 上でセットアップする際には、要求されたスコープが認可フォーム上でユーザに表示されます。
Note
GitHub App を構築している場合は、認可要求でスコープを指定する必要はありません。 この詳細については、「ユーザーに代わって GitHub アプリで認証する」を参照してください。
CLIツールなど、OAuth appがブラウザにアクセスできない場合、アプリケーションを認可するユーザのスコープを指定する必要はありません。 詳しくは、「OAuth アプリの承認」をご覧ください。
どのOAuthスコープを所有しているか、そしてAPIアクションが何を受け付けるかを知るには、ヘッダを確認してください。
$ curl -H "Authorization: Bearer OAUTH-TOKEN" https://api.github.com/users/codertocat -I
HTTP/2 200
X-OAuth-Scopes: repo, user
X-Accepted-OAuth-Scopes: user
X-OAuth-Scopesには、トークンが認可したスコープが一覧表示されます。X-Accepted-OAuth-Scopesには、アクションがチェックするスコープが一覧表示されます。
利用可能なスコープ
| 名前 | 説明 |
|---|---|
(no scope) | パブリック情報 (ユーザー プロファイル情報、リポジトリ情報、gists を含む) への読み取り専用アクセスを許可します |
repo | パブリックおよびプライベート リポジトリ (コードへの読み取りと書き込みアクセス、コミット ステータス、リポジトリの招待、コラボレーター、デプロイ ステータス、リポジトリ Webhook など) へのフル アクセスを許可します。 注: repo スコープでは、リポジトリ関連のリソースに加えて、Organization 所有のリソース (プロジェクト、招待、Team メンバーシップ、Webhook) を管理するためのアクセスも許可されます。 さらに、ユーザー所有のプロジェクトを管理する権限も許可されます。 |
repo:status | パブリックおよびプライベートリポジトリのコミット ステータスへの読み取り/書き込みアクセスを許可します。 このスコープは、コードへのアクセスを許可 せずに、他のユーザーまたはサービスにプライベート リポジトリコミットステータスへのアクセス権を付与する場合にのみ必要です。 |
repo_deployment | パブリック リポジトリとプライベート リポジトリのデプロイ ステータスへのアクセスを許可します。 このスコープは、コードへのアクセスを許可_せずに_、他のユーザーまたはサービスにデプロイ ステータスへのアクセスを許可する場合にのみ必要です。 |
public_repo | パブリック リポジトリへのアクセスを制限します。 これには、コード、コミットステータス、リポジトリプロジェクト、コラボレータ、パブリックリポジトリ及びOrganizationのデプロイメントステータスへの読み書きアクセスが含まれます。 パブリック リポジトリの星付けにも必要です。 |
repo:invite | リポジトリで共同作業を行うための招待に対する承諾/拒否機能を許可します。 このスコープは、コードへのアクセスを許可_せずに_、他のユーザーまたはサービスに招待へのアクセスを許可する場合にのみ必要です。 |
security_events | 以下を許可します: code scanning API でのセキュリティ イベントに対する読み取りおよび書き込みアクセス このスコープは、コードへのアクセスを許可_せずに_、他のユーザーまたはサービスにセキュリティ イベントへのアクセスを許可する場合にのみ必要です。 |
admin:repo_hook | パブリックまたはプライベートリポジトリのリポジトリ フックへの読み取り、書き込み、ping、削除アクセスを許可します。 repo および public_repo スコープは、リポジトリ フックを含むリポジトリに対するフル アクセスを許可します。 アクセスをリポジトリ フックのみに限定するには、admin:repo_hook スコープを使用してください。 |
write:repo_hook | パブリックまたはプライベート リポジトリのフックへの読み取り、書き込み、ping アクセスを許可します。 |
read:repo_hook | パブリックまたはプライベート リポジトリのフックへの読み取りおよび ping アクセスを許可します。 |
admin:org | 組織とそのチーム、プロジェクト、メンバーシップを全面的に管理できます。 |
write:org | organization のメンバーシップおよび organization のプロジェクトへの読み取りおよび書き込みアクセス権限。 |
read:org | 組織のメンバーシップ、組織のプロジェクト、チームのメンバーシップへの読み取り専用アクセス。 |
admin:public_key | 公開鍵を全面的に管理できます。 |
write:public_key | 公開鍵の作成、一覧表示、詳細の表示ができます。 |
read:public_key | 公開鍵の一覧表示と詳細の表示ができます。 |
admin:org_hook | 組織フックへの読み取り、書き込み、ping、削除アクセスを許可します。 注: OAuth トークンがこれらのアクションを実行できるのは、OAuth app によって作成された Organization フックに対してのみです。 Personal access token がこれらのアクションを実行できるのは、ユーザーが作成した組織のフックに対してのみです。 |
gist | gist への書き込みアクセスを許可します。 |
notifications | 以下を許可します: "ユーザーの通知に対する読み取りアクセス" スレッドに対する既読としてマーク アクセス "リポジトリに対するウォッチおよびウォッチ解除アクセス" スレッドのサブスクリプションに対する読み取り、書き込み、削除アクセス。 |
user | プロファイル情報のみへの読み取り/書き込みアクセスを許可します。 このスコープには user:email と user:follow が含まれることにご注意ください。 |
read:user | ユーザーのプロファイル データへの読み取りアクセスを許可します。 |
user:email | ユーザーのメール アドレスへの読み取りアクセスを許可します。 |
user:follow | 他のユーザーをフォローまたはフォロー解除するためのアクセスを許可します。 |
project | ユーザーおよび組織の projects への読み取り/書き込みアクセスを許可します。 |
read:project | ユーザーおよび組織の projects への読み取り専用アクセスを許可します。 |
delete_repo | 管理可能なリポジトリを削除するためのアクセスを許可します。 |
write:packages | GitHub Packages でパッケージをアップロードまたは公開するためのアクセスを許可します。 詳しくは、「パッケージの公開」をご覧ください。 |
read:packages | GitHub Packages からパッケージをダウンロードまたはインストールするためのアクセスを許可します。 詳しくは、「パッケージのインストール」をご覧ください。 |
delete:packages | GitHub Packages からパッケージを削除するためのアクセスを許可します。 詳しくは、「パッケージを削除および復元する」をご覧ください。 |
admin:gpg_key | GPG キーを完全に管理できます。 |
write:gpg_key | GPG キーの作成、一覧表示、詳細の表示ができます。 |
read:gpg_key | GPG キーの一覧表示および詳細の表示ができます。 |
codespace | コードスペースを作成および管理する機能を許可します。 codespace は、スコープのセットが異なる可能性がある GITHUB_TOKEN を公開する場合があります。 詳細については、「GitHub Codespaces のセキュリティ」を参照してください。 |
workflow | GitHub Actions のワークフロー ファイルの追加および更新する機能を許可します。 同じリポジトリ内の他のブランチに同じファイル（パスと内容が同じ）が存在する場合、ワークフローファイルはこのスコープがなくてもコミットできます。 ワークフロー ファイルは、スコープのセットが異なる可能性がある GITHUB_TOKEN を公開する場合があります。 詳細については、「自動トークン認証」を参照してください。 |
Note
OAuth app は最初のリダイレクトでスコープを要求できます。 複数のスコープを指定するには、スコープを空白で区切ります (%20 を使用)。
https://github.com/login/oauth/authorize?
client_id=...&
scope=user%20repo_deployment
リクエストされたスコープと許可されたスコープ
scope 属性は、トークンに付随する、ユーザーによって許可されたスコープを一覧表示します。 通常、これらのスコープはリクエストされたものと同じになります。
しかし、ユーザーはスコープを編集して、実質的には元々要求されたアクセスよりも少ないアクセスをアプリケーションに対して許可できます。 また、ユーザーは OAuth フローが完了した後にトークンのスコープを編集することもできます。
この可能性を認識しておき、それに応じたアプリケーションの動作の調整が必要になります。
元々要求されたアクセスよりも少ないアクセスをユーザーが許可した場合のエラー ケースを処理することが重要です。 たとえば、アプリケーションはユーザーに対して、機能の低下や一部のアクションが実行できないことを警告したり、知らせたりすることができます。
また、アプリケーションはいつでもユーザーをもう一度フローに戻して追加の権限を得ようとすることができますが、ユーザーは常に拒否できることを忘れないようにしてください。
変更できるトークンのスコープの扱いに関するヒントが提供されている認証の基本ガイドをご確認ください。
正規化されたスコープ
複数のスコープが要求された場合、トークンは正規化されたスコープのリストとともに保存され、要求された別のスコープに暗黙的に含まれているスコープは破棄されます。 たとえば user,gist,user:email を要求すると、トークンには user と gist スコープのみが含まれます。これは、user:email スコープで許可されるアクセスは user スコープに含まれているからです。