# Add a Workflow That Deploys MkDocs Documentation on Every Push

Yes. An agent adds a workflow that builds your MkDocs site with the pinned tooling and publishes it to gh-pages on every push, not only on a release tag.

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

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

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

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

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.

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

## More MkDocs jobs

- [Add a Strict Docs Build Check to MkDocs Docs](https://getrush.ai/run/add-docs-build-check/mkdocs/)
- [Add Giscus Comments to a MkDocs Material Site](https://getrush.ai/run/add-giscus-comments/mkdocs/)
- [Add i18n to a MkDocs Site](https://getrush.ai/run/add-i18n/mkdocs/)

## The same job on other stacks

- [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/)
- [Add a GitHub Pages Deploy Workflow to an Eleventy Site](https://getrush.ai/run/add-deploy-workflow/eleventy/)

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