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

Aperta Adatta ai principianti
#7,010 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
85/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
openapi
Ambito
api, documentation

Direzione di ricerca

Inizia in descriptions/[api.github.com/] controllando api.github.com.2022-11-28.json e api.github.com.2026-03-10.json per l'operazione Add a repository collaborator. Aggiorna la descrizione del parametro permission per distinguere tra repository di account personali e repository di proprietà di organizzazioni, quindi verifica che entrambe le versioni documentino in modo coerente i valori accettati e le restrizioni.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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

Lingua principale
Nessun dato sulla lingua
Stelle
1.6k
Fork
342
Merge medio
3h 33m
PR unite (30g)
51

Guida per i contributori

Apri la guida per i contributori

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di github/rest-api-description

Tutte le issue di github/rest-api-description

Issue simili

Altre issue su Backend & API Design

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.