# Build an mdBook on Every Pull Request Before It Deploys

Yes. An agent makes your mdBook deploy workflow build on pull requests too, with the same pinned mdBook and generator script, proves it first and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-docs-build-check/mdbook/). Opens the console with this prompt ready to send, in a Project that has your repository.

## 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`

```json
{
  "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"
    }
  ]
}
```

1. **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.
2. **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.
3. **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.

## 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`.

## More mdBook jobs

- [Add Giscus Comments to an mdBook](https://getrush.ai/run/add-giscus-comments/mdbook/)
- [Add i18n to an mdBook Site](https://getrush.ai/run/add-i18n/mdbook/)
- [Add Last Updated Dates to an mdBook Site](https://getrush.ai/run/add-last-updated-dates/mdbook/)

## The same job on other stacks

- [Add a Strict Docs Build Check to MkDocs Docs](https://getrush.ai/run/add-docs-build-check/mkdocs/)
- [Fail CI on Sphinx Warnings and Broken Links for a Python Library](https://getrush.ai/run/add-docs-build-check/python/)
- [Add a Docs Build Check for a Sphinx Site on Every Pull Request](https://getrush.ai/run/add-docs-build-check/sphinx/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
