shithub Public

Watch 1 Fork 0 Star 0
markdown · 1764 bytes Raw Blame History

Repositories

Planned. The repository CRUD API surface is not yet shipped. Today the repo lifecycle is driven through the web UI and the shithubd CLI. The shape below is the planned v1 surface; it will land in a follow-up sprint.

Planned routes

Method Path Scope Purpose
GET /api/v1/repos/{owner}/{repo} repo:read Get one repo.
POST /api/v1/user/repos repo Create a repo under the user.
POST /api/v1/orgs/{org}/repos repo,admin:org Create a repo under an org.
PATCH /api/v1/repos/{owner}/{repo} repo Edit settings.
DELETE /api/v1/repos/{owner}/{repo} repo Delete (with confirmation).
GET /api/v1/repos/{owner}/{repo}/branches repo:read List branches.
GET /api/v1/repos/{owner}/{repo}/branches/{branch}/protection repo:read Get branch protection rules.
PUT /api/v1/repos/{owner}/{repo}/branches/{branch}/protection repo Replace branch protection.

The web UI's behavior is the de-facto specification — when these endpoints land, they implement the same checks (visibility, name collisions, owner-permissions, soft-delete grace) that the web forms enforce.

Today

Until the API ships, scripted repo lifecycle is best done via the shithubd operator CLI on the host (operator-only) or through HTML form submission with a session cookie (per-user but not API-shaped).

View source
1 # Repositories
2
3 > **Planned.** The repository CRUD API surface is not yet
4 > shipped. Today the repo lifecycle is driven through the web UI
5 > and the `shithubd` CLI. The shape below is the **planned** v1
6 > surface; it will land in a follow-up sprint.
7
8 ## Planned routes
9
10 | Method | Path | Scope | Purpose |
11 |--------|---------------------------------------------|--------------|-------------------------------|
12 | GET | `/api/v1/repos/{owner}/{repo}` | `repo:read` | Get one repo. |
13 | POST | `/api/v1/user/repos` | `repo` | Create a repo under the user. |
14 | POST | `/api/v1/orgs/{org}/repos` | `repo,admin:org` | Create a repo under an org. |
15 | PATCH | `/api/v1/repos/{owner}/{repo}` | `repo` | Edit settings. |
16 | DELETE | `/api/v1/repos/{owner}/{repo}` | `repo` | Delete (with confirmation). |
17 | GET | `/api/v1/repos/{owner}/{repo}/branches` | `repo:read` | List branches. |
18 | GET | `/api/v1/repos/{owner}/{repo}/branches/{branch}/protection` | `repo:read` | Get branch protection rules. |
19 | PUT | `/api/v1/repos/{owner}/{repo}/branches/{branch}/protection` | `repo` | Replace branch protection. |
20
21 The web UI's behavior is the de-facto specification — when these
22 endpoints land, they implement the same checks (visibility, name
23 collisions, owner-permissions, soft-delete grace) that the web
24 forms enforce.
25
26 ## Today
27
28 Until the API ships, scripted repo lifecycle is best done via
29 the `shithubd` operator CLI on the host (operator-only) or
30 through HTML form submission with a session cookie (per-user but
31 not API-shaped).