@@ -0,0 +1,88 @@ |
| 1 | +# Repo collaborators |
| 2 | + |
| 3 | +Mirrors GitHub's `/repos/{owner}/{repo}/collaborators` family of |
| 4 | +endpoints — manage the per-repo role grants that policy.Can |
| 5 | +consults for non-owner callers. |
| 6 | + |
| 7 | +All endpoints share the canonical [API conventions](overview.md) |
| 8 | +(JSON error envelopes, `X-RateLimit-*`, `Link:` pagination on |
| 9 | +the list endpoint). |
| 10 | + |
| 11 | +## Auth |
| 12 | + |
| 13 | +| Method | Required scope | Policy gate | |
| 14 | +|--------|---------------|-------------| |
| 15 | +| GET | `repo:read` | `ActionRepoRead` | |
| 16 | +| PUT | `repo:write` | `ActionRepoAdmin` | |
| 17 | +| DELETE | `repo:write` | `ActionRepoAdmin` | |
| 18 | + |
| 19 | +Mutations are restricted to repo owners and `admin`-role |
| 20 | +collaborators. shithub doesn't currently mint a separate |
| 21 | +`repo:admin` scope; the per-route policy check enforces the |
| 22 | +admin floor on top of the broader `repo:write` scope. |
| 23 | + |
| 24 | +## Endpoints |
| 25 | + |
| 26 | +``` |
| 27 | +GET /api/v1/repos/{owner}/{repo}/collaborators |
| 28 | +GET /api/v1/repos/{owner}/{repo}/collaborators/{username} |
| 29 | +GET /api/v1/repos/{owner}/{repo}/collaborators/{username}/permission |
| 30 | +PUT /api/v1/repos/{owner}/{repo}/collaborators/{username} |
| 31 | +DELETE /api/v1/repos/{owner}/{repo}/collaborators/{username} |
| 32 | +``` |
| 33 | + |
| 34 | +### List |
| 35 | + |
| 36 | +Returns every direct collaborator row for the repo (org owner |
| 37 | +membership is exposed separately under `/orgs/{org}/members`). |
| 38 | + |
| 39 | +```json |
| 40 | +[ |
| 41 | + { |
| 42 | + "user_id": 42, |
| 43 | + "username": "bob", |
| 44 | + "display_name": "Bob", |
| 45 | + "role": "write" |
| 46 | + } |
| 47 | +] |
| 48 | +``` |
| 49 | + |
| 50 | +### Membership probe |
| 51 | + |
| 52 | +`GET .../collaborators/{username}` returns `204 No Content` |
| 53 | +when the user is a collaborator, `404` otherwise. No body — |
| 54 | +clients check the status code directly. Mirrors GitHub's |
| 55 | +behaviour. |
| 56 | + |
| 57 | +### Permission level |
| 58 | + |
| 59 | +```json |
| 60 | +{ "user": "bob", "permission": "write" } |
| 61 | +``` |
| 62 | + |
| 63 | +`permission` is one of `read` / `triage` / `write` / `maintain` |
| 64 | +/ `admin`, or `"none"` when the user is not a collaborator. |
| 65 | + |
| 66 | +### Add or upgrade |
| 67 | + |
| 68 | +```http |
| 69 | +PUT /api/v1/repos/alice/demo/collaborators/bob |
| 70 | +Content-Type: application/json |
| 71 | + |
| 72 | +{ "role": "write" } |
| 73 | +``` |
| 74 | + |
| 75 | +`role` accepts the shithub canonical names plus the GitHub-style |
| 76 | +aliases (`pull` → `read`, `push` → `write`). Returns the |
| 77 | +upgraded row at 200. Refuses (422) to enrol the repo owner — an |
| 78 | +owner already has full implicit access, so a collaborator row |
| 79 | +would only confuse the policy decision. |
| 80 | + |
| 81 | +### Remove |
| 82 | + |
| 83 | +``` |
| 84 | +DELETE /api/v1/repos/alice/demo/collaborators/bob |
| 85 | +``` |
| 86 | + |
| 87 | +Returns `204`. Idempotent — removing a non-collaborator still |
| 88 | +returns 204 (matches gh). |