WordPress Playground is not a single interface. A developer may use the Playground CLICLI Command Line Interface. Terminal (Bash) in Mac, Command Prompt in Windows, or WP-CLI for WordPress. for local work, a Blueprint to describe a reproducible site, or playground.wordpress.net to create and share a browser-based demo. An AI agent needs to know which surface owns each part of a request.

PR #56 in the WordPress agent-skills repository updates the wp-playground skill around that idea. Instead of keeping CLI commands, Blueprint advice, browser links, and debugging notes in one long procedure, the skill becomes a small routing layer with focused references.

The result gives agents a clearer model of the whole Playground ecosystem. In this post, we are going to cover the main updates on the WordPress Playground agent skill, which is present in the WordPress repository. If you want an introduction post, I do recommend reading the previous post about the Playground agent skill.

What changes for Playground users

• A developer starting a pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party. locally gets the current start workflow and a check that the plugin is active.
• A reviewer receiving a demo link gets correct encoding, public hosting and CORS requirements, and a fresh-browser verification step.
• A mixed request can move from Blueprint authoring to local execution and browser sharing without one skill pretending to own every concern.

The headline benefit is consistency across surfaces: the answer changes with the workflow, while the underlying model of Playground stays coherent.

Why the previous skill reached its limit

The previous 101-line SKILL.md put local execution, Blueprint guidance, browser sharing, and debugging in one procedure. That created three failure modes:

• Browser support was too shallow to explain the Query API, persistence, or the difference between window.playgroundSites and the active window.playground client.
• Blueprint guidance existed in both wp-playground and the dedicated blueprint skill, creating two sources of truth.
• The common plugin and theme workflow still led with server --auto-mount after the Playground CLI documentation had moved the typical development loopLoop The Loop is PHP code used by WordPress to display posts. Using The Loop, WordPress processes each post to be displayed on the current page, and formats it according to how it matches specified criteria within The Loop tags. Any HTML or PHP code in the Loop will be processed on each post. https://codex.wordpress.org/The_Loop to start.

The current high-level workflow is:

cd <plugin-or-theme-root>
node -v
npx @wp-playground/cli@latest start

The server command remains useful when an agent needs explicit mounts, a disposable environment, CI behavior, or fine-grained runtime control. The important change is teaching the agent to choose, not treating one command as the answer to every local workflow.

Route by intent, then load the detail

The new wp-playground wrapper starts by classifying the request:

Mixed requests can use more than one route. For example, “write a Blueprint, run it locally, and give me a reviewer link” uses blueprint for the JSON, the CLI reference for local execution, and the website reference for sharing.

This is progressive disclosure in practice. The entry file drops from 101 to 52 lines. The complete bundle grows because it documents more capability, but an agent loads that depth only when the request needs it.

Browser sharing becomes a first-class route

The website reference distinguishes three control surfaces:

1. URL setup through Query API parameters, Blueprint fragments, and blueprint-url.
2. Browser site management through the Sites API at window.playgroundSites.
3. Runtime interaction through the JavaScript API client exposed as window.playground.

That distinction prevents several common mistakes. playgroundSites manages site records, persistence, and the active site. The Playground client reads and writes the WordPress virtual filesystem, runs PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. https://www.php.net/manual/en/index.php, makes requests, and navigates the visible site. URL parameters configure a site before it boots.

The reference also documents boundaries that matter when an agent generates a share link:

• Small inline Blueprints should be encoded once with encodeURIComponent(JSON.stringify(blueprint)).
• Larger JSON files and ZIP bundles should use ?blueprint-url=<public-url>.
• Hosted files must be public and allow cross-origin loading.
• A browser Playground cannot read an arbitrary local filesystem path.
• The final URL should be checked in a fresh browser session.

These details turn “make a Playground link” from a plausible-looking string into a repeatable handoff. The official troubleshooting guide confirms that raw JSON in a fragment, double encoding, private URLs, and missing CORS headers are frequent failure modes.

