Permissions
Permissions and the tools they unlock
A fine-grained token only needs the permissions for the tools you plan to use. The token generator applies one of two presets, or you can choose individual permissions.
Read-only
Explore repositories, read issues and pull requests, and search code. No changes are made.
Metadata read, Contents read, Issues read, Pull requests read, Issue fields read, Issue types read, Projects read.
Read-write
RecommendedEverything in Read-only, plus creating and updating issues, files, labels, projects and pull requests.
Contents write, Issues write, Pull requests write, Issue fields write, Projects write.
Which permission each tool needs
| Permission | Level | Tools | What it is for |
|---|---|---|---|
| Metadata | read | owner_list_repository, repository_search | Included in every preset. Required for repository access. |
| Contents | read | file_get_content, code_search | Read files and search code. |
| Contents | write | file_create_update, file_delete, pull_request_merge | Create, update and delete files. Also required to merge a pull request. |
| Issues | read | issue_read, issue_list, issue_search, label_list, issue_get_field_value | Read issues, comments and labels. |
| Issues | write | issue_create, issue_add_comment, issue_add_label, issue_remove_label, issue_update, issue_close, issue_reopen, sub_issue_write, label_write, issue_set_field_value | Create and update issues, comments and labels. |
| Pull requests | read | pull_request_read | Read pull requests, commits and reviews. |
| Pull requests | write | pull_request_create | Create pull requests from an existing branch. |
| Issue fields | read | owner_list_issue_field, issue_get_field_value, issue_set_field_value, issue_list (with include_fields or filter_fields), issue_read (with include_fields) | Read Priority, Effort and date values. |
| Issue fields | write | issue_set_field_value | Set or clear Priority, Effort and date values. |
| Issue types | read | owner_list_issue_type | List organization issue types. |
| Projects | read | owner_list_project, projects_get, issue_list (with include_project_fields or filter_fields) | Read organization Projects v2 items and fields. |
| Projects | write | projects_write | Add items and update field values in organization Projects v2. |
| No permission required | - | auth_get_current_login, server_info, profile_get, owner_list_organization, organization_search | Sign-in, profile and public search. |
Merging a pull request needs Contents write, not just Pull requests
write. The Read-write preset includes it, so you only need to think about this if you
build a custom token.