Repo collaborators
Mirrors GitHub's /repos/{owner}/{repo}/collaborators family of
endpoints — manage the per-repo role grants that policy.Can
consults for non-owner callers.
All endpoints share the canonical API conventions
(JSON error envelopes, X-RateLimit-*, Link: pagination on
the list endpoint).
Auth
| Method | Required scope | Policy gate |
|---|---|---|
| GET | repo:read |
ActionRepoRead |
| PUT | repo:write |
ActionRepoAdmin |
| DELETE | repo:write |
ActionRepoAdmin |
Mutations are restricted to repo owners and admin-role
collaborators. shithub doesn't currently mint a separate
repo:admin scope; the per-route policy check enforces the
admin floor on top of the broader repo:write scope.
Endpoints
GET /api/v1/repos/{owner}/{repo}/collaborators
GET /api/v1/repos/{owner}/{repo}/collaborators/{username}
GET /api/v1/repos/{owner}/{repo}/collaborators/{username}/permission
PUT /api/v1/repos/{owner}/{repo}/collaborators/{username}
DELETE /api/v1/repos/{owner}/{repo}/collaborators/{username}
List
Returns every direct collaborator row for the repo (org owner
membership is exposed separately under /orgs/{org}/members).
[
{
"user_id": 42,
"username": "bob",
"display_name": "Bob",
"role": "write"
}
]
Membership probe
GET .../collaborators/{username} returns 204 No Content
when the user is a collaborator, 404 otherwise. No body —
clients check the status code directly. Mirrors GitHub's
behaviour.
Permission level
{ "user": "bob", "permission": "write" }
permission is one of read / triage / write / maintain
/ admin, or "none" when the user is not a collaborator.
Add or upgrade
PUT /api/v1/repos/alice/demo/collaborators/bob
Content-Type: application/json
{ "role": "write" }
role accepts the shithub canonical names plus the GitHub-style
aliases (pull → read, push → write). Returns the
upgraded row at 200. Refuses (422) to enrol the repo owner — an
owner already has full implicit access, so a collaborator row
would only confuse the policy decision.
Remove
DELETE /api/v1/repos/alice/demo/collaborators/bob
Returns 204. Idempotent — removing a non-collaborator still
returns 204 (matches gh).
View source
| 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). |