What the agent does
The agent first works out how the docs are built and published today. In a project laid out like encode/httpx, mkdocs.yml uses the material theme with a custom_dir of docs/overrides, sets site_url to the project's own domain, and loads mkautodoc so docs/api.md renders docstrings from the package itself; docs/CNAME names that domain so GitHub Pages serves it from the gh-pages branch. requirements.txt pins mkdocs, mkdocs-material and mkautodoc and installs the package in editable mode with its extras, because the autodoc pages import it. scripts/install runs pip install -r requirements.txt straight into the runner's Python when GITHUB_ACTIONS is set and into a venv otherwise, scripts/build runs python -m build, twine check and mkdocs build, and scripts/publish uploads to PyPI with twine and then runs mkdocs gh-deploy --force, after checking that GITHUB_REF matches the version in httpx/__version__.py.
That is the gap: .github/workflows/publish.yml runs on a tag push only, in the deploy environment on Python 3.9, so a docs fix merged to master sits unpublished until the next release. Meanwhile test-suite.yml already builds the docs on every push and pull request through scripts/build across five Python versions, so the site is known to build; nothing publishes it. .gitignore ignores site/, the build output, so the agent knows nothing rendered is committed.
The agent adds .github/workflows/docs.yml: on push to master, limited with paths to docs/**, mkdocs.yml, requirements.txt and the package directory, because the autodoc pages change when a docstring does. One job checks out, sets up the same Python 3.9 publish.yml uses, runs scripts/install, sets the git identity the way scripts/publish does, and runs mkdocs gh-deploy --force. The job gets permissions: contents: write because gh-deploy pushes a branch, and a concurrency group named for the workflow with cancel-in-progress: false, so two merges in a row deploy in order rather than racing on gh-pages. The tag-driven release path is left exactly as it is; it keeps publishing the docs on a release as well.
Before opening the pull request the agent runs the build in its sandbox with the same commands: scripts/install, then mkdocs build, and reads the output for warnings about missing pages or broken anchors and confirms site/CNAME landed in the output, which is what makes the custom domain survive a deploy. It does not run gh-deploy, because that would push to the reader's repository. It runs actionlint on the new workflow and pins the two actions to the versions the other workflows use.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a GitHub Actions workflow that publishes this MkDocs site to the gh-pages branch on every push to the default branch. Read mkdocs.yml, requirements.txt, docs/CNAME, every file under scripts and every file under .github/workflows first. Reuse scripts/install for the install step, use the same Python version publish.yml uses, set the git identity the way scripts/publish does, run mkdocs gh-deploy --force with contents write permission and a concurrency group that queues deploys instead of cancelling them, and limit the trigger with paths to the docs, mkdocs.yml, requirements.txt and the package directory the autodoc pages read. Leave publish.yml and the scripts unchanged. In the sandbox run scripts/install and mkdocs build, read the warnings, confirm the CNAME file is in the output, and run actionlint on the new workflow, but do not run gh-deploy. Open a pull request whose description quotes the build output and says what the reader checks under the repository's Pages settings.",
"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
What comes back is a pull request with one new file, .github/workflows/docs.yml, and no change to scripts/, publish.yml, mkdocs.yml or anything under docs/. The description quotes the mkdocs build output from the sandbox, including any warning MkDocs printed, notes that site/CNAME was present, and includes the actionlint result.
The run's record holds the scripts/install log with the pinned mkdocs, mkdocs-material and mkautodoc versions it resolved, the editable install of the package, and the full build log, so a reviewer can see the site builds with the workflow's commands before the workflow runs once on GitHub.
Before merging, a reviewer confirms the repository's Pages source is the gh-pages branch, which is a setting on github.com the agent cannot read or change, decides whether the paths filter should also cover CHANGELOG.md or any other file the site includes, and considers whether a docs change should wait for test-suite.yml to pass first, which would mean triggering this workflow with workflow_run instead of push.
Run it on every documentation repository
A team that keeps several MkDocs sites starts one run per repository from a script: GET /o/{org}/github lists every repository the installation reaches, the script clones each, keeps the ones with an mkdocs.yml, and sends this body with that repository in resources only where no workflow under .github/workflows/ runs mkdocs gh-deploy on a push. Each call carries a request_id that is a UUID v5 of the repository's full name, so a second pass returns the runs already started.
Each run reads its own site. One that deploys only on tags gets a push-triggered workflow beside the release one; one whose Pages source is already the Actions deployment gets actions/upload-pages-artifact and actions/deploy-pages instead of a branch push; one with no CNAME gets a workflow that passes the Pages URL as the site's base. The pull requests arrive one per site, each with its own build log in the record.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A deploy workflow written without running the build breaks on its first push in ways a green test suite hides: a plugin left out of the install so a page renders empty, a CNAME that does not reach the branch so the custom domain drops for a few minutes, or two merges pushing gh-pages at once so one deploy wins and the other fails. In a Rush sandbox the agent runs the project's own install script and the real mkdocs build, and reads what came out before it writes the workflow.
The build log stays with the run and the pull request cites it, so the reviewer reads evidence rather than a promise. A team with a dozen documentation sites starts a dozen runs at once, each with its own machine, its own log and its own pull request.
Frequently asked questions
Why keep pushing a gh-pages branch instead of using the Pages deployment actions?
Because that is how the site is published today: scripts/publish runs mkdocs gh-deploy and docs/CNAME rides along into the branch, so the custom domain keeps working without a settings change. Switching the Pages source to Actions is a reasonable later change, but it means the release path and the new workflow would publish two different ways, and the agent does not make it on its own.
Does the release still deploy the docs?
Yes. publish.yml and scripts/publish are untouched, so a tag still uploads to PyPI and runs gh-deploy after it. The new workflow only adds the pushes in between.
Why does the workflow install the package to build documentation?
mkautodoc renders docs/api.md by importing the package and reading its docstrings, and requirements.txt installs it in editable mode for that reason. Skipping the install would build a site with an empty API reference.
What stops two pushes from fighting over the branch?
The workflow's concurrency group with cancel-in-progress: false: a second push waits for the first deploy to finish and then deploys on top of it, so the branch always ends at the newest commit's site.
Can I get a preview for a pull request too?
Not from this workflow; it publishes the default branch only. Previews need a host that serves per-branch builds, and that is a separate change the pull request mentions but does not make.