- Notifications
You must be signed in to change notification settings - Fork3.1k
feat: Add fine-grained permissions support and tool permissions docs (Phase 2)#1486
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Open
SamMorrowDrums wants to merge1 commit intoSamMorrowDrums/oauth-scopesChoose a base branch
base:SamMorrowDrums/oauth-scopes
Could not load branches
Branch not found:{{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline, and old review comments may become outdated.
Open
+636 −1
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
Phase 2 of OAuth scopes work:- Extend pkg/scopes package with fine-grained permission types: - Permission type with constants (actions, contents, issues, etc.) - PermissionLevel type (read, write, admin) - FineGrainedPermission struct and helper functions - WithScopesAndPermissions(), AddPermissions(), GetPermissionsFromMeta() - ReadPerm(), WritePerm(), AdminPerm() convenience functions- Create comprehensive docs/tool-permissions.md: - OAuth scope hierarchy reference - Fine-grained permission levels explanation - Tool-by-category permission tables for all ~90 tools - Minimum required scopes by use case - Notes about limitations and special cases- Update README.md with links to permissions docs: - Link in Prerequisites section for PAT creation - Callout note before Tools section- Add tests for all new fine-grained permission functionality
Contributor
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Pull request overview
This PR adds comprehensive support for fine-grained personal access token permissions alongside existing OAuth scope support, and provides detailed documentation to help users understand authentication requirements for each tool.
Key Changes:
- Extended the scopes package with fine-grained permission types, levels, and utility functions
- Created comprehensive tool permissions documentation mapping 100+ tools to their required OAuth scopes and fine-grained permissions
- Updated README to link to the new permissions documentation
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
pkg/scopes/scopes.go | Added fine-grained permission types (Permission,PermissionLevel,FineGrainedPermission) with 20+ permission constants, and 7 new functions for working with permissions in tool metadata |
pkg/scopes/scopes_test.go | Added 5 comprehensive test functions covering all new permission functionality including helper functions, metadata operations, and edge cases |
docs/tool-permissions.md | Created new 312-line documentation file organizing all tools by category with OAuth scopes and fine-grained permissions, plus permission hierarchy explanations and use-case guides |
README.md | Added two strategic links to the new tool permissions documentation in the Prerequisites and Tools sections |
This was referencedNov 25, 2025
Sign up for freeto join this conversation on GitHub. Already have an account?Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds fine-grained permission types to the scopes package and creates comprehensive tool permissions documentation.
Changes
Extended
pkg/scopes/scopes.goAdded support for fine-grained personal access token permissions:
New Types:
Permission- Fine-grained permission constants (e.g.,PermActions,PermContents,PermIssues,PermPullRequests)PermissionLevel- Access levels (PermissionRead,PermissionWrite,PermissionAdmin)FineGrainedPermission- Struct combining permission and levelNew Functions:
WithScopesAndPermissions()- Create Meta with both OAuth scopes and fine-grained permissionsAddPermissions()- Add permissions to existing Meta mapGetPermissionsFromMeta()- Extract permissions from tool MetaReadPerm(),WritePerm(),AdminPerm()- Convenience constructorsPerm()- General permission constructorNew
docs/tool-permissions.mdComprehensive documentation covering:
Categories documented:
Updated README.md
Added links to the new permissions documentation:
Testing
TestFineGrainedPermissionStringTestWithScopesAndPermissionsTestAddPermissionsTestAddPermissionsToNilMetaTestGetPermissionsFromMetaTestPermHelperFunctionsPart of OAuth Scopes Work (Phase 2 of 4)