WordPress to GitHub

Use WordPress-to-GitHub synchronization when an editor changes a managed Page in Gutenberg and the corresponding Markdown change should return to the repository through reviewable pull requests.

Requirements

• The same WP_ACCESS_TOKEN used for publishing; DocsPress uses it to read editable Page content.
• contents: write and pull-requests: write permissions for the workflow's GITHUB_TOKEN.
• Allow GitHub Actions to create and approve pull requests enabled under the repository's Actions settings.
• A scheduled or manually dispatched workflow, because WordPress editor saves do not directly start a GitHub workflow.

Poll WordPress and propose Markdown

Use mode: propose when this workflow should only import WordPress changes:

name: Propose WordPress documentation changeson:  schedule:    - cron: "3/5 * * * *"  workflow_dispatch:permissions:  contents: write  pull-requests: writeconcurrency:  group: docspress-sync  cancel-in-progress: falsejobs:  sync:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262      - uses: Automattic/docspress@14d318924a81fb95ce4d3aaa9c3b547bf76b7768        with:          mode: propose          wordpress-site: example.wordpress.com          wordpress-access-token: ${{ secrets.WP_ACCESS_TOKEN }}          docs-dir: docs          root-slug: docs          pull-request-base: main          pull-request-branch: docspress/wordpress-sync          dry-run: false

GitHub schedules can start later than the exact cron minute. Run workflow_dispatch when an editor needs an immediate proposal.

Review the rolling pull request

DocsPress maintains one action-owned branch, docspress/wordpress-sync, instead of opening duplicate pull requests on every poll. Each run refreshes that branch from the latest base and updates the proposal.

The pull request uses a Conventional Commits title derived from its files, such as docs(sync-and-rest-api): sync changes from WordPress. Its description names the direction, lists changed Markdown files, and explains that the branch is managed and may be refreshed.

Review the Markdown diff exactly like any other documentation change. When it is correct, merge it. Do not commit unrelated work to the managed branch.

Preserve the Markdown structure

DocsPress compares Gutenberg blocks semantically and rewrites only matching Markdown regions. Unchanged frontmatter, spacing, code-fence languages, tables, and readable block envelopes stay intact. Plain core blocks become ordinary Markdown. DocsPress blocks become semantic Markdown previews with hidden config; attributed, structural, dynamic, and unrecognized core blocks use a lossless envelope rather than exposing raw wp:* comments.

Reverse synchronization updates the title and content of an existing managed Page. WordPress-created or deleted Pages and editor changes to slug, parent, or publication status remain outside reverse-sync scope.

Combine both directions safely

Use mode: reconcile when the same workflow also has a push trigger for GitHub-to-WordPress publication. Add this condition to the sync job so merging the managed proposal does not publish the same change back to WordPress:

if: >-
  github.event_name != 'push' ||
  !contains(
    github.event.head_commit.message,
    format('from {0}/docspress/wordpress-sync', github.repository_owner)
  )

If pull-request-branch changes, use the same branch name in the condition. The Action also recognizes a managed merge internally and exits successfully with skipped=true when a caller omits the job condition.

The complete combined example lives in Keep documentation synchronized.