# Add a GitHub Pages Deploy Workflow to an mdBook

Yes. An agent adds a GitHub Pages deploy job to your mdBook's workflow that publishes the built book and its translations after the tests pass, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-deploy-workflow/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 already built in CI before adding a deploy, because the deploy should publish exactly what the tests checked. In a book laid out like rust-lang/rust-by-example, `book.toml` names the title, turns on the editable playground and folding, sets `git-repository-url`, an `edit-url-template` and `hash-files = true` under `[output.html]`, adds `theme/css/language-picker.css`, sets `edition = "2021"` under `[rust]`, watches `po/` and declares an optional `gettext` preprocessor that runs after `links`. `.github/workflows/rbe.yml` is one `test` job on push and pull request with `LANGUAGES: ja zh es ko` and `MDBOOK_VERSION: 0.5.1` in its env: it checks out with `fetch-depth: 0`, installs nightly Rust with `rust-docs`, downloads the pinned `mdbook` tarball into `bin`, runs `cargo install mdbook-i18n-helpers --locked --version 0.4.0`, then `mdbook test` and `mdbook build`, fetches `linkcheck.sh` from the rust-lang/rust repository and runs it with `--all`, builds each translation with `MDBOOK_BOOK__LANGUAGE=$po_lang mdbook build -d book/$po_lang`, link-checks each, and uploads `book` as an artifact named `rust-by-example` with `actions/upload-artifact@v4`.

The translations shape the deploy. `po/` holds `es.po`, `ja.po`, `ko.po` and `zh.po`, and `theme/head.hbs` injects a language picker that links each language to `${path_to_root}${lang}/${path}`, English to the root, and sends a `HEAD` request to each target to hide languages whose page is not deployed; the workflow's comment points at `index.hbs` for that picker, but the file is `head.hbs`. So a deploy that publishes the `book/` directory with `book/ja`, `book/zh`, `book/es` and `book/ko` inside it, exactly as the `test` job lays them out, makes every picker entry resolve. `.gitignore` excludes `book`, and the README says the upstream book is published at `doc.rust-lang.org/rust-by-example` by the Rust project's own tooling, so this workflow is for a fork or for a book that uses the same layout and hosts itself.

The agent changes `rbe.yml` in two places. In the `test` job it replaces `actions/upload-artifact@v4` with `actions/upload-pages-artifact@v5`, pointing at `book`, so the artifact the tests produced is already in the shape `deploy-pages` consumes; the job still runs on pull requests, where the artifact is simply never deployed. It adds a `deploy` job with `needs: test`, an `if` that limits it to pushes to the default branch, `permissions` of `pages: write` and `id-token: write`, a `github-pages` environment whose `url` reads the deployment output, a `concurrency` group named `pages` with `cancel-in-progress: false`, and two steps: `actions/configure-pages@v6` and `actions/deploy-pages@v5`. The job needs no Rust and no mdBook, since it deploys what `test` uploaded. For a book served at a project path such as `/<repo>/` rather than at the root of a user site, the agent adds `site-url` under `[output.html]` in `book.toml` so mdBook's 404 page and its absolute links point under the prefix, and leaves it out for a root site; the pull request says which case it chose and why.

To prove the build side, the agent installs mdBook 0.5.1 from the same release tarball the workflow uses and `mdbook-i18n-helpers` 0.4.0, runs `mdbook test` and `mdbook build`, builds the four translations into `book/<lang>`, and serves `book/` with `python3 -m http.server` to open the language picker on a page and follow each entry to its translated copy, which is the check `head.hbs`'s `HEAD` requests perform in a browser. It runs `actionlint` on the edited workflow. The deploy itself needs a push to the default branch and a repository whose Pages source is set to GitHub Actions, neither of which a pull request can do, so the pull request names that one-time setting and says what the first deploy will show.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a GitHub Pages deploy to this mdBook's workflow. Read book.toml, .github/workflows/rbe.yml, README.md, theme/head.hbs and the po/ directory first, and note how the test job builds the English book and each translation into book/<lang>. In the test job, replace the plain artifact upload of book with actions/upload-pages-artifact. Add a deploy job that needs test, runs only on pushes to the default branch, has pages write and id-token write permissions, a github-pages environment with the deployment URL, a pages concurrency group that does not cancel in progress, and runs actions/configure-pages then actions/deploy-pages. Decide from the repository name whether the book is served at a project path and add site-url under output.html in book.toml only if it is, explaining the choice. Install the mdbook version the workflow pins and mdbook-i18n-helpers at the pinned version, run mdbook test, build the English book and every translation into book/<lang>, serve book/ locally and check the language picker links resolve, and run actionlint on the workflow. Open a pull request that names the one-time Pages source setting the repository needs.",
  "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/rbe.yml` and, for a project-path site, one line of `book.toml`. Its description shows the `mdbook test` and `mdbook build` output for English and the four translations, the language picker check against the served `book/` directory, the `actionlint` result, and the setting a maintainer flips under the repository's Pages settings before the first deploy.

