GitHub Actions
Validate, dry-run, sync, and publish docs from GitHub Actions.
GitHub Actions
The recommended CI workflow validates docs on every docs change, dry-runs signed syncs on pull requests, and syncs or publishes from main.
Recommended OIDC Workflow
Use GitHub OIDC when the docs workflow runs in GitHub Actions. It avoids a long-lived private key secret.
Required permission:
1permissions:2 id-token: write3 contents: readRequired secret or environment value:
DOCS_SYNC_ENDPOINT
Create a docs set whose slug matches the CLI source and add a Trusted GitHub owner in Payload Admin. The docs set branch remains the normal publishing boundary. Advanced workflow refs are optional and disabled by default.
Ed25519 Secrets
DOCS_SYNC_ENDPOINTDOCS_SYNC_PRIVATE_KEY
Use these only for the Ed25519 workflow. The matching docs set must have the
public key configured under the same key id in Docs Globals > Keys.
Workflow Example
See examples/github-actions/publish-docs.yml in this repository.
Important commands:
1pnpm exec payload-markdown-docs validate --source main-docsMain-branch sync defaults to sync mode:
1pnpm exec payload-markdown-docs push \2 --endpoint "$DOCS_SYNC_ENDPOINT" \3 --source main-docs \4 --github-oidcPull request dry-run is explicit:
1pnpm exec payload-markdown-docs push \2 --endpoint "$DOCS_SYNC_ENDPOINT" \3 --source main-docs \4 --github-oidc \5 --dry-run1pnpm exec payload-markdown-docs push \2 --endpoint "$DOCS_SYNC_ENDPOINT" \3 --source main-docs \4 --github-oidc \5 --publishThe publish job succeeds only when the server has sync.allowWrites: true, sync.allowPublish: true, and target.enableDrafts: true.
See GitHub OIDC for docs set claim validation details. See signed push for the Ed25519 alternative.