What the agent does
The agent reads how the book is produced before it adds a check, because here the source tree is generated. In a repository laid out like rust-lang/rfcs, book.toml sets the title, a site-url of /rfcs/, git-repository-url, heading-split-level = 0 for search, a non-runnable playground and extra-watch-dirs = ["text"]; the src/ directory mdBook reads is not committed. generate-book.py deletes any src/, symlinks every entry of text/ into it plus compiler_changes.md, lang_changes.md, libs_changes.md and README.md as introduction.md, writes SUMMARY.md with the three guideline chapters first and then every .md under text/ in sorted order, nesting the chapters of the three RFCs that have a subdirectory of the same name, and finally calls mdbook build. text/ holds 646 Markdown files, .gitignore drops book/ and src/, and triagebot.toml adds a rendered link to pull requests that touch text/.
Then it reads the only workflow. .github/workflows/deploy.yml runs on push to main alone: a build job downloads mdBook at the version in MDBOOK_VERSION, 0.5.4 with a renovate: comment so renovate.json5 bumps it monthly, runs ./generate-book.py and uploads book/ as a Pages artifact, and a deploy job with pages: write and id-token: write publishes it. An RFC pull request, which is most of the repository's traffic, is never built: a Markdown file that mdBook 0.5 refuses, a subdirectory that does not match an RFC file name, or an RFC whose symlink the generator cannot create is found when the deploy on main fails after merge.
The agent changes deploy.yml rather than adding a second workflow, so there is one pinned version for Renovate to track. It adds pull_request to the triggers, keeps the build job as it is, and gates deploy with if: github.event_name == 'push' so a pull request builds and uploads the artifact but never publishes. It adds permissions: contents: read at the top, since the file sets none, a concurrency group per ref with cancel-in-progress so repeated pushes to an RFC branch do not queue builds, and a timeout-minutes from the time the sandbox build took. The artifact upload stays on pull requests too, so a reviewer can download the rendered book of an RFC that changes page structure.
Before writing any of it the agent runs the build in its own sandbox the way the job does: downloads the same mdBook 0.5.4 tarball, runs ./generate-book.py, and checks that book/ has an HTML page per entry of text/ and that SUMMARY.md nests the three subdirectories. It records the duration, and reads the build log for warnings mdBook printed about the generated SUMMARY.md or any chapter so the pull request can say what the first run on a contributor's branch will show.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Make this mdBook build on every pull request. Read book.toml, generate-book.py, .gitignore, triagebot.toml, .github/renovate.json5 and .github/workflows/deploy.yml first. Change deploy.yml so it also runs on pull_request: keep the single build job with its pinned MDBOOK_VERSION and renovate comment, gate the deploy job so it only runs on a push to main, add contents: read permissions at the top, a concurrency group per ref with cancel-in-progress, and a timeout on the build job. Keep the Pages artifact upload on pull requests. In your sandbox, download the same mdBook version the workflow names, run ./generate-book.py, confirm book/ holds a page for every Markdown file under text/ and that SUMMARY.md nests the RFC subdirectories, record the build duration and any warnings, and open a pull request with that output. Do not change book.toml, generate-book.py or anything under text/.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request changes .github/workflows/deploy.yml and nothing else. Its description pastes the tail of the sandbox build with its duration, the count of pages under book/ against the count of files under text/, the three nested entries of the generated SUMMARY.md, and any warning mdBook printed.
The changed workflow runs on the pull request itself, so the first green check is on the change that introduced it, and the deploy job shows as skipped there. A push to main runs both jobs as before, with the same mdBook version and the same generator script.
Before merging, a reviewer decides whether the artifact upload on pull requests is worth its storage, whether the concurrency group should also cover main, and whether a failing build should block an RFC's merge or only annotate it.
Run it on every book repository
A team that keeps several mdBooks sends this body once per repository from its own server: one POST /o/{org}/sessions each, with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own workflow: a book that installs mdBook with cargo install keeps that, one with mdbook test for Rust code blocks gets that step in the build job, and one whose deploy already runs on pull requests gets no change and a note saying so.
Once the check is merged, an automation on the Project with a github trigger on workflow_run.failure and the prompt "if the failed workflow is the book build, read its log, name the file under text/ that broke it and comment on the pull request with the fix" turns a red build into a comment for the RFC author. The trigger adds the event after the prompt, and only work by an owner, member or collaborator fires it.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A workflow edit that adds a trigger looks trivial and is the kind that quietly publishes from a pull request or stops publishing from main. The agent reads the two jobs and their permissions, keeps the pinned version and its Renovate comment, and gates the deploy on the event name, then runs the generator and mdBook in its own sandbox so the pull request shows what a contributor's branch will see.
The build log, its duration and the page count stay with the run and are pasted into the pull request. The same request runs across every book a team maintains at once, each reading its own workflow.
Frequently asked questions
Why change `deploy.yml` instead of adding a `build.yml`?
Because MDBOOK_VERSION carries a renovate: comment and renovate.json5 bumps it monthly. A second workflow would need its own pin and could drift from the one that deploys. One job that runs on both events keeps the pull request build identical to the publish build.
Can a pull request now deploy the book?
No. The deploy job gets if: github.event_name == 'push', and the trigger still names main as the only branch for pushes. On a pull request the job appears as skipped, and the pages: write and id-token: write permissions are only used by that job.
Does the check validate the RFC text?
Only as far as mdBook does: that every file under text/ renders, that the generated SUMMARY.md resolves, and that the three subdirectory RFCs nest. Style, numbering and the template in 0000-template.md are for the human reviewers; the pull request lists what the build does and does not check.
Why keep the artifact upload on pull requests?
So a reviewer of an RFC with a subdirectory or unusual structure can download the rendered book from the check rather than building it locally. The description notes the storage cost and that removing the upload from pull requests is a one-line if.