Skip to content

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 an errors array, which the backend raises as livery.forge.ForgeError with GitHub's words verbatim.
  • GitHub only arms a pull request that something blocks: the repository needs allow_auto_merge on 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.arm cuts 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.status folds GitHub's two reporting systems, commit statuses and check runs, into the one combined verdict.
  • checks.job_log answers 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.get on a pull request's number answers None. pr.add_labels writes 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.search matches 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's await_issue bound.
  • Lookups ask the narrowest query GitHub has: pr.find_by_head sends head=<owner>:<branch>, pr.find_by_head_sha asks the commit (GET /repos/:owner/:repo/commits/:sha/pulls), tags(prefix) reads git/matching-refs/tags/<prefix>, which answers whole and unpaged, and runs with a workflow reads that workflow's own listing. Each answer is matched again client-side. A run's ref is its head_branch.
  • dispatch sends return_run_details: true in the body, and GitHub answers 200 naming the run in workflow_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 in runs by its event, ref and head_sha.
  • mergeable is computed asynchronously after a pull request opens; merging inside that window is refused and callers retry.
  • merge_commit_sha names a test merge commit while a pull request is open, once GitHub has computed its mergeability. The backend reports it as merged_sha only once the pull request has merged.
  • pr.list builds each pull request from its listing row. A row says merged_at where the single read says merged, 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).
  • members and teams speak 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.