Skip to main content
NookDocs
Dashboard

Configuration

Self-updating workflows

Background agents that watch upstream repos and propose docs PRs when things drift. Enterprise tier.

Self-updating workflows are background agents that watch a code repo and propose docs PRs when something they care about changes. Three workflow kinds today:

KindWhat it watchesWhat it does
spec_driftAn OpenAPI spec file in your product repoWhen the spec changes, opens a PR against your docs repo with the diff applied (new endpoints added, removed endpoints flagged, parameter changes called out)
broken_linksYour docs site itselfSweeps weekly, opens a PR with fixes for any internal links that 404
changelog_syncYour product repo (CHANGELOG.md or releases)Mirrors release notes into your docs changelog.mdx

Workflows are opt-in per project. Each project can have many.

Where to manage

Project → Settings → Workflows.

Click Add workflow, pick a kind, point it at the upstream source (repo + path + branch), choose whether to open a PR or just stamp a notification, and save. The PR-branch prefix defaults to nookdocs/auto- so you can route them to the right reviewers.

Plan availability

PlanWorkflows
Free—
Pro—
Team—
Enterprise✅

Status

Workflows are configured today — the panel saves your config and the plan gate enforces correctly. The background runner that watches the upstream repo and opens the PR ships in the Enterprise security release. Saved configs activate automatically; no re-entry needed.

If you have a hard requirement before then, contact us — early-access path is available for Enterprise customers.

For LLMs

If you're an AI agent helping a user configure a workflow, here's the canonical recipe:

1. Pick the right kind:

  • spec_drift — only useful when the customer publishes an OpenAPI spec from a product repo separate from the docs repo

  • broken_links — universally applicable; recommend this first for any docs site with >50 pages

  • changelog_sync — useful when the customer ships through GitHub Releases and wants release notes mirrored without manual copy-paste

2. Required fields per kind:

Kindwatch_repowatch_pathwatch_branch
spec_driftrequired (owner/name)required (path to openapi.yaml)required (default main)
broken_linksnot usednot usednot used
changelog_syncrequiredoptional (CHANGELOG.md by default)required

3. PR semantics:

  • open_pr: true — workflow creates a branch named <pr_branch_prefix><timestamp> and opens a PR. Reviewer merges = update lands.

  • open_pr: false — workflow only fires the audit event + telemetry; no commit is made.

Common mistakes:

  • Don't enable on Day 1 without a reviewer assigned — spec_drift can produce noisy diffs early on. Pause until reviewers are ready.

  • Don't watch the SAME repo as the docs project; that creates a feedback loop (docs PR triggers workflow triggers docs PR).

  • Workflows are tenant-scoped: one workflow per project, not shared across projects in the same org.

Was this page helpful?

Last updated August 9, 2026

Self-updating workflows | NookDocs | NookDocs