The GitHub-shaped edge: /api/v3 and gh
Zuppo serves a named subset of GitHub's REST API under /api/v3, and the fixed GraphQL operations stock gh sends to /api/graphql, so gh and Octokit work against…
Zuppo serves a named subset of GitHub's REST API under /api/v3, and the fixed GraphQL operations stock gh sends to /api/graphql, so gh and Octokit work against it unchanged (IFC-5, ARC-57, API-3). It is a translation layer over zuppo.v1: every call runs the caller's own token through the same grants, scopes, policy and quotas as a Connect or REST call. Nothing here grants more.
Everything outside the lists below answers 501 Not Implemented with a link to this page. There is no general GraphQL server: gh speaks GraphQL for pr create, pr ready, pr view, pr list, pr review, pr checks and repo view, so those operations (and the introspection queries its feature detection sends) are served; any other operation is a 501.
Pointing a client at it
# gh: Zuppo is a GitHub Enterprise Server host (HTTPS in front of zuppo-apid) export GH_HOST=zuppo.example.com export GH_ENTERPRISE_TOKEN=<an access token> # or GH_TOKEN with GH_HOST set gh pr create --draft --title "Add retry" --body "..." # Octokit new Octokit({ baseUrl: "https://zuppo.example.com/api/v3", auth: "<token>" })
Authorization: token <t> and Authorization: Bearer <t> both work. Tokens are Zuppo access tokens (zpa_…); DPoP-bound tokens cannot be used here (GitHub clients do not send DPoP). GET /api/v3/meta answers an installed_version (and every answer an X-GitHub-Enterprise-Version header) so gh treats the host as GHES.
Model
| GitHub | Zuppo |
|---|---|
{owner} | the org |
| repository | repository |
| pull request | change; its number is the repository's sequence number, in creation order |
head.ref | the branch the change was opened from (source_ref); zuppo/changes/<n> when unknown |
head.sha, base.sha | the change's current revision commit and base |
| draft | change state DRAFT; ready/queued are open, landed is closed and merged, abandoned is closed |
review event | review verdict APPROVE, REQUEST_CHANGES, COMMENT |
| check run | check run of the change whose current revision has head_sha |
author_association, authorAssociation | MEMBER only for a member's text typed into the forge; agents, tools, outsiders and imported text are NONE. REST pull requests and reviews carry the forge's trust label in zuppo.trust (author_trust, source, untrusted) |
| (no equivalent) | stacks: /repos/{o}/{r}/stacks |
Every pull request opens as a draft: only a person marks a change ready (F3). A non-draft request is a draft followed by MarkReady; for an agent token the forge refuses (agent-forbidden), the pull request stays a draft, and the answer says so (zuppo.ready_refused). gh pr ready and the GraphQL markPullRequestReadyForReview mutation from an agent token are refused with 403. Approving needs a person who has read every shown hunk (F4); an approval without that coverage is refused with the forge's problem.
Pull requests are listed newest first (the forge lists oldest first; the walk is capped at 2,000 changes). Ids GitHub shows as integers are 48-bit hashes (users, repositories, pull requests, check suites) or sub-resource codes below 2^53 (reviews: number << 31 | code; check runs: number << 31 | hash(check name, reporter)), so they stay exact in JavaScript. A check run's id is stable while the run is replaced by a later report of the same check from the same reporter; it names the newest run of that check on that pull request.
REST subset
| Route | Maps to |
|---|---|
GET / , GET /meta | URL templates; GHES version |
GET /orgs/{o}/repos | ListRepos |
GET /repos/{o}/{r} | GetRepo |
GET /repos/{o}/{r}/contents/{path}?ref= | BatchRead (text files up to 1 MiB; binary: 403 too_large; no directory listings) |
GET /repos/{o}/{r}/commits?sha=&path= | Log |
GET /repos/{o}/{r}/commits/{ref} | Log + GetDiff (files with patches) |
GET /repos/{o}/{r}/commits/{ref}/check-runs | check runs of the open changes with that head |
GET /repos/{o}/{r}/pulls?state=&head=&base=&direction= | ListChanges |
GET /repos/{o}/{r}/pulls/{n} | ListChanges, GetRevision, GetMergeability |
POST /repos/{o}/{r}/pulls | Log, MergeBase, BatchCreateChanges (one change from the pushed branch), MarkReady unless draft |
GET /repos/{o}/{r}/pulls/{n}/files | GetDiff |
GET /repos/{o}/{r}/pulls/{n}/commits | Log (a change is one commit per revision) |
GET /repos/{o}/{r}/pulls/{n}/reviews[/{id}] | ListReviews |
POST /repos/{o}/{r}/pulls/{n}/reviews | CreateReview (event required: no pending reviews; no inline comments: those are findings) |
POST /repos/{o}/{r}/check-runs | CreateCheckRun on every open change whose head is head_sha |
GET/PATCH /repos/{o}/{r}/check-runs/{id} | GetCheckRun; re-report merged with the existing run (a check cannot be renamed) |
GET /repos/{o}/{r}/check-runs/{id}/annotations | the run's failures |
GET /repos/{o}/{r}/stacks[/{id}] | ListStacks, GetStack, ListChanges |
Lists take per_page (1–100, default 30) and page (at most 100) and answer a Link header. Errors are GitHub's {message, documentation_url, status, errors[]}; the forge's problem rides along in zuppo (reason is its slug, e.g. agent-forbidden). Rate-limit headers are the caller's limits, as on the native API: x-ratelimit-limit, -remaining, -used, -reset (Unix seconds) and -resource (e.g. points_per_hour) for the limit closest to running out, and the IETF RateLimit-Policy/RateLimit fields for every limit in force.
Check runs: an agent's report is declared and never satisfies a required check (zuppo.evidence); a report on a completed run may carry annotations (they become failures); annotations on an unfinished run are refused.
GraphQL (POST /api/graphql)
Operations are matched by shape, not by name: the selection decides what is fetched. Served roots and fields (gh 2.101):
repository(owner, name):id name owner defaultBranchRef viewerPermission description sshUrl mergeCommitAllowed …,pullRequests(states, headRefName, baseRefName, first, orderBy),pullRequest(number);node(id)for pull requests.PullRequest:id number title body state isDraft url headRefName baseRefName headRefOid author headRepositoryOwner isCrossRepository mergeable mergeStateStatus reviewDecision additions deletions reviews latestReviews commits files statusCheckRollupand the constant-empty fieldsghasks for (labels, assignees, projects, comments, …).- Mutations:
createPullRequest,markPullRequestReadyForReview,addPullRequestReview.convertPullRequestToDraftis refused: a ready change cannot go back to draft. - Introspection:
__type(name:)for the typesghprobes (the field lists say what Zuppo serves). - Limits: a document plans at most 64 nested selection sets and 5,000 selections with its fragments expanded (gh's documents use under 200); a larger one answers a GraphQL error (
Query is too deeply nested,Query is too complex) before anything is fetched.
gh commands covered by the conformance suite: pr create --draft, pr create, pr ready, pr view --json, pr list --json, pr review, pr checks, repo view --json, gh api over the REST subset.
Not in the subset
Merging (PUT …/merge: landing goes through the merge queue), editing or closing pull requests, issues, users (/user), organizations beyond repository listing, git data endpoints, statuses, hooks, search, GraphQL viewer/search (so gh pr status fails with GitHub's "field doesn't exist" error), and everything else. Each is a 501.