Add WordPress Playground Preview for Pull Requests

[davidperezgar]

Description

I'd like to propose adding a WordPress Playground Preview GitHub Action to this repository so that every pull request automatically generates a live, browser-based preview of the plugin with the PR's changes applied.

This would allow contributors, reviewers, and maintainers to test PRs directly in a fully functional WordPress instance running in the browser — without needing to clone the repo, set up a local environment, or build the plugin locally.

Motivation

Plugin Check is a tool many plugin authors and reviewers rely on, and PRs often introduce changes that affect how the plugin behaves inside the WordPress admin (new checks, UI changes, output formatting, settings, etc.). Right now, reviewing those changes requires:

1. Pulling the branch locally.
2. Running composer install / npm install and any build steps.
3. Spinning up a local WordPress site.
4. Activating the plugin and manually testing the affected flow.

A Playground Preview would reduce that friction to a single click on a PR comment, which:

• Speeds up code review — maintainers can validate changes visually in seconds.
• Lowers the barrier for new contributors — anyone can verify their PR works as expected before requesting review.
• Helps QA edge cases — testers can quickly try the PR build against different plugins/themes by tweaking the Blueprint.
• Improves collaboration with non-developers — designers, documentation writers, or team members can interact with the change without a dev setup.

Proposed Implementation

WordPress Playground already provides an official GitHub Action for exactly this use case:

📖 Docs: https://wordpress.github.io/wordpress-playground/guides/github-action-pr-preview/

The action:

• Builds the plugin from the PR branch.
• Uploads the build artifact.
• Posts (or updates) a comment on the PR with a link to a Playground instance that loads the built plugin via a Blueprint.

A working reference implementation can be found here:
🔗 https://github.com/fellyph/wc-asia-plugin/blob/main/.github/workflows/pr-preview.yml

Example workflow file

A starting point for .github/workflows/pr-preview.yml would look something like:

name: Playground Preview

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.1'
          tools: composer

      - name: Install dependencies
        run: |
          composer install --no-dev --optimize-autoloader
          npm ci
          npm run build

      - name: Deploy Playground Preview
        uses: WordPress/playground-actions/preview-pr@trunk
        with:
          plugin-slug: plugin-check
          blueprint-path: .wordpress-org/blueprints/blueprint.json

Blueprint considerations

For Plugin Check specifically, the Blueprint should probably:

• Land the user on wp-admin/admin.php?page=plugin-check so the tool is immediately visible.
• Optionally pre-install a sample plugin to scan (e.g. Hello Dolly or a tiny test plugin) so the reviewer can trigger a check with one click.
• Set landingPage accordingly.

A draft Blueprint could look like:

{
  "landingPage": "/wp-admin/admin.php?page=plugin-check",
  "preferredVersions": {
    "php": "8.1",
    "wp": "latest"
  },
  "steps": [
    { "step": "login", "username": "admin", "password": "password" },
    {
      "step": "installPlugin",
      "pluginData": {
        "resource": "wordpress.org/plugins",
        "slug": "hello-dolly"
      }
    }
  ]
}

Open Questions

A few things worth discussing before implementation:

1. Blueprint location — should it live under .wordpress-org/blueprints/ (the convention used by many plugins for the Playground "Live Preview" button on WordPress.org) or somewhere else like .github/playground/?
2. Sample plugin to scan — should the Blueprint pre-install a known plugin so reviewers don't have to upload one manually? If so, which?
3. Scope of the build step — Plugin Check has both PHP (Composer) and JS (npm) dependencies. The workflow needs to run the full build pipeline so the preview reflects the actual distributable plugin, not just the source.
4. PR from forks — the action posts a comment on the PR. Permissions and pull_request_target vs pull_request trade-offs should be considered to keep things secure for PRs from forks.

References

• 📖 Playground PR Preview guide: https://wordpress.github.io/wordpress-playground/guides/github-action-pr-preview/
• 🔗 Working example: https://github.com/fellyph/wc-asia-plugin/blob/main/.github/workflows/pr-preview.yml
• 📖 Playground Blueprints: https://wordpress.github.io/wordpress-playground/blueprints/

Special thanks to @fellyph for pointing to the reference implementation that inspired this issue.