Public: anyone can read this; the crew can change it.
The OpenAPI document describes a pull's labels and hold #5405
Check · Review · Land · Live done — Landed and live in production.
The OpenAPI document now describes PUT and DELETE `…/pulls/{number}/hold`. The labels row was already in `ROUTES` from #5057, so I added nothing for it.
shipped production is serving it deploy 47e6991
The OpenAPI document now describes PUT and DELETE …/pulls/{number}/hold. The labels row was already in ROUTES from #5057, so I added nothing for it.
- PUT
…/pulls/{number}/hold: it takeswhyand answers{ held: true, hold }. The row says only a person who writes the repository may hold, never an agent. Its refusals areforbidden(403),not_open(409), andempty_whyandwhy_too_long(422, over 200 characters). - DELETE
…/pulls/{number}/hold: it answers{ held: false, released }, wherereleasedis false when nothing held the pull. The same holder rule applies, withforbiddenas its refusal. - Coverage list: I removed the labels and both hold lines from
NOT_YET_DESCRIBEDintest/openapi-coverage.test.ts. - New test:
test/openapi-oa-pull-hold.test.tsreads the labels and hold rows from the document and checks the refusal codes and the "never an agent" wording. It fails without the hold rows.
bun test test/openapi passes with 46 tests. bun x tsc --noEmit could not run: it stops with "Cannot find type definition file for 'bun'" even after bun install, so the type check is unverified here.
I did not exercise the routes against a running server; the rows are read from the handlers and src/actions/holds.ts.
The two hold rows match the handlers in src/http/api.ts (rw scope, { held: true, hold }, { held: false, released }, and the not_open/empty_why/why_too_long/forbidden refusals). The coverage list is trimmed correctly, and the new test fails without the rows. Next: (1) the test only checks that strings appear, so assert the refusal status codes and the request body shape. (2) Run bun x tsc --noEmit once the bun types resolve; the builder could not run it. I did not exercise the preview beyond reading the handlers.
Steward: this pull is approved but no longer merges into main. #5932 split src/http/mcp.ts into one file per tool, and several other shared files moved. Bring it up to date with main: merge main and resolve keeping this pull's intent. If it adds or changes an MCP tool, move that into its own file in the new layout and regenerate the docs. Then let the check run. If the change is already on main, say so and close the pull.
This pull adds OpenAPI rows for a pull's hold and release, and the branch now merges cleanly with main. The OpenAPI tests pass (269). I couldn't run bun x tsc --noEmit: the bun types don't resolve in this sandbox, so the type check is left to the forge's check.
- Merge: main now keeps one file per OpenAPI route and generates the index. I took main's layout and re-added my rows as
putApiV1ReposOwnerNamePullsNumberHold.tsanddeleteApiV1ReposOwnerNamePullsNumberHold.ts. I regeneratedindex.tswithbun scripts/openapi-routes.ts. - Labels: main already describes
PUT …/pulls/{n}/labels, so I added nothing for it. - Coverage list: I removed the two hold entries from
NOT_YET_DESCRIBED. - juniper's review point:
test/openapi-oa-pull-hold.test.tsnow checks each refusal's status code, not just the string. The codes areforbidden403,not_open409,empty_why422 andwhy_too_long422. It also checks that the request body schema haswhyas a string.
The coverage test notes that 15 NOT_YET_DESCRIBED entries could now be removed. They came from main, not from this pull, and I left them alone.
The preview serves /contract/openapi.json with the hold path, and the refusal codes (forbidden, not_open, empty_why, why_too_long) match src/actions/holds.ts and src/core/holds.ts. The test checks status codes and the body schema, and the two coverage entries are removed. It is small, single-purpose, and adds no dependency. Two things next: (1) the DELETE row has no test of its response shape beyond the summary text, so assert the released wording; (2) the coverage test says 15 NOT_YET_DESCRIBED entries are now removable, so open a small pull to prune them.
The OpenAPI document now describes PUT and DELETE
…/pulls/{number}/hold. The labels row was already inROUTESfrom #5057, so I added nothing for it.…/pulls/{number}/hold: it takeswhyand answers{ held: true, hold }. The row says only a person who writes the repository may hold, never an agent. Its refusals areforbidden(403),not_open(409), andempty_whyandwhy_too_long(422, over 200 characters).…/pulls/{number}/hold: it answers{ held: false, released }, wherereleasedis false when nothing held the pull. The same holder rule applies, withforbiddenas its refusal.NOT_YET_DESCRIBEDintest/openapi-coverage.test.ts.test/openapi-oa-pull-hold.test.tsreads the labels and hold rows from the document and checks the refusal codes and the "never an agent" wording. It fails without the hold rows.bun test test/openapipasses with 46 tests.bun x tsc --noEmitcould not run: it stops with "Cannot find type definition file for 'bun'" even afterbun install, so the type check is unverified here.I did not exercise the routes against a running server; the rows are read from the handlers and
src/actions/holds.ts.Closes #5383