Outside agents: a contribute token with no account (#12012)

An agent with its own sandbox (Codex cloud, Jules, Claude Code, Cursor) contributes by clone and push. It needs no account and spawns no forge.

The owner says yes first. On a repository's settings page, Outside agents › Allow outside agents. Only a public, original, unarchived repository takes them. The same list shows each live token (agent, claimed origin, expiry, last use) with Revoke, after a confirm. The terminal has the same screen (palette: Outside agents, a repository's admins only): a allows or stops allowing, x revokes after a confirm; each write is an event, so an open settings page follows it.

The agent asks for a token.

POST /api/v1/contribute   {"agent": "codex", "repo": "owner/name", "origin": "codex cloud"}

or the MCP start tool with action: "contribute" (same arguments). The answer, shown once, holds the token, git.push (a push URL for HEAD:contrib/<agent>/<segment>/<topic>) and expiresAt.

What runs, and what it holds. The code on a contrib/ branch is an outside agent's, whoever opens the pull, so the pull is a guest's (src/origins/guest.ts). Its check runs at once, with nobody's permission: green or red in minutes, read at the checks (plain text) URL the push prints. That is safe for what a check is: a cell holding no variable, no token and no secret, reaching the registry and the hosts main's forge.json declares, within main's limits (the branch's own egress and check.limits are not used until the pull lands, as for every pull, and for this one the list is enforced whatever the forge's egress setting; src/checks/held.ts, src/checks/outside.ts). Its check is queued behind every other check: while the owner's or the crew's work is queued, that runs first (src/checks/outside_lane.ts, and once the pull is approved it is the repository's like any pull's). No preview is deployed from its branch until a person who can write approves the pull (the same once-per-pull approval a guest's fork takes); after the approval the preview deploys as for any pull, with the app's settings. The pull page says one line to a writer, "From an outside contributor: approve to deploy its preview, with this app's settings.", with Approve. A crew reviewer's approval of the pull records the same approval (approveGuestPull), so it releases the preview too. On a machine that cannot hold a cell, an unapproved outside pull's check fails with a sentence that says a writer approves the pull (Approve on its page) and then runs its checks again, rather than run a stranger's code beside the forge's own data.

The push opens the pull (#12013). A push of a new contrib/<agent>/<segment>/<topic> branch opens a pull on the default branch (the tip commit's first line is the title, its whole message the body); a later push to the branch updates that pull. While nobody has approved the pull the push also prints "checks run now, behind the owner's; the preview is deployed once a person who can write here approves the pull on its page". The push output prints, as remote: lines, the pull's URL and checks (plain text), the URL of GET /api/v1/repos/<owner>/<name>/pulls/<n>/checks?format=text (state:, head:, required:). Refused with one line: a push to the default branch or another token's branch (the line names the branches the token may push), a token past its expiry (401), a push over 5 MiB (CONTRIBUTE_PUSH_MAX_BYTES; git says "pack exceeds maximum allowed size (5.00 MiB)"), and a new branch once the token has 5 pulls open has opened 20 in a day, the agent name has opened 25, or the repository has taken 30 in a day (the line carries the number). A push that creates more new branches than the token has room to open pulls is refused whole with both numbers. Opens are serialized per token (inTurn), shared by the API and the push, with the caps read inside the turn; a branch that loses a race to a cap is still pushed and the output says no pull was opened. Code: src/actions/contribute_push.ts; test: test/contribute-push.test.ts.

Reading its own check. A token reads the plain-text check of the pulls it opened, and only those (another pull's, or an unknown one, is 403): curl -H "authorization: Bearer $TOKEN" https://<forge>/<owner>/<repo>/pulls/<n>/check.txt answers pending, green or red, head: <oid> and, on red, the last 80 lines of the log (src/http/check_text.ts). Add ?wait=S (a whole number, 1 to 120) to hold the request until the verdict changes or S seconds pass, then read the same text (a hold ends at 115 s at the longest, ahead of the server's 120 s idle limit; it wakes on run events, so a push whose check is not yet queued is seen at the next event or the limit); any other wait is a 400. At most 2 waits are held per token at once (a third is 429), and each still counts against the 120 requests a minute.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs