Auto-deploy flow¶

From a git push to a live URL — what happens, what triggers it, and how long it takes.

The chain¶

sequenceDiagram
  autonumber
  participant Dev as Developer
  participant Repo as Component repo<br/>(e.g. rig-agent-runtime)
  participant GH as GitHub
  participant CI as rig-gitops<br/>deploy-docs.yml
  participant Build as build-docs.sh<br/>+ mkdocs build
  participant CF as Cloudflare Pages<br/>(rig-docs project)
  participant W as rig-router Worker
  participant U as Visitor

  Dev->>Repo: git push docs/<file>.md
  Repo->>GH: PR + merge to main
  Note over GH,CI: One of three triggers fires<br/>deploy-docs.yml in rig-gitops:
  GH->>CI: schedule (hourly cron)
  GH->>CI: push to rig-gitops main (docs/scripts/workflow paths)
  GH->>CI: repository_dispatch(docs-update)<br/>(future — per-repo notify workflow)
  CI->>Build: ./scripts/build-docs.sh
  Build->>GH: gh api repos/dashecorp/<repo>/contents/docs<br/>for each component
  GH-->>Build: base64-encoded markdown
  Build->>Build: decode → docs-site/docs/components/<repo>/<file>.md
  CI->>Build: mkdocs build → ../build/
  CI->>CF: wrangler pages deploy build --project-name=rig-docs
  CF-->>CI: deployment URL
  Note over W,U: Live within seconds of CF deploy completion
  U->>W: GET rig.dashecorp.com/docs/...
  W->>CF: proxy to docs.rig.dashecorp.com/...
  CF-->>U: HTML + assets

Triggers¶

Trigger	Fires when	Latency
`schedule` (cron `15 * * * *`)	Every hour at :15	up to 60 min
`push` to `rig-gitops` main	docs-site/, docs/, build-docs.sh, AGENTS.md, the workflow itself	< 2 min
`repository_dispatch(docs-update)`	A component repo's notify workflow fires it	< 2 min
`workflow_dispatch`	Manual `gh workflow run`	< 2 min

Today only the first two are wired. Per-repo notify-aggregator.yml workflows (rollout step 7) reduce the worst-case latency from "hourly" to "minutes" for any repo's doc edits.

Secrets¶

Stored as GitHub Actions repo secrets on dashecorp/rig-gitops:

Secret	Purpose	Source
`RIG_DOCS_DISPATCH_TOKEN`	Cross-repo `gh api` reads in `build-docs.sh`; also dispatches at rig-docs from `notify-rig-docs.yml`. PAT with `repo` scope.	Bitwarden — "GitHub PAT (Claude)"
`CLOUDFLARE_API_TOKEN`	`wrangler pages deploy`	Bitwarden — "Cloudflare API Token (Claude)"
`CLOUDFLARE_ACCOUNT_ID`	Same	constant `59710bf016d417f860051f1f00b00258`

SOPS_AGE_KEY (used by Flux for k8s secrets) is not required here — the docs site has no secrets at runtime; only build-time tokens.

What the build actually does¶

scripts/build-docs.sh (read top-to-bottom):

Copies rig-level docs from dashecorp/rig-gitops/docs/ into the site (architecture, guides, whitepaper, AGENTS.md).
Pulls BRAIN.md from dashecorp/rig-docs into docs-site/docs/brain.md.
Loops REPOS="rig-conductor rig-agent-runtime rig-memory-mcp rig-tools infra", fetches each repo's README.md → components/<repo>/index.md and every docs/*.md → components/<repo>/<file>.md via gh api.
Generates a small reference page (reference/repositories.md).

mkdocs build then renders the Material theme over the result.

wrangler pages deploy build --project-name=rig-docs ships it.

Failure modes seen so far¶

Symptom	Cause	Fix
`base64: invalid input` then job exits 1	An archived repo (e.g. `dev-e`) returned non-base64 content; `set -e` killed the build	dropped from REPOS; helper tolerates bad payloads
`mkdocs build --strict` failed on cross-link warnings	Legacy docs reference moved files	dropped `--strict` from CI step (link cleanup tracked separately)
Workflow ran but `wrangler` skipped	`if: github.event_name == 'push'` excluded `workflow_dispatch`	added `workflow_dispatch` to the condition

These are pinned in deploy-docs.yml so we don't regress.

Verification¶

After any merge into rig-gitops main, watch:

gh run watch --repo dashecorp/rig-gitops $(gh run list --repo dashecorp/rig-gitops --workflow=deploy-docs.yml --limit 1 --json databaseId --jq '.[0].databaseId')

Then sanity-check a known page:

curl -sI https://rig.dashecorp.com/docs/components/rig-agent-runtime/claude-oauth-token/ | head -1