On the pull request, the `CI` workflow's `test` job runs as before through the link checks and now uploads a Pages artifact; the `deploy` job is skipped by its branch condition, which is visible in the run summary. After the merge, the first push to the default branch runs `deploy` and the environment shows the published URL.

Before merging, a reviewer confirms the Pages source is set to GitHub Actions, decides whether the book should deploy on every push or only on tags, and checks that the `site-url` decision matches where the book will live, since a wrong prefix breaks the 404 page and nothing else until someone follows a bad link.

## Run it on every mdBook that is published by hand

A team with several mdBooks starts one run per repository from its own server: a `POST /o/{org}/sessions` each, with this prompt as `input`, the 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. `GET /o/{org}/github` lists every repository the Rush GitHub App installation reaches, so the script can pick the ones with a `book.toml` and no `deploy-pages` step. Each run reads its own workflow, so a book with no translations gets a deploy of the plain `book/` directory, and one that builds with `mdbook build -d docs` gets that path uploaded instead.

A team that tracks documentation work in Linear runs the same prompt from an automation in the Project with a `linear` trigger on issues labelled `docs`. The trigger adds the issue after the prompt, so an issue that names the custom domain the book should answer on, or asks for deploys on tags only, reaches the agent with that instruction, and the pull request links back to it.

## Why run it on Rush?

The risk in a deploy workflow is publishing something other than what the tests built: a book without its translations, a prefix that breaks the 404 page, a job that runs on pull requests. The agent builds the book and every translation in its own sandbox with the exact mdBook and helper versions the workflow pins, serves the result and follows the language picker, and keeps that output with the run, so the reviewer sees the directory layout the deploy will publish.

Nightly Rust, a pinned mdBook tarball and a `cargo install` are setup nobody wants on a laptop for a workflow change, and the same prompt runs across every book at once, each in its own sandbox with its own pull request.

## Frequently asked questions

### What if my book is served at a project path?

A repository published as a project site lives under `https://<owner>.github.io/<repo>/`, and mdBook needs `site-url = "/<repo>/"` under `[output.html]` for its 404 page and absolute links to point there. A user or organization site at the root needs nothing. The agent decides from the repository name and says which it chose in the pull request.

### Are the translations deployed?

Yes. The `test` job already builds each language in `po/` into `book/<lang>`, and the Pages artifact is the whole `book` directory, so `/ja/`, `/zh/`, `/es/` and `/ko/` are published beside the English pages. The picker in `theme/head.hbs` checks each target with a `HEAD` request and hides any language that is missing, so a translation dropped from `LANGUAGES` disappears from the menu rather than linking to a 404.

### Why deploy the artifact the tests built instead of rebuilding?

Because the `test` job has already run `mdbook test`, built every language and link-checked them; a second build in the deploy job could differ from the one that passed. The deploy job needs no toolchain, only the two Pages actions, and it runs only after `test` succeeds on the default branch.

### What must be set in the repository first?

Under the repository's Pages settings, the source has to be GitHub Actions rather than a branch, once, by a maintainer. Until then `deploy-pages` fails with a message saying so. The pull request names the setting; a workflow cannot change it.

### Will pull requests deploy?

No. The `deploy` job's condition checks for a push to the default branch, so on a pull request the `test` job runs, uploads the artifact, and `deploy` is skipped. The artifact is still downloadable from the run for reviewers who want to open the built book.

## More mdBook jobs

- [Build an mdBook on Every Pull Request Before It Deploys](https://getrush.ai/run/add-docs-build-check/mdbook/)
- [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/)

## The same job on other stacks

- [Add a Workflow That Deploys MkDocs Documentation on Every Push](https://getrush.ai/run/add-deploy-workflow/mkdocs/)
- [Add a GitHub Pages Deploy Workflow to a Pelican Site](https://getrush.ai/run/add-deploy-workflow/pelican/)
- [Add a GitHub Pages Deploy Workflow to a Starlight Docs Site](https://getrush.ai/run/add-deploy-workflow/starlight/)

## 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/)
