GitHub backend¶
livery.forge.GithubForge: the protocol over REST v3 plus the one
GraphQL pair auto-merge requires.
Construction and the token rule¶
GithubForge.connect() speaks to github.com unless a GitHub
Enterprise URL is given (its API root is <url>/api/v3). The token
resolves as GITHUB_TOKEN first, then gh auth token, so a machine
with a signed-in gh CLI needs no configuration; nothing found raises
at connect time. Pass token="" to read anonymously on purpose.
Full scratch-and-release development needs the repo, workflow,
and delete_repo scopes; a token missing one gets GitHub's refusal
verbatim.
Capabilities¶
auto_merge, force_cancel, required_contexts, min_approvals, and schedule_events are supported.
ci_secrets depends on the github-secrets extra: GitHub's secrets
API takes only values sealed to the repository's public key
(libsodium), so livery-forge[github-secrets] installs PyNaCl and
turns the capability on, and a bare install declines by name with the
extra's name in the message. The public key and its id come from the
API; nothing is configured by hand. The import is lazy: nothing
outside the secrets path loads it, and forge.supports("ci_secrets")
answers for the running install.
Mapping notes¶
- Auto-merge is GraphQL only (
enablePullRequestAutoMerge/disablePullRequestAutoMerge); everything else is REST. GraphQL failures answer 200 with anerrorsarray, which the backend raises aslivery.forge.ForgeErrorwith GitHub's words verbatim. - GitHub only arms a pull request that something blocks: the
repository needs
allow_auto_mergeon and branch protection naming required contexts (the check context is the job name). Re-arming replaces the schedule by disarm-then-enable, because GitHub cannot update an armed schedule's commit headline. - The auto-merge mutation takes at most 320 UTF-8 bytes of commit
headline and 65535 of commit body.
pr.armcuts a longer title at the last word boundary within 320 bytes (inside a word only when no word ends within them), so the squash subject is the title's start; it refuses a longer body before any call, since a cut body would lose its closing footers. GitHub's own refusals name a quarter of each limit as characters. checks.statusfolds GitHub's two reporting systems, commit statuses and check runs, into the one combined verdict.checks.job_loganswers with a redirect to a signed, short-lived URL. The refused redirect carries the location in the error's detail and is followed once, bare, with no token attached: the one redirect this package ever follows.- Pull requests and issues share the number space and the issue
endpoints; listings filter pull requests out and
issue.geton a pull request's number answers None.pr.add_labelswrites through the issue labels endpoint, which creates a label it does not know, so the repository's labels are read first and a stranger is refused by name before the write. issue.searchmatches text client-side over the complete listing: GitHub's search API indexes asynchronously, and a probe that can miss what was just created is not a probe. Issue listings themselves run several seconds behind writes, which is the conformance driver'sawait_issuebound.- Lookups ask the narrowest query GitHub has:
pr.find_by_headsendshead=<owner>:<branch>,pr.find_by_head_shaasks the commit (GET /repos/:owner/:repo/commits/:sha/pulls),tags(prefix)readsgit/matching-refs/tags/<prefix>, which answers whole and unpaged, andrunswith a workflow reads that workflow's own listing. Each answer is matched again client-side. A run'srefis itshead_branch. dispatchsendsreturn_run_details: truein the body, and GitHub answers 200 naming the run inworkflow_run_id, which comes back. A server without the run's details answers 204 with no body: None comes back, and the caller finds the run inrunsby its event,refandhead_sha.mergeableis computed asynchronously after a pull request opens; merging inside that window is refused and callers retry.merge_commit_shanames a test merge commit while a pull request is open, once GitHub has computed its mergeability. The backend reports it asmerged_shaonly once the pull request has merged.pr.listbuilds each pull request from its listing row. A row saysmerged_atwhere the single read saysmerged, and the backend reads either.- Branch protection is one whole-rule PUT: the pieces the caller did
not state (contexts, approvals, the codeowner ask, the up-to-date
requirement) are read back and re-sent, so an approvals-only write
cannot clear the contexts. Push restrictions and the review
settings the protocol does not model are cleared by that PUT.
Admins are always bound (
enforce_admins). membersandteamsspeak the org endpoints; on a personal namespace they 404, and the fallback answers the login itself and an empty team list. The codeowners dialect is.github/CODEOWNERS; a per-path approval count above one is approximated repository-wide and reported in the rendering's notes.
Fixtures¶
Recording runs against scratch repositories named
livery-forge-conf-* under the signed-in user, created public
(branch protection on private repositories needs a paid plan) and
deleted as scenarios re-run. fm forge.fixtures.record re-records;
the replayed cassettes gate merges with no network and no credential.