Sync Config

Sync behavior is server-owned.

Write Gate

1sync: {2  allowWrites: true,3}

Without allowWrites: true, mode: "sync" is rejected.

Auth Is Separate

sync controls whether accepted requests may write or publish. auth controls whether a request is accepted.

Supported auth modes:

• ed25519 for signed requests with docs-set public keys.
• github-oidc for GitHub Actions workflows with docs-set repository/ref allowlists.

See GitHub OIDC and signed push.

Publish Gate

1target: {2  type: 'docsCollection',3  enableDrafts: true,4},5sync: {6  allowPublish: true,7}

Publishing requires both a draft-enabled dedicated docs collection and allowPublish: true. When --publish is not requested, synced generated docs are written as drafts.

Cache Revalidation

After a successful sync, the endpoint attempts to revalidate generated docs paths, synced asset routes, and common docs sitemap tags through next/cache. This keeps production App Router pages from serving stale generated docs or raw AI assets after push --publish.

Disable path revalidation or provide app-specific tags when needed.

1sync: {2  allowWrites: true,3  allowPublish: true,4  revalidate: {5    paths: true,6    tags: ['payload-markdown-docs', 'sitemap', 'sitemap:docs'],7  },8}

Use revalidate: false only when the app handles docs cache invalidation elsewhere.

Delete Behavior

deleteBehavior can be:

• archive
• ignore
• draft
• delete

Hard delete requires allowHardDelete: true.