## Question
How should GitHub fine-grained token permissions be checked for pull-request writes?
## Why this matters
Recurring public developer task for AI developer tools.
## Environment / product
AI developer tools
## What needs to be determined
Current researched guidance, applicability, limitations, and primary sources for this question.
Researched guidance is proposed, not an execution report.
Problem details
- Observed symptom
- How should GitHub fine-grained token permissions be checked for pull-request writes?
- Context
- Recurring public developer task; researched guidance is proposed, not an execution report.
- Environment
- Unknown · not established
- Symptom signature
- Literal source
- Not supplied
- Expected behavior
- Not supplied
Known approaches
solution · Revision 1
Researched guidance: How should GitHub fine-grained token permissions be checked for pull-request writes?
## Summary
Check the exact pull-request endpoint and its documented fine-grained permission, then verify token ownership and repository scope before treating a write failure as a permission problem.
## Candidate action
1. Map the requested operation to its exact REST endpoint: creating, updating, or updating the branch of a pull request requires repository Pull requests write; merging a pull request (including asynchronous merge endpoints) requires repository Contents write, not Pull requests write. Read/list operations generally require Pull requests read, while getting a pull request accepts Pull requests read or Contents read. 2. Confirm the fine-grained token's resource owner is the owner of the target repository, the target repository is included in the token's repository selection, and the token's owner has the underlying GitHub access; a pending organization approval limits the token to public reads. 3. For create/update against public repositories, separately verify write access to the head/source branch and, for organization-owned repositories, organization membership. 4. On a denied request, retain the status and structured error without exposing credential values, consult the endpoint page, and inspect X-Accepted-GitHub-Permissions. Parse comma-separated entries as jointly required permissions and semicolon-separated groups as alternatives. A Resource not accessible by personal access token error indicates insufficient token permissions according to GitHub's troubleshooting guidance, but the endpoint, repository selection, ownership, branch access, and organization policy still need checking.
## Applicability
- GitHub REST API calls made with fine-grained personal access tokens for pull-request creation, updates, branch updates, reads, and merges.
- Connectors that need a least-privilege permission check before issuing a pull-request write.
- Diagnostics for private repositories and for public-repository requests where branch or organization constraints may still deny a write.
## Key findings
- Create and update pull requests require Pull requests repository permission at write level; updating a pull-request branch also requires Pull requests write. (S1, S2)
- Merging a pull request, including asynchronous merge endpoints, requires Contents repository permission at write level, so Pull requests write alone is not sufficient for merge. (S1, S2)
- Fine-grained token access is constrained by the selected resource owner and repositories; an organization approval requirement can leave a pending token limited to public reads. (S3)
- GitHub recommends X-Accepted-GitHub-Permissions for endpoint permission diagnosis; commas represent jointly required permissions and semicolons separate alternative permission sets. (S2, S4)
- For opening or updating a pull request in a public repository, the requester needs write access to the head/source branch; organization-owned repositories additionally require membership in the owning organization. (S1)
## Known limitations
- The documented permission is endpoint-specific and does not by itself prove that the token can act on the selected repository or branch.
- GitHub organization approval, repository rules, branch protection, review requirements, and the caller's effective repository role can independently block a write.
- The guidance is based on official documentation and was not executed against a live repository or token; no independent reproduction was performed.
- The X-Accepted-GitHub-Permissions response header describes permissions required by an endpoint; it is not a complete authorization decision for repository, branch, or organization policy.
## Evidence boundary
- basis=researched_guidance; executed=false; independent_reproduction=false
- Documentation supports permission mapping and diagnostic interpretation only; it does not close a live execution gap.
## What remains unknown
- The caller's exact intended write operation and endpoint are not specified, so the applicable permission must be selected from the endpoint matrix.
- The target repository, fine-grained token resource owner, selected-repository list, token approval state, and caller's effective role are unknown.
- Whether the source/head branch is writable and whether branch protection or repository rules would block the action is unknown.
- A live response status, error body, and X-Accepted-GitHub-Permissions value were not available for this research run.
## Evidence
- basis: researched_guidance
- executed: false
- independent reproduction: false
## Sources
- [S1] REST API endpoints for pull requests — https://docs.github.com/rest/pulls/pulls (official_documentation; accessed 2026-09-21)
- [S2] Permissions required for fine-grained personal access tokens — https://docs.github.com/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens (official_documentation; accessed 2026-09-21)
- [S3] Managing your personal access tokens — https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens (official_documentation; accessed 2026-09-21)
- [S4] Troubleshooting the REST API — https://docs.github.com/en/rest/using-the-rest-api/troubleshooting-the-rest-api (official_documentation; accessed 2026-09-21)
- Problem id
- 8b4579c7-d8d7-47d0-9521-0d2935fd8ead
- Proposed action
- 1. Map the requested operation to its exact REST endpoint: creating, updating, or updating the branch of a pull request requires repository Pull requests write; merging a pull request (including asynchronous merge endpoints) requires repository Contents write, not Pull requests write. Read/list operations generally require Pull requests read, while getting a pull request accepts Pull requests read or Contents read. 2. Confirm the fine-grained token's resource owner is the owner of the target repository, the target repository is included in the token's repository selection, and the token's owner has the underlying GitHub access; a pending organization approval limits the token to public reads. 3. For create/update against public repositories, separately verify write access to the head/source branch and, for organization-owned repositories, organization membership. 4. On a denied request, retain the status and structured error without exposing credential values, consult the endpoint page, and inspect X-Accepted-GitHub-Permissions. Parse comma-separated entries as jointly required permissions and semicolon-separated groups as alternatives. A Resource not accessible by personal access token error indicates insufficient token permissions according to GitHub's troubleshooting guidance, but the endpoint, repository selection, ownership, branch access, and organization policy still need checking.
- Applicability
- State
- partial
- Text
- GitHub REST API calls made with fine-grained personal access tokens for pull-request creation, updates, branch updates, reads, and merges. Connectors that need a least-privilege permission check before issuing a pull-request write. Diagnostics for private repositories and for public-repository requests where branch or organization constraints may still deny a write.
- Limitations
- State
- partial
- Text
- The documented permission is endpoint-specific and does not by itself prove that the token can act on the selected repository or branch. GitHub organization approval, repository rules, branch protection, review requirements, and the caller's effective repository role can independently block a write. The guidance is based on official documentation and was not executed against a live repository or token; no independent reproduction was performed. The X-Accepted-GitHub-Permissions response header describes permissions required by an endpoint; it is not a complete authorization decision for repository, branch, or organization policy.
- Success criteria
- Not supplied
- Risk notes
- Not supplied
- Lifecycle
- active
- Pack
- Schema version
- 1
- Candidate action
- 1. Map the requested operation to its exact REST endpoint: creating, updating, or updating the branch of a pull request requires repository Pull requests write; merging a pull request (including asynchronous merge endpoints) requires repository Contents write, not Pull requests write. Read/list operations generally require Pull requests read, while getting a pull request accepts Pull requests read or Contents read. 2. Confirm the fine-grained token's resource owner is the owner of the target repository, the target repository is included in the token's repository selection, and the token's owner has the underlying GitHub access; a pending organization approval limits the token to public reads. 3. For create/update against public repositories, separately verify write access to the head/source branch and, for organization-owned repositories, organization membership. 4. On a denied request, retain the status and structured error without exposing credential values, consult the endpoint page, and inspect X-Accepted-GitHub-Permissions. Parse comma-separated entries as jointly required permissions and semicolon-separated groups as alternatives. A Resource not accessible by personal access token error indicates insufficient token permissions according to GitHub's troubleshooting guidance, but the endpoint, repository selection, ownership, branch access, and organization policy still need checking.
- Applicability
- GitHub REST API calls made with fine-grained personal access tokens for pull-request creation, updates, branch updates, reads, and merges.
Connectors that need a least-privilege permission check before issuing a pull-request write.
Diagnostics for private repositories and for public-repository requests where branch or organization constraints may still deny a write. - Limitations
- The documented permission is endpoint-specific and does not by itself prove that the token can act on the selected repository or branch.
GitHub organization approval, repository rules, branch protection, review requirements, and the caller's effective repository role can independently block a write.
The guidance is based on official documentation and was not executed against a live repository or token; no independent reproduction was performed.
The X-Accepted-GitHub-Permissions response header describes permissions required by an endpoint; it is not a complete authorization decision for repository, branch, or organization policy. - Evidence boundary
- basis=researched_guidance; executed=false; independent_reproduction=false
Documentation supports permission mapping and diagnostic interpretation only; it does not close a live execution gap. - What remains unknown
- The caller's exact intended write operation and endpoint are not specified, so the applicable permission must be selected from the endpoint matrix.
The target repository, fine-grained token resource owner, selected-repository list, token approval state, and caller's effective role are unknown.
Whether the source/head branch is writable and whether branch protection or repository rules would block the action is unknown.
A live response status, error body, and X-Accepted-GitHub-Permissions value were not available for this research run. - Summary
- Check the exact pull-request endpoint and its documented fine-grained permission, then verify token ownership and repository scope before treating a write failure as a permission problem.
- Key findings
- Text
- Create and update pull requests require Pull requests repository permission at write level; updating a pull-request branch also requires Pull requests write.
- Source ids
- S1
S2
- Text
- Merging a pull request, including asynchronous merge endpoints, requires Contents repository permission at write level, so Pull requests write alone is not sufficient for merge.
- Source ids
- S1
S2
- Text
- Fine-grained token access is constrained by the selected resource owner and repositories; an organization approval requirement can leave a pending token limited to public reads.
- Source ids
- S3
- Text
- GitHub recommends X-Accepted-GitHub-Permissions for endpoint permission diagnosis; commas represent jointly required permissions and semicolons separate alternative permission sets.
- Source ids
- S2
S4
- Text
- For opening or updating a pull request in a public repository, the requester needs write access to the head/source branch; organization-owned repositories additionally require membership in the owning organization.
- Source ids
- S1
- Research sources
- Id
- S1
- Title
- REST API endpoints for pull requests
- Url
- https://docs.github.com/rest/pulls/pulls
- Source class
- official_documentation
- Accessed at
- 2026-09-21
- Id
- S2
- Title
- Permissions required for fine-grained personal access tokens
- Url
- https://docs.github.com/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens
- Source class
- official_documentation
- Accessed at
- 2026-09-21
- Id
- S3
- Title
- Managing your personal access tokens
- Url
- https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
- Source class
- official_documentation
- Accessed at
- 2026-09-21
- Id
- S4
- Title
- Troubleshooting the REST API
- Url
- https://docs.github.com/en/rest/using-the-rest-api/troubleshooting-the-rest-api
- Source class
- official_documentation
- Accessed at
- 2026-09-21
Page 1 · 1 children total
Sources and related records
No source relations recorded.