At the same time, the blueprint skill now explicitly owns Blueprint JSON and bundles, and the debugging reference replaces stale worker advice with current flags. The router can therefore choose a source before the agent starts composing an answer.

What the benchmark showed

To measure the impact, I compared three configurations:

• The new version.
• The previous skill.
• A control that answered from general model knowledge without consulting a skill.

The benchmark used the four scenarios added by the PR: CLI auto-mounting, website sharing, a mixed Blueprint/CLI/browser request, and current Blueprint schema authoring. Every configuration received the same prompts running on GPT 5.5 Sol. The two skill configurations could read only the files from their pinned revision, while the control could not read skill files or references.

On this four-scenario, 24-assertion regression suite:

Six criteria inspect the execution trace rather than the final answer. Five explicitly require the agent to use or route through a skill, so they necessarily penalize the no-skill control. Removing all six produces a cleaner comparison of answer content:

The final PR revision passed 24/24 checks: 100% on this four-scenario, 24-assertion regression suite. Only two content checks separated it from the previous skill:

• It chose npx @wp-playground/cli@latest start for the common plugin-development workflow.
• It required public, CORS-enabled hosting with Access-Control-Allow-Origin: * for Blueprint files, bundles, and referenced assets.

The Blueprint-only scenario did not distinguish answer quality; all three configurations passed its six content checks. That is evidence of preserved behavior, not improvement.

This is a focused regression suite, not a general model leaderboard. It uses one run per prompt, does not measure run-to-run variance, and grades guidance rather than live Playground execution.

Review improved the architecture

The pull request’s review history also shaped the final structure. Review feedback asked for an explicit routing procedure, top-level failure modes, stronger delegation to blueprint, and direct one-hop links from the wrapper to each reference.

The final revision removes reference-to-reference handoffs. A CLI or website reference now sends the agent back to the wrapper when the request changes direction. That keeps every focused file one hop from SKILL.md and makes the routing model easier to inspect.

Consistency across surfaces

The improvement is not merely a higher benchmark score. It is a more consistent developer experience across the CLI, Blueprints, and browser sharing. A request can move from a valid Blueprint to a local run and then to a reviewer link while each skill remains responsible for one concern.

PR #56 was merged on July 25, 2026. You can inspect the complete change set and use the four scenarios as starting points for testing real Playground tasks.

WordPress Playground is often used as a one-off browser sandbox: open a link, test a pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party., close the tab.

That is useful, but plugin and theme development usually involves more than one sandbox. You may need a clean site for reproduction, a saved site for ongoing debugging, another site pinned to a different PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. https://www.php.net/manual/en/index.php version, and a way to inspect all of them without clicking through the interface.

Recent Playground updates make those workflows easier to automate. The Playground website now makes a site management object available to JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com running on its top-level page. Code in the browser console or a browser automation tool can access it through window.playgroundSites to list and switch sites, save temporary sites, rename saved sites, change runtime settings, or get the active site’s PlaygroundClient.

This post shows how plugin and theme developers can use that APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. from the browser console to speed up real workflows.

One interface for site management

Before these updates, anything outside the Playground UIUI UI is an acronym for User Interface - the layout of the page the user interacts with. Think ‘how are they doing that’ and less about what they are doing. had to recreate site management behavior itself. MCP tools, browser-native WebMCP, DevTools experiments, and UI components all needed some way to list sites, save them, rename them, or switch the active site.

The new PlaygroundSitesAPI gives those workflows one shared interface. After the Playground website loads, JavaScript running on the page can call that interface through window.playgroundSites. This makes site management scriptable without relying on brittle UI automation.

In practical terms, you can now open DevTools and run:

window.playgroundSites.list();

The result is an array of site records:

[
  {
    slug: "quiet-river",
    name: "Quiet River",
    storage: "temporary",
    isActive: true,
  },
];

The storage field tells you whether the site is temporary, saved in browser storage, or saved to the local filesystem. Temporary sites disappear on reload unless you save them first.

The API at a glance

The workflows in this post use these coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. methods:

The API is available after Playground loads its saved sites. If window.playgroundSites is undefined, wait until the Playground UI has finished loading. Then call await window.playgroundSites.isReady() before running commands that need the active site’s client.

See the Sites API documentation for the complete reference, including methods for autosaved and explicitly saved sites.

Run the examples on the Playground website

The examples below use the Sites API on playground.wordpress.net. Open the website, wait for the Playground UI to load, open your browser’s DevTools console, and run await window.playgroundSites.isReady(). You can then paste the examples into the console. A browser automation tool such as Playwright can run the same JavaScript while it controls a tab open to the Playground website.

This API belongs to the Playground website. It is not part of the @wp-playground/client package or the Playground CLICLI Command Line Interface. Terminal (Bash) in Mac, Command Prompt in Windows, or WP-CLI for WordPress., and it is not exposed by /remote.html when you embed Playground in another application. For embedded sites and test automation that starts its own Playground client, use the JavaScript API instead.

Scenario 1: Create a clean plugin test site

When debugging a plugin issue, start with a fresh site that matches the target environment. The example below creates a temporary site using PHP 8.4, the latest WordPress release, and networking enabled:

const slug = await window.playgroundSites.createNewTemporarySite(
  "plugin-test-php-84",
  {
    phpVersion: "8.4",
    wpVersion: "latest",
    networking: true,
  }
);

console.log(`Active test site: ${slug}`);

Use this when you need a clean environment before installing a plugin or reproducing a report. The site is temporary at this point, so changes will not survive a reload.

Scenario 2: Save and rename a reproducible bug report

Once you reproduce a bug, save the site before making more changes. Saving turns a temporary site into a browser-stored site:

const saved = await window.playgroundSites.saveInBrowser(
  "Plugin compatibility test"
);

console.log(saved);

The returned object includes the site slug and storage type:

{
  slug: "plugin-test-php-84",
  storage: "opfs",
}

After saving, you can rename the active site:

await window.playgroundSites.rename(
  "Plugin compatibility test - PHP 8.4"
);

That sequence matters. rename() only works on saved sites. If you call it on a temporary site, Playground throws:

Cannot rename a temporary site. Save it first.

Scenario 3: Switch between saved test sites

When you keep separate sites for different reproduction cases, list them and switch by slug:

const sites = window.playgroundSites.list();

console.table(
  sites.map((site) => ({
    slug: site.slug,
    name: site.name,
    storage: site.storage,
    active: site.isActive,
  }))
);

To activate one:

const target = window.playgroundSites
  .list()
  .find((site) => site.name.includes("Plugin compatibility"));

if (target) {
  await window.playgroundSites.setActiveSite(target.slug);
}

setActiveSite() waits for the selected site to boot before resolving, so follow-up commands can safely assume the active site is ready.

Scenario 4: Inspect plugin state with PHP

The site management API gives you access to the active site’s PlaygroundClient. That client can run PHP inside the WordPress environment.

function phpResponseText(response) {
  return "text" in response
    ? response.text
    : new TextDecoder().decode(response.bytes);
}

await window.playgroundSites.isReady();
const client = window.playgroundSites.getClient();

if (!client) {
  throw new Error("The active Playground site has not booted yet.");
}

const response = await client.run({
  code: `<?php
require_once "/wordpress/wp-load.php";

echo json_encode([
  "php" => phpversion(),
  "wp" => get_bloginfo("version"),
  "active_plugins" => get_option("active_plugins"),
]);
`,
});

console.log(phpResponseText(response));

This lets you query plugin data in the WordPress database directly, without navigating through wp-admin. You can replace the PHP with targeted checks for options, active theme data, custom post types, or plugin-specific database rows.

For example, to inspect one option:

const response = await client.run({
  code: `<?php
require_once "/wordpress/wp-load.php";
echo wp_json_encode(get_option("woocommerce_currency"));
`,
});

console.log(phpResponseText(response));

Playground uses SQLite for WordPress storage, so prefer WordPress APIs like get_option() and $wpdb over database-specific SQL behavior.

Scenario 5: Change runtime settings for a saved site

Sometimes a bug only appears with a specific PHP version or with networking enabled. Once the active site is saved, you can update runtime settings directly:

await window.playgroundSites.setPhpVersion("8.3");
await window.playgroundSites.setNetworking(true);

These methods require a saved site. If the active site is temporary, save it first:

await window.playgroundSites.saveInBrowser("Network test");
await window.playgroundSites.setNetworking(true);

This is a good workflow for compatibility testing:

1. Create a clean site.
2. Install and configure the plugin.
3. Save the site.
4. Switch PHP versions.
5. Re-run the same plugin checks.

Scenario 6: Create a small compatibility checklist

You can combine the API calls into a manual checklist from DevTools. This example creates a site, saves it, gathers basic version information, and leaves the result in the console:

async function prepareCompatibilitySite() {
  function phpResponseText(response) {
    return "text" in response
      ? response.text
      : new TextDecoder().decode(response.bytes);
  }

  const slug = await window.playgroundSites.createNewTemporarySite(
    "compatibility-check",
    {
      phpVersion: "8.4",
      wpVersion: "latest",
      networking: true,
    }
  );

  await window.playgroundSites.saveInBrowser(
    "Compatibility check - PHP 8.4"
  );

  await window.playgroundSites.isReady();
  const client = window.playgroundSites.getClient();
  if (!client) {
    throw new Error("The compatibility site has not booted yet.");
  }

  const response = await client.run({
    code: `<?php
require_once "/wordpress/wp-load.php";
echo wp_json_encode([
  "site_url" => get_site_url(),
  "php" => phpversion(),
  "wp" => get_bloginfo("version"),
  "theme" => wp_get_theme()->get("Name"),
]);
`,
  });

  return {
    site: window.playgroundSites
      .list()
      .find((site) => site.slug === slug),
    info: JSON.parse(phpResponseText(response)),
  };
}

console.log(await prepareCompatibilitySite());

This is not a replacement for a full test suite. It is a fast way to prepare and inspect a browser-based testing site when you are triaging a report.

How this fits recent Playground updates

Recent Playground work also added deeper AI and browser automation hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. through MCP and WebMCP. The same centralized site management API supports those integrations, so AI agents and browser-native tools can manage Playground sites through explicit operations instead of clicking through menus.

For example:

• list() maps naturally to “show me my Playground sites.”
• setActiveSite(slug) maps to “open the site named Plugin compatibility test.”
• saveInBrowser(name) maps to “save this reproduction so I can come back later.”
• getClient() gives tool layers access to PHP execution, HTTPHTTP HTTP is an acronym for Hyper Text Transfer Protocol. HTTP is the underlying protocol used by the World Wide Web and this protocol defines how messages are formatted and transmitted, and what actions Web servers and browsers should take in response to various commands. requests, and filesystem operations.

The result is a cleaner foundation for agent workflows. A coding agent can keep one site for investigation, another for a clean reproduction, and another for verifying a fix, all without depending on visual UI state.

For setup instructions, see Connect AI coding agents to WordPress Playground with MCP. For URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org-based configuration options such as php, wp, networking, and site-slug, see the Query API documentation.

Practical limits

There are a few details to remember:

• window.playgroundSites is only available after Playground finishes loading saved sites.
• Temporary sites must be saved before you can rename them, delete them, or update their PHP/networking settings.
• Call isReady() before getClient() when the active site may still be booting. Until the site is ready, getClient() can return undefined.
• saveToLocalFileSystem() may open a browser directory picker when you do not pass a directory handle.
• Browser storage is still browser storage. Clearing site data can remove saved Playground sites.

Try it

Open playground.wordpress.net, wait for the site to finish loading, then open DevTools and run:

await window.playgroundSites.isReady();
window.playgroundSites.list();

From there, create a temporary site, save it, switch between saved sites, and use getClient() to inspect WordPress state with PHP. For plugin and theme developers, this turns Playground from a single sandbox into a small fleet of browser-based test environments.

@wp-now/wp-now is now deprecated and will not receive future updates. If you use wp-now for local WordPress development, the recommended replacement is @wp-playground/cli. The process took a few months because the Playground team was working to replace all the capabilities from wp-now.

This change is now reflected in the Playground documentation through PR #3767, which documents the migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. path from wp-now to Playground CLICLI Command Line Interface. Terminal (Bash) in Mac, Command Prompt in Windows, or WP-CLI for WordPress. and updates the CLI docs to lead with the new start command for familiar wp-now-style workflows. server command still available for more complex workflows.

Why this change

wp-now helped make local WordPress development fast and portable by running WordPress with the Playground runtime, without Docker, MySQLMySQL MySQL is a relational database management system. A database is a structured collection of data where content, configuration and other options are stored. https://www.mysql.com, or ApacheApache Apache is the most widely used web server software. Developed and maintained by Apache Software Foundation. Apache is an Open Source software available for free.. Over the last few years, though, new local development work has moved toward the official Playground CLI.

With the recent implementation of start command, it means the remaining gap has closed: Playground CLI now supports the familiar wp-now behavior and adds more room for customization through the broader WordPress Playground toolchain.

What to use instead

For most local development workflows, use:

npx @wp-playground/cli@latest start

It automatically detects whether the current directory is a pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party., theme, wp-content directory, or full WordPress installation. It also persists the site between runs, enables login, and opens the browser by default.

For lower-level control, use:

npx @wp-playground/cli@latest server

The server command is best when you want to define mounts, storage behavior, versions, Blueprints, or automation explicitly. It is also a better fit for CI and scripted development environments.

Migration guide

Most wp-now commands map directly to @wp-playground/cli start:

1. Replace the package name

If you currently run:

npx @wp-now/wp-now start

Run this instead:

npx @wp-playground/cli@latest start

You do not need to install the package globally. Using npx keeps your workflow on the latest Playground CLI release.

2. Run start from the project directory

The main workflow difference is how saved sites are associated with local paths.

With wp-now, --path=./plugin selected both the project and the saved site. With Playground CLI, start saves the site for the current working directory. For the closest match to wp-now --path, change into the project directory first:

cd ./plugin
npx @wp-playground/cli@latest start

start --path=./plugin still mounts that folder, but the saved site belongs to the directory where the command was run. If you want one persistent site per project, run the command from that project directory.

3. Keep version and Blueprint flags

Common version and Blueprint flags continue to work:

npx @wp-playground/cli@latest start --wp=6.8 --php=8.3
npx @wp-playground/cli@latest start --blueprint=./blueprint.json

Use --skip-browser if you do not want the browser to open automatically:

npx @wp-playground/cli@latest start --skip-browser

Use --reset to delete the stored site and start fresh:

npx @wp-playground/cli@latest start --reset

4. Understand persistence

When Playground CLI creates WordPress for you, start stores the site in:

~/.wordpress-playground/sites/<path-hash>/

The <path-hash> is derived from the command’s current working directory. This keeps projects isolated from one another while preserving the site between CLI runs.

If you run Playground CLI on a full WordPress directory, or mount a directory at /wordpress, that directory becomes the WordPress site and changes are written there instead.

What this means for existing wp-now users

Existing wp-now workflows should move to Playground CLI. The migration is intentionally small for common use cases: replace the package, use start, and run it from the project directory you want to persist.

For more advanced workflows, Playground CLI offers a larger surface area than wp-now, including server, run-blueprint, build-snapshot, custom mounts, and deeper configuration options.

See the updated documentation:

• wp-now migration page
• Playground CLI documentation
• PR #3767: Document wp-now migration to Playground CLI

Reviewing a pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party. or theme Pull Request has always carried a bit of friction. To actually test the change, someone had to pull the branch, spin up a local WordPress, and activate the code by hand. That is exactly why the WordPress Playground PR Preview GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged by the repository owner. https://github.com/ Action exists: it adds a “Preview in WordPress Playground” button straight to the PR. As a result, any reviewer opens the environment with the code already applied in the browser, without installing anything.

The action already existed in v2. However, version 3 underwent an important simplification: the manual “glue” that each project had to write for builds was replaced by ready-made, reusable workflows. In this post, therefore, I’ll cover what the action does, why it’s worth it, how to set it up in the two possible scenarios, practical examples, and the step-by-step path to migrate from v2.

What the WordPress Playground PR Preview action does

In short, it publishes a preview link on the Pull Request. That link points to a WordPress Playground instance, in other words, a full WordPress running through WebAssembly (WASM) in the browser of whoever clicks it. Playground boots clean, installs the plugin or theme from the PR branch, and automatically activates everything.

The result, then, is a disposable, isolated environment created on demand that mirrors the state of that branch exactly.

Why use it

• One-click testing: the reviewer needs no local setup and no WordPress installed.
• Works with forks: external contributions get a preview without exposing repository secrets.
• Plugin, theme, or both: you can create scenarios that combine several artifacts.
• Handles complex builds: projects that rely on Composer, npm, or Vite are supported too, through dedicated workflows.
• Real sandbox: the code runs in the user’s browser, isolated, without touching any server.

Scenario 1: no build step

This is the simplest path. Use it when the files committed to the repository run as-is, without compilation, for example, a plain PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. https://www.php.net/manual/en/index.php plugin.

First, create .github/workflows/pr-preview.yml:

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

jobs:
  preview:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: WordPress/action-wp-playground-pr-preview@v3
        with:
          plugin-path: .
          github-token: ${{ secrets.GITHUB_TOKEN }}

For a theme, swap plugin-path: . for theme-path: .. Besides that, the permissions blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. is mandatory: the action needs pull-requests: write to write the link on the PR and contents: read to read the code.

Main inputs of the direct action

You provide one of plugin-path, theme-path, blueprint, or blueprint-url. The mode, in turn, decides whether the link goes into the PR description body or as a comment.

Scenario 2: with a build step

When the preview depends on compilation (npm run build, Composer, etc.), v3 uses two workflows that talk to each other. First, one builds the untrusted PR code with read-only permissions. Then, the other publishes the result from the default branch, with write permissions, without ever executing the PR code. The only point of contact between them is the generated ZIP file — and that is precisely what keeps the flow secure.

The build workflow lives in .github/workflows/pr-preview-build.yml:

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

jobs:
  build:
    uses: WordPress/action-wp-playground-pr-preview/.github/workflows/preview-build.yml@v3
    with:
      artifacts: my-plugin=build/my-plugin.zip
      node-version: '20'
      build-command: |
        npm ci
        npm run build:plugin-zip

The publish workflow, in turn, lives in .github/workflows/pr-preview-publish.yml:

name: PR Preview - Publish
on:
  workflow_run:
    workflows: ["PR Preview - Build"]
    types: [completed]

permissions:
  contents: write
  pull-requests: write

jobs:
  publish:
    permissions:
      contents: write
      pull-requests: write
    uses: WordPress/action-wp-playground-pr-preview/.github/workflows/preview-publish.yml@v3
    with:
      kind: plugin

The artifacts field uses the name=path/to/file.zip format — one per line, if you have several. The kind in publish, meanwhile, tells whether the artifact is a plugin or a theme. Besides that, the reusable workflows take care of automatically creating a ci-artifacts prerelease to host the ZIPs publicly. After all, Playground needs to download the asset, so it can’t be in a draft release.

Build workflow inputs

Practical example: custom Blueprint

