Open a pull request (Practitioner)
write_to_repoLand finished work in a repository as a pull request: pass the files you wrote (full new contents, not diffs) and this opens a branch and a PR for the human to review and merge. Nothing is ever pushed to the default branch. Requires a SHPBL Practitioner key and the SHPBL GitHub App installed on that repository (or a one-off github_token). The caller chooses the repository — ask which one, or call list_repos first; never assume. Where things go:
Harvest output belongs under .shpbl/ in the caller's own repository — the person who asked for the run — and never in the repository that was harvested. Those are frequently not the same repository: a run may read a public open-source project, or a repository the caller merely has access to, and writing a harvest back into a source repository would be putting our output into somebody else's software. Sources a run may read: public repositories that carry a proper open-source license, the caller's own repositories, or private repositories the caller has access to. The server never reads a repository the caller has no right to read, and it never absorbs customer harvests back into the public library.
.shpbl/README.md— the index of their capability library (this tool scaffolds it when it is absent)..shpbl/<run-seal>/LEDGER.md— the folded ledger for one run..shpbl/<run-seal>/REPORT.html— the branded report, if one was produced..shpbl/<capability-name>/— a capability kept as source, one folder each..shpbl/COMPOSITES.md— your own composites: capabilities this run invented for your repository by fusing parts that did nothing alone. Record each as- <name> — <what it fuses> — <why neither part sufficed>. These are yours and stay private; SHPBL's global composites ledger is fed only by Governor-keyed published runs, so never send yours anywhere and never expect them to appear there. If the harvested repository is not the caller's own, the harvest still lands in the caller's.shpbl/and the source is named in provenance. Ask the person which of their repositories is the home for their library if it is not obvious, and stop for that answer rather than guessing. Give each kept capability a one-line contract in.shpbl/README.md, in the form- <name> — <path> — <contract>. That index is what makes the library reusable: on the next run, read it and pass those entries asown_librarytoevaluate_repo,fix_repoorrun_gauntlet, and the run will tell you which concerns you already solved before citing anything new. Those entries stay yours — they are held for the call and never stored by SHPBL. Repairs are the exception: write the repaired file at its own path, never under.shpbl/.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Your SHPBL subscription key (shpbl_mcp_…). Optional if your client sends it as the `Authorization: Bearer …` request header. | |
| kind | No | What this pull request lands. `harvest` means kept capabilities and a ledger: write them under `.shpbl/` and this scaffolds `.shpbl/README.md` as the index of their own capability library when it is missing. `foundry` means built software and its tests, landing under `.shpbl/` beside the index the same way a harvest does — only ever an artifact whose Build Intent `build_intent` authorised. `repair` means fixed files at their own paths, and nothing is scaffolded. | |
| repo | Yes | The GitHub repository to write to: `owner/repo` or a URL. | |
| files | Yes | Complete file contents to commit. For a repair, the whole fixed file — not a diff. | |
| title | Yes | Pull request title — say what the change does. | |
| branch | No | Branch to write on. Defaults to one derived from `run_id`, or `shpbl/<date>-<n>`; reusing a name appends to that PR. | |
| run_id | No | A stable id for this piece of work (a harvest run seal, a repair order id). Retrying with the same run_id lands on the same branch and updates the same pull request instead of opening a second one. Prefer this over `branch`. | |
| summary | Yes | Pull request body: the repair order, or the run seal and coverage of a harvest. Markdown. | |
| base_ref | No | Branch to open against. Defaults to the repository's default branch. | |
| github_token | No | One-off GitHub token with Contents and Pull requests write. Used for this call only and never stored. Omit it if the SHPBL GitHub App is installed. | |
| build_authorization | No | The signed build authorizations `build_intent` returned, one per artifact this pull request lands. Required when `kind` is `foundry`: the server verifies each against its own Build Intent ledger and refuses to land an artifact it never gated. |