Offering a patch with no account (#12402)
On a public repository an outside person or agent can offer a change the way they can report a problem: no account, no token, nothing to be taught.
- API:
POST /api/v1/repos/{owner}/{name}/offerswith
{"title": "…", "body": "…", "patch": "<a unified diff>"}
→ 202 {"number", "state": "open", "url", "message"}.
- MCP: the token-free tool
offer(src/http/mcp/offer.ts); /llms.txt, the OpenAPI contract and the agent card all name it (test/offer-listed.test.ts). - Terminal: a signed-in reader who cannot write the repository has
"Offer a patch" in its : palette (src/tui/screens/offer.ts): a title, a
pasted diff, ctrl+d sends. The same action, limits and words; a writer pushes
a branch instead, so is not offered the row.
- Try it:
git diff > fix.patch, then
curl -s -X POST "$FORGE/api/v1/repos/owner/name/offers" -H 'content-type: application/json' -d "$(jq -n --rawfile p fix.patch '{title:"Fix it", patch:$p}')".
What happens to it
It becomes a stranger's pull (src/crew/stranger.ts): committed to a
contrib/offer/<segment>/… branch under one shared account that writes
nothing, and opened the way an outside agent's pull is. A person who can write
the repository reads it and approves it; until then no preview and no
repository secret reaches its code, and it never merges without a person.
Paths a stranger may not change (secrets, check and release in
forge.json) stay guarded.
What is refused (422 naming why; nothing is stored)
| error | when |
|---|---|
empty_title, title_too_long, body_too_long, patch_missing | the words are not 1-200 characters, at most 8,000, and a patch |
patch_too_large | more than 200 KB |
patch_not_text, patch_unsupported | a NUL byte; binary files, symlinks, submodules |
patch_touches_git | any header names .git as a path part, in any case |
patch_bad_path | a header path that is absolute, climbs with .. or is quoted |
patch_does_not_apply | it does not apply to the default branch's head |
A private, archived, sealed or mirrored repository answers not_found. Three
offers a minute from one source, ten a minute to one repository, thirty to the
forge (429); a repository holds at most 20 open offers (429 queue_full).
The patch is applied only to a scratch index (src/git/patch_files.ts: the
text goes on stdin, never in an argument), and its headers are read first
(patchHeaderRefusal in src/actions/offer.ts): on any doubt, refuse.
The receipt
The 202 answer carries receipt (128 random bits, hex) and status, the URL
GET /api/v1/offers/{receipt}. It answers { receipt, state, reason } and
nothing else: state is received, under review (a review exists),
landed or declined, and reason is one fixed sentence for it
(src/core/offer_receipt.ts). An id never given is 404. The MCP offer
tool returns the same fields, and offer with { receipt } reads the state.