GitHub OIDC

GitHub OIDC lets GitHub Actions authenticate to the sync endpoint without storing a long-lived Ed25519 private key secret.

Server Config

Enable GitHub OIDC at the plugin level:

1payloadMarkdownDocs({2  auth: {3    githubOidc: true,4  },5  target: {6    enableDrafts: true,7  },8  sync: {9    allowWrites: true,10    allowPublish: true,11  },12})

Then create records in Payload Admin:

• Docs Globals > Sets: a docs set whose slug matches the CLI source
• Docs Globals > Trusted: a trusted GitHub owner

The docs set branch is the normal publishing boundary. The token repository owner must match a Trusted owner. If limitRepos is off, any repository under that owner is trusted. If it is on, the repository must be listed.

Workflow Permissions

GitHub only exposes the OIDC token request endpoint when the workflow grants id-token: write.

1permissions:2  id-token: write3  contents: read

Push With OIDC

Sync is the default mode:

1pnpm exec payload-markdown-docs push \2  --endpoint "$DOCS_SYNC_ENDPOINT" \3  --source main-docs \4  --github-oidc

Use --dry-run for an explicit validation-only request, such as pull request checks:

1pnpm exec payload-markdown-docs push \2  --endpoint "$DOCS_SYNC_ENDPOINT" \3  --source main-docs \4  --github-oidc \5  --dry-run

Request published output separately:

1pnpm exec payload-markdown-docs push \2  --endpoint "$DOCS_SYNC_ENDPOINT" \3  --source main-docs \4  --github-oidc \5  --publish

When the docs set slug matches the repository name, omit --source in GitHub Actions and the CLI derives it from GITHUB_REPOSITORY.

Ed25519 Still Works

Ed25519 signed sync remains supported for local machines, non-GitHub CI, and workflows that prefer static key pairs. Add public keys in Docs Globals > Keys. See signed push.