DocsOpen app

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

sh
# 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

GitHubZuppo
{owner}the org
repositoryrepository
pull requestchange; its number is the repository's sequence number, in creation order
head.refthe branch the change was opened from (source_ref); zuppo/changes/<n> when unknown
head.sha, base.shathe change's current revision commit and base
draftchange state DRAFT; ready/queued are open, landed is closed and merged, abandoned is closed
review eventreview verdict APPROVE, REQUEST_CHANGES, COMMENT
check runcheck run of the change whose current revision has head_sha
author_association, authorAssociationMEMBER 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

RouteMaps to
GET / , GET /metaURL templates; GHES version
GET /orgs/{o}/reposListRepos
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-runscheck 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}/pullsLog, MergeBase, BatchCreateChanges (one change from the pushed branch), MarkReady unless draft
GET /repos/{o}/{r}/pulls/{n}/filesGetDiff
GET /repos/{o}/{r}/pulls/{n}/commitsLog (a change is one commit per revision)
GET /repos/{o}/{r}/pulls/{n}/reviews[/{id}]ListReviews
POST /repos/{o}/{r}/pulls/{n}/reviewsCreateReview (event required: no pending reviews; no inline comments: those are findings)
POST /repos/{o}/{r}/check-runsCreateCheckRun 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}/annotationsthe 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 statusCheckRollup and the constant-empty fields gh asks for (labels, assignees, projects, comments, …).
  • Mutations: createPullRequest, markPullRequestReadyForReview, addPullRequestReview. convertPullRequestToDraft is refused: a ready change cannot go back to draft.
  • Introspection: __type(name:) for the types gh probes (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.