Deployment

Audience: maintainers publishing docs and configuring CI.

Documentation site (mdbook → Cloudflare Pages)

Castellan docs are built with mdbook from book/ and deployed on every push to main that touches book/, docs/, or .github/workflows/docs.yml.

Environment	URL
Production	`https://castellan-docs.pages.dev`
Cloudflare Pages	`https://castellan-docs.pages.dev`

Local build

./scripts/build-docs-site.sh   # canonical — installs mdbook, mermaid, llms.txt, sitemap
# or manually:
cargo install mdbook mdbook-mermaid --locked   # once
mdbook build book
open book/book/index.html

Live preview:

mdbook serve book --open

./scripts/verify.sh runs scripts/smoke-docs.sh, which includes mdbook build book.

CLI help snapshots

When CLI flags or subcommands change intentionally:

UPDATE_SNAPSHOTS=1 cargo test -p castellan-cli cli_help_snapshot

verify.sh runs cli_help_snapshot tests (BL-014). MCP tool names must appear in MCP tools — enforced by scripts/check-mcp-doc-parity.sh (BL-015).

CI workflow

Workflow: .github/workflows/docs.yml

Install Rust toolchain and mdbook
./scripts/build-docs-site.sh → output in book/book/
cloudflare/wrangler-action uploads book/book/ to Pages project castellan-docs

Model A (canonical): GitHub Actions direct upload — not Cloudflare Git integration. Keep CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID in GitHub secrets.

gh workflow run docs.yml   # manual deploy

Cloudflare Workers Builds (dashboard)

Production health = GitHub Actions → Deploy Docs, not the Cloudflare Workers Builds list. If the dashboard is red with “build token … deleted or rolled” while https://castellan-docs.pages.dev returns 200 and Deploy Docs is green, production is fine — disconnect Model B.

Symptom	Cause	Fix (operator)
Build token deleted/rolled	Stale dashboard Git / Workers Builds token	Disconnect Git: Dashboard → Workers & Pages → `castellan-docs` → Settings → Builds → Disconnect, or run Actions → Disconnect CF Workers Builds
Build command fails	Dashboard Git expects a build we do not use	Same — disconnect; rely on Model A (`docs.yml` + `wrangler-action`)
Wrong build command	Dashboard runs incomplete build	Do not “fix” Model B; keep GitHub Actions as the only publisher

Automated in-repo: scripts/build-docs-site.sh, .github/workflows/docs.yml (Model A), .github/workflows/cf-builds-disconnect.yml (silence Model B). Root wrangler.toml is optional local assets config — it must not be paired with a connected Git repo in the dashboard.

Operator checklist:

Confirm CLOUDFLARE_API_TOKEN has Account → Cloudflare Pages → Edit (Model A)
Confirm CLOUDFLARE_ACCOUNT_ID is the 32-char account ID (sidebar), not a zone ID
Disconnect Workers Builds Git so only docs.yml deploys (workflow above, or dashboard Disconnect)
Re-create the GitHub API token if docs.yml deploy returns HTTP 403 — do not confuse that with the dashboard build token

Required GitHub secrets

Secret	Description
`CLOUDFLARE_API_TOKEN`	Account Settings Read + Cloudflare Pages Edit
`CLOUDFLARE_ACCOUNT_ID`	32-char account ID from dashboard sidebar — not a zone ID

Troubleshooting

Symptom	Fix
Deploy 403	Token lacks Pages Edit for target account
Wrong account ID	Copy from Workers & Pages sidebar, not zone overview
Dashboard build token error	Disconnect Git builds; use Model A CI upload only; see Workers Builds table above

Application / CLI releases

The Castellan CLI is not yet published to crates.io (API still moving). Install from source:

cargo install --path crates/castellan-cli --locked

Semver tags and CI

Step	Command / workflow
Local verify	`./scripts/verify.sh`
Release prep (dry-run publish)	`./scripts/release-prep.sh [version]`
Tag push	`git tag -a v0.1.0 -m "Release v0.1.0" && git push origin v0.1.0`
GitHub Release	`.github/workflows/release.yml` — verify, artifact upload, changelog body

MSRV: rust-version = "1.75" in root Cargo.toml. Release workflow pins toolchain 1.75.

Changelog: CHANGELOG.md (Keep a Changelog format).

CI runs ./scripts/verify.sh on every PR and push to main.

Keyboard shortcuts

Castellan