OAuth AppをGitHub上でセットアップする際には、要求されたスコープが認可フォーム上でユーザに表示されます。
ノート: GitHub Appを構築しているなら、認可リクエストでスコープを提供する必要はありません。 このことに関する詳細については「GitHub Appのユーザの特定と認可」を参照してください、
CLIツールなど、OAuth Appがブラウザにアクセスできない場合、アプリケーションを認可するユーザのスコープを指定する必要はありません。 詳しい情報については「OAuth Appの認可」を参照してください。
どのOAuthスコープを所有しているか、そしてAPIアクションが何を受け付けるかを知るには、ヘッダを確認してください。
$ curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com/users/codertocat -I
HTTP/2 200
X-OAuth-Scopes: repo, user
X-Accepted-OAuth-Scopes: userX-OAuth-Scopesはトークンが認可したスコープをリストします。X-Accepted-OAuth-Scopesは、アクションがチェックするスコープをリストします。
利用できるスコープ
| 名前 | 説明 |
|---|---|
(スコープなし) | パブリックな情報への読み取りのみのアクセスを許可します (ユーザのプロフィール情報、リポジトリの情報、Gist) |
repo | プライベートリポジトリを含め、リポジトリへの完全なアクセスを許可します。 これにはコード、コミットのステータス、リポジトリおよびOrganizationのプロジェクト、招待、コラボレータ、Teamのメンバーシップの追加、デプロイメントのステータス、リポジトリとOrganizationのためのリポジトリwebhookが含まれます。 また、ユーザプロジェクトを管理する機能も許可します。 |
repo:status | Grants read/write access to commit statuses in public and private repositories. このスコープが必要になるのは、コードへのアクセスを許可することなく他のユーザあるいはサービスにプライベートリポジトリのコミットステータスへのアクセスを許可したい場合のみです。 |
repo_deployment | デプロイメントステータス for パブリックおよびプライベートリポジトリへのアクセスを許可します。 このスコープが必要になるのは、コードへのアクセスを許可することなくデプロイメントステータスへのアクセスをユーザまたはサービスに許可する場合のみです。 |
public_repo | アクセスをパブリックリポジトリのみに制限します。 これには、コード、コミットステータス、リポジトリプロジェクト、コラボレータ、パブリックリポジトリ及びOrganizationのデプロイメントステータスへの読み書きアクセスが含まれます。 パブリックリポジトリにStarを付けるためにも必要です。 |
repo:invite | リポジトリでのコラボレーションへの招待の承認／拒否を許可します。 このスコープが必要になるのは、コードへのアクセスを許可することなく他のユーザまたはサービスに招待へのアクセスを許可する場合のみです。 |
security_events | 以下のアクセスを許可します。 code scanning API中のセキュリティイベントへの読み取りおよび書き込みアクセス secret scanning API中のセキュリティイベントへの読み取りおよび書き込みアクセス このスコープが必要になるのは、コードへのアクセスを許可することなく他のユーザまたはサービスにセキュリティイベントへのアクセスを許可したい場合のみです。 |
admin:repo_hook | Grants read, write, ping, and delete access to repository hooks in public or private repositories. The repo and public_repo scopes grant full access to repositories, including repository hooks. アクセスをリポジトリフックのみに限定するには、admin:repo_hookスコープを使ってください。 |
write:repo_hook | Grants read, write, and ping access to hooks in public or private repositories. |
read:repo_hook | Grants read and ping access to hooks in public or private repositories. |
admin:org | OrganizationとそのTeam、プロジェクト、メンバーシップを完全に管理できます。 |
write:org | Organizationのメンバーシップ、Organizationのプロジェクト、Teamのメンバーシップへの読み書きアクセス。 |
read:org | Organizationのメンバーシップ、Organizationのプロジェクト、Teamのメンバーシップへの読み取りのみのアクセス。 |
admin:public_key | 公開鍵を完全に管理できます。 |
write:public_key | 公開鍵の作成、リスト、詳細の表示。 |
read:public_key | 公開鍵のリストと詳細の表示。 |
admin:org_hook | Organizationフックへの読み書き、ping、削除アクセスを許可します。 ノート: OAuthトークンがこれらのアクションを行えるのは、OAuth Appが作成したOrganizationフックに対してのみです。 個人アクセストークンがこれらのアクションを行えるのは、ユーザが作成したOrganizationフックに対してのみです。 |
gist | Gistへの書き込みアクセスを許可します。 |
notifications | 許可するアクセス: ユーザの通知に対する読み取りアクセス スレッドへの既読アクセス リポジトリへのWatch及びWatch解除のアクセス スレッドのサブスクリプションに対する読み書き及び削除アクセス。 |
ユーザ | プロフィール情報にのみ読み書きアクセスを許可します。 このスコープにはuser:emailとuser:followが含まれることに注意してください。 |
read:user | ユーザのプロフィールデータへの読み取りアクセスを許可します。 |
user:email | ユーザのメールアドレスへの読み取りアクセスを許可します。 |
user:follow | 他のユーザのフォローあるいはフォロー解除のアクセスを許可します。 |
delete_repo | 管理可能なリポジトリの削除アクセスを許可します。 |
write:discussion | Teamのディスカッションの読み書きアクセスを許可します。 |
read:discussion | Team ディスカッションの読み取りアクセスを許可します。 |
write:packages | GitHub Packagesでのパッケージのアップロードあるいは公開のアクセスを許可します。 詳しい情報については「パッケージの公開」を参照してください。 |
read:packages | GitHub Packagesからのパッケージのダウンロードあるいはインストールのアクセスを許可します。 詳しい情報については「パッケージのインストール」を参照してください。 |
delete:packages | GitHub Packagesからのパッケージの削除アクセスを許可します。 For more information, see "Deleting and restoring a package." |
admin:gpg_key | GPGキーを完全に管理できます。 |
write:gpg_key | GPGキーの作成、リスト、詳細の表示ができます。 |
read:gpg_key | GPGキーのリストと詳細を表示できます。 |
codespace | Grants the ability to create and manage codespaces. Codespaces can expose a GITHUB_TOKEN which may have a different set of scopes. For more information, see "Security in Codespaces." |
ワークフロー | GitHub Actionsのワークフローファイルの追加と更新機能を許可します。 同じリポジトリ内の他のブランチに同じファイル（パスと内容が同じ）が存在する場合、ワークフローファイルはこのスコープがなくてもコミットできます。 ワークフローファイルは、異なるスコープのセットを持ちうるGITHUB_TOKENを公開できます。 詳しい情報については、「ワークフローでの認証」を参照してください。 |
ノート:OAuth Appは最初のリダイレクトでスコープをリクエストできます。 スコープは、%20を使って、空白で区切って複数指定できます。
https://github.com/login/oauth/authorize?
client_id=...&
scope=user%20repo_deployment
リクエストされたスコープと許可されたスコープ
scope属性は、トークンに添付された、ユーザが許可したスコープをリストします。 通常、これらのスコープはリクエストされたものと同じになります。 しかし、ユーザはスコープを編集でき、実質的にアプリケーションに対して元々リクエストされたよりも少ないアクセスだけを許可できます。 また、ユーザはOAuthフローが完了した後にトークンのスコープを編集することもできます。 この可能性を認識しておき、対応してアプリケーションの動作を調整しなければなりません。
元々リクエストされたよりも少ないアクセスをユーザが許可した場合のエラーケースを処理することは重要です。 たとえば、アプリケーションはユーザに対し、機能が低下したり、行えないアクションがでてくることを警告したり、知らせたりすることができます。
また、アプリケーションはいつでもユーザをフローに戻して追加の権限を得ようとすることができますが、ユーザは常に拒否できることを忘れないようにしてください。
変更できるトークンのスコープの扱いに関するヒントが提供亜sレテイル、認証の基礎ガイドを参照してください。
正規化されたスコープ
複数のスコープがリクエストされた場合、トークンは正規化されたスコープのリストとともに保存され、リクエストされた他のスコープに暗黙のうちに含まれているスコープは破棄されます。 たとえばuser,gist,user:emailをリクエストすると、トークンにはuserとgistスコープだけが含まれます。これは、user:emailスコープで許可されるアクセスはuserスコープに含まれているためです。