All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading