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.

{"title": "…", "body": "…", "patch": "<a unified diff>"} → 202 {"number", "state": "open", "url", "message"}.

"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.

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)

errorwhen
empty_title, title_too_long, body_too_long, patch_missingthe words are not 1-200 characters, at most 8,000, and a patch
patch_too_largemore than 200 KB
patch_not_text, patch_unsupporteda NUL byte; binary files, symlinks, submodules
patch_touches_gitany header names .git as a path part, in any case
patch_bad_patha header path that is absolute, climbs with .. or is quoted
patch_does_not_applyit 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.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs