v4 keeps the direct action and reusable build/publish setup, with stricter artifact handling and clearer template behavior.

Upgrade

For a direct action, change:

- uses: WordPress/action-wp-playground-pr-preview@v3

to:

- uses: WordPress/action-wp-playground-pr-preview@v4

For built previews, update both reusable workflow references:

uses: WordPress/action-wp-playground-pr-preview/.github/workflows/preview-build.yml@v4

uses: WordPress/action-wp-playground-pr-preview/.github/workflows/preview-publish.yml@v4

Keep the publish caller on your default branch. Existing inputs and build commands still apply.

Behavior changes

• PR and repository template values render as literal text. Put PR_* and REPO_* placeholders outside Markdown code spans or fences. For example, change **Branch:** `{{PR_HEAD_REF}}` to **Branch:** {{PR_HEAD_REF}}.
• Comment mode reuses only comments written by the account behind github-token. Changing that account creates a new comment. Failed account lookups stop the update.
• Artifact bundles must contain ordinary files and directories, not links or special files. The legacy helper extracts only the requested artifact-filename into a temporary directory, rather than unpacking the whole bundle into the caller's workspace.
• Legacy callers must provide a source run and PR that agree on repository, branch, and current head commit. Use the source run's head_sha, positive unpadded IDs, and a PR number obtained from GitHub's event or API. Stale or mismatched runs fail before changing release assets. The token needs actions: read and pull-requests: read in the source repository and contents: write in the release repository.
• The reusable publisher uses one PR-number spelling for uploads and cleanup: 007 becomes 7. Existing assets are not renamed.

Documentation

The README covers token placement, current Blueprint examples, ZIP layouts, v3 migration, and legacy source-run lookup. Example repository names retain v3 so existing links keep working.

See the upgrade guide. Upgrading to v4 requires updating your workflow references.

Changes: #94, #95.

This v3 patch adds an upgrade warning with a link to the v4 migration guide.

• The direct action, reusable build and publish workflows, and legacy artifact helper emit the warning.
• The warning does not fail a job. Existing v3 preview behavior is unchanged.
• For built previews, update both workflow references when moving to v4.
• Older commit pins do not receive the warning. The v2, v4, and v4.0.0 tags are unchanged.
• No v3 support end date has been announced.

Changes: #97.

v3 is deprecated. The v3 tag now includes the warning-only v3.0.1 patch. Preview behavior is unchanged. Follow the v4 upgrade guide. No support end date has been announced.

Adds fork-safe reusable workflows for build-step WordPress Playground PR previews.\n\n- preview-build.yml builds and bundles one or more plugin/theme zips from pull_request runs.\n- preview-publish.yml publishes successful workflow_run artifacts to public release URLs and posts the Preview button.\n- README documents v3 quick starts, fork-safety, live same-repo and fork examples, Plugin Check-style usage, and migration notes.\n- Fixes release asset cleanup to sort by the GitHub CLI createdAt field.\n\nThe v2 tag remains unchanged for existing users.

"Try it in Playground" GitHub Workflow for WordPress

This workflow automatically adds a "Try it in Playground" button to your pull requests, enabling easy testing and feedback for WordPress plugins and themes.

Usage

Say you're developing a plugin called my-awesome-plugin and your source code lives in the repository root. Even though this workflow supports testing CI artifacts, for now assume your plugin doesn't have a build step.

To enable the "Try it in Playground" button, create a .github/workflows/pr-preview.yml file in your repository with the following content:

name: PR Preview
on:
  pull_request:
    types: [opened, synchronize, reopened, edited]

jobs:
  preview:
    permissions:
      contents: read
      pull-requests: write
    uses: WordPress/action-wp-playground-pr-preview@v2
    with:
      # "append-to-description"  – add the button to the PR description
      # "comment"           – create a new comment with the preview button
      mode: "append-to-description"
    
      # Use "." if plugin is in repository root
      plugin-path: .

Examples

Plugin repository without a CI build process

See the usage example above. You may also want to inspect a live repository that uses this action: adamziel/preview-in-playground-button-plugin-example.

Plugin or theme repository with a CI build process

See the preview-in-playground-button-built-artifact-example section below for an example of how to test built artifacts in WordPress Playground.

Theme repository without a CI build process

name: PR Preview
on:
  pull_request:
    types: [opened, synchronize, reopened, edited]

jobs:
  preview:
    permissions:
      contents: read
      pull-requests: write
    uses: WordPress/action-wp-playground-pr-preview@v2
    with:
    # Use "." if theme is in repository root
      theme-path: .

Plugin in a subdirectory

If your plugin lives in plugins/my-awesome-plugin/:

with:
  plugin-path: plugins/my-awesome-plugin

Post as comment instead of updating description

with:
  plugin-path: .
  mode: comment

Custom Blueprint

For advanced configurations, you can provide a custom blueprint:

name: PR Playground Preview
on:
  pull_request:
    types: [opened, synchronize, reopened, edited]

jobs:
  create-blueprint:
    name: Create Blueprint
    runs-on: ubuntu-latest
    outputs:
      blueprint: ${{ steps.blueprint.outputs.result }}
    steps:
      - name: Create Blueprint
        id: blueprint
        uses: actions/github-script@v7
        with:
          script: |
            const blueprint = {
              steps: [
                {
                  step: "installPlugin",
                  pluginData: {
                    resource: "git:directory",
                    url: `https://github.com/${context.repo.owner}/${context.repo.repo}.git`,
                    ref: context.payload.pull_request.head.ref,
                    path: "/"
                  }
                },
                {
                  "step": "installPlugin",
                  "pluginData": {
                    "resource": "wordpress.org/plugins",
                    "slug": "woocommerce"
                  }
                }
              ]
            };
            return JSON.stringify(blueprint);
          result-encoding: string

  playground-preview:
    name: Post Playground Preview Button
    needs: create-blueprint
    permissions:
      contents: read
      pull-requests: write
    uses: WordPress/action-wp-playground-pr-preview@v2
    with:
      blueprint: ${{ needs.create-blueprint.outputs.blueprint }}

External Blueprint URL

Already hosting your blueprint JSON elsewhere? Provide a blueprint-url input pointing to that file:

with:
  mode: append-to-description
  blueprint-url: https://example.com/path/to/blueprint.json

When blueprint-url is set, you can omit plugin-path, theme-path, and blueprint—the action links directly to the remote blueprint via ?blueprint-url=....

Customize the preview button/comment

Customize the preview button appearance:

with:
  plugin-path: .
  description-template: |
    ### Test this PR in WordPress Playground

    {{PLAYGROUND_BUTTON}}

    **Branch:** {{PR_HEAD_REF}}
    **Testing:** Plugin `{{PLUGIN_SLUG}}`

Or customize comment format:

with:
  mode: comment
  comment-template: |
    ## Preview Changes in WordPress Playground

    {{PLAYGROUND_BUTTON}}

    ### Testing Instructions
    1. Click the button above to open Playground
    2. Navigate to Plugins → Installed Plugins
    3. Verify that `{{PLUGIN_SLUG}}` is active
    4. Test the new functionality

    **PR:** #{{PR_NUMBER}} - {{PR_TITLE}}

Usage in other repositories

• WordPress/blueprints: CI workflow, Sample PR
• adamziel/preview-in-playground-button-plugin-example: CI workflow, Sample PR
• adamziel/preview-in-playground-button-built-artifact-example: CI workflow, Sample PR

Inputs

mode

Optional How to publish the preview button.

Accepted values:

• append-to-description (default) – Automatically updates the PR description with a managed block containing the preview button. The block is wrapped in HTML comment markers (<!-- wp-playground-preview:start --> and <!-- wp-playground-preview:end -->) so it can be updated on subsequent workflow runs.
• comment – Posts the preview button as a PR comment. Updates the same comment on subsequent runs rather than creating duplicates.

Default: append-to-description

playground-host

Optional Base WordPress Playground host URL used to build the preview link.

The workflow appends blueprint parameters to this URL to create the final preview link.

Default: https://playground.wordpress.net

blueprint

Optional Custom WordPress Blueprint as a JSON string.

When provided, this blueprint is used as-is and the plugin-path and theme-path inputs are ignored. If omitted, the workflow automatically generates a blueprint based on plugin-path or theme-path.

The blueprint must be a complete, ready-to-use JSON object (not a template). It will be URL-encoded and passed to Playground via the blueprint-url parameter.

Learn more about blueprints: https://wordpress.github.io/wordpress-playground/blueprints/

Example (custom blueprint with specific WordPress version):

with:
  blueprint: |
    {
      "$schema": "https://playground.wordpress.net/blueprint-schema.json",
      "preferredVersions": {
        "php": "8.3",
        "wp": "6.4"
      },
      "steps": [
        {
          "step": "installPlugin",
          "pluginData": {
            "resource": "git:directory",
            "url": "https://github.com/owner/repo.git",
            "ref": "feature-branch",
            "path": "my-plugin"
          },
          "options": { "activate": true }
        }
      ]
    }

plugin-path

Optional Installs and activates a plugin from a path inside the repository.

This is a shortcut for plugins that don't need any bundling and can be installed directly from the repository.

The path string should point to a directory containing a valid WordPress plugin with a main plugin file.

This option is ignored if the blueprint input is provided.

Example (plugin in repository root):

with:
  plugin-path: .

Example (plugin in subdirectory):

with:
  plugin-path: plugins/my-awesome-plugin

theme-path

Optional Installs and activates a theme from a path inside the repository.

The path string should point to a directory containing a valid WordPress theme with a style.css file.

This option is ignored if the blueprint input is provided.

Example (theme in repository root):

with:
  theme-path: .

Example (theme in subdirectory):

with:
  theme-path: themes/my-cool-theme

Example (testing theme + plugin):

with:
  plugin-path: plugins/my-plugin
  theme-path: themes/my-theme

description-template

Optional Custom markdown/HTML template for the content added to PR descriptions (only used in append-to-description mode).

The template supports variable interpolation using {{VARIABLE_NAME}} syntax (case-insensitive). The rendered content will be wrapped in HTML comment markers so it can be updated on subsequent runs.

Available template variables:

• {{PLAYGROUND_BUTTON}} - Rendered preview button HTML (recommended to include)
• {{PLAYGROUND_URL}} - Full URL to the Playground preview
• {{PLAYGROUND_BUTTON_IMAGE_URL}} - URL to the button image
• {{PLAYGROUND_BLUEPRINT_JSON}} - Complete bluepri...