GitHub client
Create one patchula_github::Client per batch and clone it for repository
tasks; clones share the token, connection pool, governor and stats.
Client::new takes a token and builds one shared reqwest pool through
patchula-http, and with_transport injects replay without a network client.
with_credentials takes refreshable credentials, such as an App installation,
and keeps the pool, governor and cache namespace across token renewals. The
client never reads the environment; the CLI and server supply the credentials.
App tokens
Section titled “App tokens”app::App holds a GitHub App’s ID and private key. It signs RS256 JWTs,
backdated 60 seconds and valid for ten minutes, and uses them to look up a
repository’s or organisation’s installation, list installations and read the
App’s bot login, client ID and webhook URL. App::installation returns
credentials that mint installation access tokens on demand. A token is reused
until two minutes before it expires, and one lock per App means simultaneous
requests never mint twice. App requests resolve against the configured API
root, so an Enterprise deployment’s App endpoints work too. No credential
reaches SQLite.
Installation credentials can also mint a token scoped to one repository:
Credentials::scoped_token("owner/name", permissions) reads the repository’s
numeric id with the installation token (GET /repos/{owner}/{repo}), then
posts {"repository_ids": [<id>], "permissions": …} to
app/installations/{id}/access_tokens. Permissions::MetadataRead
({"metadata": "read"}) is what the actions.lock tool and mise’s public
listings get: it reads public repositories, whose releases and tags any
token may list, and no private repository’s contents, the minted one’s
included. Permissions::ContentsRead ({"contents": "read", "metadata": "read"}) is what mise gets for a listing kept for the repository alone,
enough to list the repository’s own releases and tags.
Credentials::repository_id answers the numeric id the mint names, which
keys what such a listing serves. GitHub answers the token with the
permissions, repositories and repository_selection it minted. The full
installation mint stays body-less. Scoped tokens share the cache and the
single-flight lock, keyed by (installation, repository, permission set), so
two repositories mint separately and a fuller token never answers a narrower
mint. Only App installation credentials answer scoped_token,
repository_id and mints_scoped_tokens; every other credential returns
None, and the actions.lock tool and mise use the run’s own token. A
real-installation proof lives ignored in crates/github/tests/app.rs: set
PATCHULA_TEST_APP_ID, PATCHULA_TEST_APP_KEY_FILE,
PATCHULA_TEST_INSTALLATION, PATCHULA_TEST_REPO and
PATCHULA_TEST_OTHER_PRIVATE_REPO, then run
mise exec -- cargo test -p patchula-github --test app -- --ignored.
Token scope
Section titled “Token scope”The cache namespace of a client built from a token is a SHA-256 of the
token, which a token minted per run changes every run. Client::identify
replaces it, before the client is cloned, for an installation token (ghs_,
which includes an Action’s GITHUB_TOKEN). It reads, live and never from the
cache:
GET /installation/repositories?per_page=100, at most ten pages, forrepository_selectionand the repository ids;- GraphQL
viewer { databaseId }, the App’s bot user; GET /repos/{repository}/commits?per_page=1on a repository in the set, a private one when there is one, which needscontents: read.
The scope is then {api root}|app:{bot id}/repos:{sha256 of the sorted ids}
whatever the selection, so a token narrowed to some repositories never shares
the full installation’s entries even if GitHub called its selection all.
Any non-2xx answer, a missing or unknown repository_selection or one that
changes between pages, a listing past the page cap, empty, naming a
repository twice or whose count disagrees with total_count, a viewer
without an id, or a failed contents read keeps the token hash. An
installation with more than a thousand repositories therefore keeps it too.
Personal, OAuth and user tokens keep it without a request. The threat
model says why the scope may leave
permissions out.
unrevalidated::ENDPOINTS lists every endpoint whose cached answer is
returned without asking GitHub: Git blobs, recursive trees and commits, under
repos/{owner}/{repo} or a renamed repository’s repositories/{id}. A read
that skips revalidation on anything else fails with Error::Unrevalidated,
and a unit test checks the path of every get_immutable call in the
workspace against the list.
Transport
Section titled “Transport”reqwest 0.13 uses HTTP/2 negotiation, rustls, gzip, brotli and zstd
decompression, a 10-second connect, 30-second read and 60-second total request
timeout, and a 90-second idle pool timeout. User-Agent is
patchula/<workspace version>. Automatic retries are off so the governor owns
request accounting, and automatic redirects are off too: a REST GET follows
same-origin redirects itself, at most ten requests in all. Cross-origin URLs
and URLs with embedded credentials are rejected before the token is sent.
api_url can select another HTTPS API root, and GraphQL resolves as
graphql relative to it, so an Enterprise deployment whose GraphQL root is
elsewhere is not supported yet.
Authorization headers are marked sensitive, and Debug output, Display output
and errors omit tokens and bodies. Request diagnostics use an allowlist of
fields, so headers, bodies and query strings never reach the logger; the CLI
enables them with -vv or PATCHULA_LOG=debug.
Conditional reads
Section titled “Conditional reads”Every REST GET looks up validators in SQLite and sends If-None-Match or
If-Modified-Since when it has them, even after expiry. The exception is a
read whose answer cannot change, a Git blob, commit or tree named by its SHA:
get_immutable returns a cached success without a request. blobs reads many at once: those
the cache holds need no request, the rest go through GraphQL fifty to a query,
and a blob counts from GraphQL only when its text hashes to the SHA asked for.
Binary, truncated or mismatched blobs come through REST instead. Either way the
blob is cached as its REST representation. A cached blob counts only when it
hashes to its SHA too; one that does not is dropped and read again. A 304 reuses the
cached status and body and merges headers, keeping a cached pagination Link
if GitHub omits it. no-store, Vary: * and Vary: User-Agent responses are
not kept. Any other Vary names a header the key holds (Accept, the API
version), one the client never sends, Accept-Encoding (bodies are stored
decoded) or authorization, which the key’s credential namespace covers: a
refreshed token is the same installation. So Vary never splits the key. Keys include the normalised URL, Accept, the API
version and a SHA-256 namespace of the credential’s scope (see token
scope), so data is shared only between credentials with the
same reach; tokens are never stored in keys. Cookies and
authorization are never cached.
Writes
Section titled “Writes”post, patch and put send JSON to the REST API, and graphql sends
queries and mutations. The Count uses them to create Git objects, publish refs
with updateRefs, and open, edit and close PRs, the dashboard issue and
auto-merge. Writes never enter the cache. Any response other than a 2xx is an
error, and only documented rate-limit refusals are retried: a transport or
server failure may already have written, so the next run reconciles instead.
Every REST request other than GET, HEAD and OPTIONS, and every GraphQL
document whose text starts with mutation (or whose body cannot be parsed),
runs one at a time across all clones of a client, paced by a token bucket of
github.writeBurst tokens (12 by default) refilling one a second — the
first writes of a run go out without a pause, and no minute holds more than
writeBurst + 60 (72 by default, at most 79) — and at most 500 an hour,
inside GitHub’s
best practices
and content-creation limit. Any secondary-rate-limit answer cuts the budget
to one token for the next hour, the one write a second GitHub asks for. A
mutation document must start with the mutation keyword, with no leading
comment, or it is paced as a read. Each installation’s engine has its own
client, so the server’s batches for different installations pace their
writes separately.
Typed responses
Section titled “Typed responses”get_fresh, get_immutable, post, patch, put and graphql are generic over the type
they decode into, like rest_pages already was. A response that does not
decode is an Error::Decode, which names the operation and the field path
only: serde’s message is never kept, because a type-mismatch message can
quote response text that would reach dashboards and public pages.
patchula_github::model holds the REST resource types the lifecycle,
dashboard, batch, server and discovery listings read: deserialize only,
unknown fields ignored, and Option only where GitHub’s OpenAPI description
documents null or a missing field must fail closed.
model::Page<T> decodes a list element by element: an element that fails
marks the page incomplete and stays out of items, so a partial read blocks
every action that depends on the whole set rather than silently acting on
the readable subset.
Static GraphQL documents — the inventory, status-check, ref-update,
auto-merge, repository-head and releases operations — live as .graphql
files beside the code that issues them. graphql_client’s GraphQLQuery
derive checks each against the vendored schema at
crates/github/graphql/schema.docs.graphql and generates the response types:
a schema-required field generates a plain field, a nullable one an Option,
and interface and union selections generate enums decoded on __typename,
which the document must therefore select. mise run github:schema refreshes
the vendored schema. Dynamic documents — the alias batches that read many
objects in one query — keep hand-written response types, since generated
code cannot name them.
Rate limits
Section titled “Rate limits”The library’s default in-flight cap is 4, shared by REST and GraphQL;
callers can set concurrency=1 for serial requests, which GitHub recommends
to minimise secondary limits. A token run (the CLI) sizes it from the
api.github.com host limit when one is set, and otherwise from the default
host limit capped at 16 (see host limits).
No cap guarantees against secondary throttling.
The governor tracks the x-ratelimit-* headers per resource (core, search and
graphql), reserves known remaining capacity for in-flight requests and waits
until an exhausted window resets, plus one second. A 304 refunds its
reservation. While a bucket is exhausted its reset only moves later, so a
response still in flight can’t cut short a wait a rate-limit answer set. Once
the reset passes the bucket is unknown again and queued requests go ahead.
Secondary 403 and 429 responses (Retry-After, documented secondary or abuse
messages, or GraphQL RATE_LIMITED errors) set a cooldown shared by all tasks.
Retry-After seconds or dates are honoured; otherwise the delay starts at 60
seconds and doubles. When a primary reset and Retry-After both apply, the
longer wait wins. By default a request is retried three times, and a requested
wait over one hour fails rather than retrying early. Ordinary permission errors
are not retried. Requests already in flight may finish while a new cooldown
blocks later ones.
Stats and request lines
Section titled “Stats and request lines”stats() returns transport attempts, 304s, retries, summed queue and rate
wait, and the primary limit snapshots. Debug request lines show the method,
host, sanitised path, status, cache outcome, body bytes, wait and total time,
and the negotiated protocol. reqwest does not expose connection or TLS reuse or
timings, so those fields say unavailable rather than being guessed.
Pagination
Section titled “Pagination”REST pagination follows Link rel=next URLs as given, never inventing page
numbers. GraphQL pagination puts the returned endCursor into $cursor, and
GraphqlPage::from_connection reads nodes and pageInfo at a JSON pointer.
Both call a stop predicate on each page before fetching the next and return the
stopping page, so a cache merge can take its new prefix and ignore the known
rest. Repeated pages or cursors fail instead of looping, and the default budget
is 1,000 pages.
Fixtures
Section titled “Fixtures”fixtures/github/public-{releases,tags,graphql}.json were recorded from public
GitHub endpoints; releases include a real 200 and 304 exchange. Simulated
cassettes cover two-page pagination that stops at known history, rate limits,
permission errors, redirects and cache policy. Tests use Tokio’s paused clock
for minute-scale backoff. HTTP fixtures covers
recording.
© 2026 Sweepy