Sometimes you need more than “install and activate”. Say, a plugin from the PR running alongside WooCommerce and already logged in as admin. In that case, use a Blueprint. It’s a JSON recipe that describes the site’s initial state.

- uses: WordPress/action-wp-playground-pr-preview@v3
  with:
    blueprint: |
      {
        "$schema": "https://playground.wordpress.net/blueprint-schema.json",
        "preferredVersions": { "php": "8.3", "wp": "6.6" },
        "steps": [
          { "step": "installPlugin",
            "pluginData": {
              "resource": "git:directory",
              "url": "https://github.com/${{ github.repository }}.git",
              "ref": "${{ github.event.pull_request.head.ref }}",
              "path": "/"
            },
            "options": { "activate": true } },
          { "step": "installPlugin",
            "pluginData": { "resource": "wordpress.org/plugins", "slug": "woocommerce" },
            "options": { "activate": true } },
          { "step": "login", "username": "admin" }
        ]
      }
    github-token: ${{ secrets.GITHUB_TOKEN }}

This Blueprint pins PHP 8.3 and WordPress 6.6, installs the code from the PR branch, adds WooCommerce from the official repository, and hands over an already-logged-in environment. For build scenarios, moreover, you can reference the generated ZIPs inside the Blueprint using the {{ARTIFACT_URL:<name>}} placeholder. That way, v3 resolves the public artifact URL for you.

Migrating from v2 to v3

In practice, the migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. varies with the complexity of your setup.

Simple plugins and themes (no build): here, almost nothing changes. Switch the action reference from @v2 to @v3 and keep the same inputs.

# works the same in v2 and v3
- uses: WordPress/action-wp-playground-pr-preview@v3
  with:
    plugin-path: .
    github-token: ${{ secrets.GITHUB_TOKEN }}

Projects with a build: this is where the real gain is. On v2 you needed a build workflow, plus manual parsing of the artifact name, plus an expose-artifact-on-public-url helper, plus manual Blueprint generation, and still the manual release publishing. v3, by contrast, replaces all of that with the two reusable workflows (preview-build.yml and preview-publish.yml) shown above. The step-by-step, therefore, looks like this:

1. Create pr-preview-build.yml with the build workflow template.
2. Create pr-preview-publish.yml with the publish workflow template.
3. Define the artifacts in the artifacts field (name=path format).
4. Set kind: plugin or kind: theme in publish — or, alternatively, use blueprint with {{ARTIFACT_URL:<name>}} placeholders for setups with multiple ZIPs.

Inputs such as artifact-name, artifact-filename, artifact-source-run-id, pr-number, and commit-sha, which existed only for the manual glue, are no longer needed in most cases.

Finally, watch out for the mandatory release cleanup: the change that breaks the most in practice is that draft releases no longer work. After all, Playground can’t download assets from a draft release without authentication. Therefore, if you have ci-artifacts releases in draft, convert them to prerelease or delete them.

Common gotchas

• 404 error when opening the preview: the release is probably set as a draft instead of a prerelease. Fix it on the repository’s Releases tab.
• Plugin doesn’t show up as installed: the ZIP must be extracted to a folder named after the slug. Make sure your build does that. For example:
  bash mkdir -p stage/my-plugin && rsync -a ./ stage/my-plugin/ && (cd stage && zip -r ../my-plugin.zip my-plugin)
• Build failing when comparing against the base: if you use git diff against the base branch, set fetch-depth: 0 in the build workflow. After all, the default checkout brings only the latest commit.
• Permission error: the permissions block is missing at the workflow or job level.

Conclusion

If you already used v2 for builds, migrating is worth it: you delete dozens of lines of manual glue and get tested, community-maintained workflows in their place. On the other hand, if you don’t use PR preview in your plugin or theme repository yet, the no-build scenario solves it with a few lines of YAML — and noticeably improves the experience for whoever reviews code in your project.

The full documentation lives at wordpress.github.io/action-wp-playground-pr-preview. For the more specific cases, also check the detailed migration guide.