[Schema Inaccuracy] `permission` on Add a repository collaborator is valid on personal-account repositories

Open Beginner friendly
#7,010 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
85/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
openapi
Domain
api, documentation

Research direction

Start in descriptions/[api.github.com/], checking api.github.com.2022-11-28.json and api.github.com.2026-03-10.json for the Add a repository collaborator operation. Update the permission parameter description to distinguish personal-account and organization-owned repositories, then verify both versions consistently document the accepted values and restrictions.

Written by the indexing model from the issue text.

Description

documentation

Schema Inaccuracy

Operation: PUT /repos/{owner}/{repo}/collaborators/{username} (Add a repository
collaborator).

The description of the permission body parameter states:

The permission to grant the collaborator. Only valid on organization-owned repositories.

That restriction does not hold. On a repository owned by a personal account the parameter
is honoured for pull, push and admin. Only triage and maintain are
organization-only.

Expected

The permission parameter description should state that on organization-owned
repositories all of pull, triage, push, maintain, admin and custom repository
roles are accepted, while on repositories owned by a personal account only pull, push
and admin are accepted — triage and maintain return 422 Validation Failed.

Reproduction Steps

Against a private repository owned by a personal account:

$ curl -X PUT
-H "Authorization: Bearer $TOKEN"
-H "Accept: application/vnd.github+json"
-H "X-GitHub-Api-Version: 2022-11-28"
https://api.github.com/repos/OWNER/REPO/collaborators/USERNAME
-d '{"permission":"pull"}'

→ HTTP 201, and the returned invitation object contains "permissions": "read".

Full sweep of all five values, cancelling the invitation between attempts:

requested HTTP recorded permissions
pull 201 read
triage 422 Validation Failed
push 201 write
maintain 422 Validation Failed
admin 201 admin

Identical sweep against a private organization-owned repository, same script and
token: all five accepted and recorded as requested.

Enforcement matches what is recorded: a collaborator granted pull on a private
personal-account repository has git push rejected by the server.

Note on versioning: this description is identical in both published API versions in
descriptions/[api.github.com/](http://api.github.com/) on main — api.github.com.2022-11-28.json and
api.github.com.2026-03-10.json both contain the "Only valid on organization-owned
repositories." sentence verbatim. So this is not a leftover in an older version.

Related documentation issue: github/docs#45537

Dominant language
No language data
Stars
1.6k
Forks
342
Avg merge
3h 33m
Merged PRs (30d)
51

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from github/rest-api-description

All issues in github/rest-api-description

Similar issues

More Backend & API Design issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.