Branches and tags
Read-only enumeration of a repo's git refs. Mirrors GitHub's
/repos/{owner}/{repo}/branches + /tags endpoints with one
shithub-specific addition (is_default on branches).
All endpoints require an Authorization: Bearer <pat> header
with the repo:read scope and gate on ActionRepoRead. The
common API conventions apply — JSON error
envelopes, X-RateLimit-* headers, Link: pagination.
List branches
GET /api/v1/repos/{owner}/{repo}/branches[?page=&per_page=]
Paginated (default 30, max 100). Sorted alphabetically by ref name.
[
{
"name": "trunk",
"commit_sha": "5f3a…",
"protected": false,
"is_default": true
},
{
"name": "release/v1.0",
"commit_sha": "8c0d…",
"protected": true,
"is_default": false
}
]
protected reflects the repo's branch-protection rule set —
the longest-prefix match against the configured patterns
(release/*, etc.). An uninitialised / empty repo returns an
empty list rather than 404.
Get a single branch
GET /api/v1/repos/{owner}/{repo}/branches/{branch}
{branch} may contain forward slashes (feature/x,
release/v1.0). The route accepts them verbatim or
URL-encoded (feature%2Fx). Returns the same shape as a list
entry; unknown branches 404.
The registered route literal is
/api/v1/repos/{owner}/{repo}/branches/* so branch names may include
slashes.
List tags
GET /api/v1/repos/{owner}/{repo}/tags[?page=&per_page=]
[
{ "name": "v0.1.0", "commit_sha": "5f3a…" },
{ "name": "v0.2.0", "commit_sha": "9d4e…" }
]
Sorted alphabetically. We don't currently surface annotated-tag metadata (tagger / message) — that's a follow-up if the CLI's release flow needs it.
View source
| 1 | # Branches and tags |
| 2 | |
| 3 | Read-only enumeration of a repo's git refs. Mirrors GitHub's |
| 4 | `/repos/{owner}/{repo}/branches` + `/tags` endpoints with one |
| 5 | shithub-specific addition (`is_default` on branches). |
| 6 | |
| 7 | All endpoints require an `Authorization: Bearer <pat>` header |
| 8 | with the `repo:read` scope and gate on `ActionRepoRead`. The |
| 9 | [common API conventions](overview.md) apply — JSON error |
| 10 | envelopes, `X-RateLimit-*` headers, `Link:` pagination. |
| 11 | |
| 12 | ## List branches |
| 13 | |
| 14 | ``` |
| 15 | GET /api/v1/repos/{owner}/{repo}/branches[?page=&per_page=] |
| 16 | ``` |
| 17 | |
| 18 | Paginated (default 30, max 100). Sorted alphabetically by ref |
| 19 | name. |
| 20 | |
| 21 | ```json |
| 22 | [ |
| 23 | { |
| 24 | "name": "trunk", |
| 25 | "commit_sha": "5f3a…", |
| 26 | "protected": false, |
| 27 | "is_default": true |
| 28 | }, |
| 29 | { |
| 30 | "name": "release/v1.0", |
| 31 | "commit_sha": "8c0d…", |
| 32 | "protected": true, |
| 33 | "is_default": false |
| 34 | } |
| 35 | ] |
| 36 | ``` |
| 37 | |
| 38 | `protected` reflects the repo's branch-protection rule set — |
| 39 | the longest-prefix match against the configured patterns |
| 40 | (`release/*`, etc.). An uninitialised / empty repo returns an |
| 41 | empty list rather than 404. |
| 42 | |
| 43 | ## Get a single branch |
| 44 | |
| 45 | ``` |
| 46 | GET /api/v1/repos/{owner}/{repo}/branches/{branch} |
| 47 | ``` |
| 48 | |
| 49 | `{branch}` may contain forward slashes (`feature/x`, |
| 50 | `release/v1.0`). The route accepts them verbatim or |
| 51 | URL-encoded (`feature%2Fx`). Returns the same shape as a list |
| 52 | entry; unknown branches `404`. |
| 53 | |
| 54 | The registered route literal is |
| 55 | `/api/v1/repos/{owner}/{repo}/branches/*` so branch names may include |
| 56 | slashes. |
| 57 | |
| 58 | ## List tags |
| 59 | |
| 60 | ``` |
| 61 | GET /api/v1/repos/{owner}/{repo}/tags[?page=&per_page=] |
| 62 | ``` |
| 63 | |
| 64 | ```json |
| 65 | [ |
| 66 | { "name": "v0.1.0", "commit_sha": "5f3a…" }, |
| 67 | { "name": "v0.2.0", "commit_sha": "9d4e…" } |
| 68 | ] |
| 69 | ``` |
| 70 | |
| 71 | Sorted alphabetically. We don't currently surface annotated-tag |
| 72 | metadata (tagger / message) — that's a follow-up if the CLI's |
| 73 | release flow needs it. |