OAuth AppをGitHub上でセットアップする際には、要求されたスコープが認可フォーム上でユーザに表示されます。
ノート: GitHub Appを構築しているなら、認可リクエストでスコープを提供する必要はありません。 このことに関する詳細については「GitHub Appのユーザの特定と認可」を参照してください、
If your OAuth App doesn't have access to a browser, such as a CLI tool, then you don't need to specify a scope for users to authenticate to your 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は、アクションがチェックするスコープをリストします。
利用できるスコープ
| 名前 | 説明 |
|---|---|
(スコープなし) | Grants read-only access to public information (including user profile info, repository info, and gists) |
repo | Grants full access to repositories, including private repositories. That includes read/write access to code, commit statuses, repository and organization projects, invitations, collaborators, adding team memberships, deployment statuses, and repository webhooks for repositories and organizations. また、ユーザプロジェクトを管理する機能も許可します。 |
repo:status | Grants read/write access to public and private repository commit statuses. このスコープが必要になるのは、コードへのアクセスを許可することなく他のユーザあるいはサービスにプライベートリポジトリのコミットステータスへのアクセスを許可したい場合のみです。 |
repo_deployment | Grants access to deployment statuses for public and private repositories. This scope is only necessary to grant other users or services access to deployment statuses, without granting access to the code. |
public_repo | アクセスをパブリックリポジトリのみに制限します。 これには、コード、コミットステータス、リポジトリプロジェクト、コラボレータ、パブリックリポジトリ及びOrganizationのデプロイメントステータスへの読み書きアクセスが含まれます。 Also required for starring public repositories. |
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 and 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 | Allows read access for team discussions. |
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キーのリストと詳細の表示ができます。 |
ワークフロー | GitHub Actionsのワークフローファイルの追加と更新機能を許可します。 同じリポジトリ内の他のブランチに同じファイル（パスと内容が同じ）が存在する場合、ワークフローファイルはこのスコープがなくてもコミットできます。 Workflow files can expose GITHUB_TOKEN which may have a different set of scopes. For more information, see "Authentication in a workflow." |
ノート:OAuth Appは最初のリダイレクトでスコープをリクエストできます。 You can specify multiple scopes by separating them with a space using %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スコープに含まれているためです。