Valkyrian Labs logo

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.

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: read

Required secret or environment value:

  • DOCS_SYNC_ENDPOINT
  • PMDOCS_SOURCE: the Payload docs set slug to pass as --source

Create a docs set whose slug matches the CLI source and add a GitHub OIDC record in Docs Globals > Access. The docs set branch remains the normal publishing boundary. Advanced workflow refs are optional and disabled by default.

Ed25519 Secrets

  • DOCS_SYNC_ENDPOINT
  • DOCS_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 > Access.

Workflow Example

See examples/github-actions/publish-docs.yml in this repository.

That workflow installs pmdocs from the Valkyrian Labs Debian repository before validation or publishing, then logs pmdocs --version and pmdocs --help so the CI output proves the native CLI path is being used.

Important commands:

1pmdocs validate --source "$PMDOCS_SOURCE"

Main-branch sync defaults to sync mode:

1pmdocs push \2  --endpoint "$DOCS_SYNC_ENDPOINT" \3  --source "$PMDOCS_SOURCE" \4  --github-oidc

Pull request dry-run is explicit:

1pmdocs push \2  --endpoint "$DOCS_SYNC_ENDPOINT" \3  --source "$PMDOCS_SOURCE" \4  --github-oidc \5  --dry-run
1pmdocs push \2  --endpoint "$DOCS_SYNC_ENDPOINT" \3  --source "$PMDOCS_SOURCE" \4  --github-oidc \5  --publish

Do not omit --source in copied workflow templates. Set PMDOCS_SOURCE to the docs set slug you created in Payload Admin.

Server gates still apply

The 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.