diff --git a/packages/docs/site/docs/main/about/test.md b/packages/docs/site/docs/main/about/test.md index 72e038b94c..e32e96befb 100644 --- a/packages/docs/site/docs/main/about/test.md +++ b/packages/docs/site/docs/main/about/test.md @@ -24,7 +24,7 @@ Testing pull requests is one of the most exciting use cases for the Playground p There are some public implementations of this use case such as [WordPress Core PR previewer](https://playground.wordpress.net/wordpress.html) and [Gutenberg PR previewer](https://playground.wordpress.net/gutenberg.html). Users can input the PR number or URL to be redirected to a WordPress instance, powered by Playground, where the changes from the PR are applied. -GitHub actions such as [WP Playground PR Preview](https://github.com/vcanales/action-wp-playground-pr-preview) allows you to add PR previews powered by WP Playground on any repository. For example, this feature [was enabled](https://github.com/WordPress/twentytwentyfive/pull/359) in the [WordPress/twentytwentyfive](https://github.com/WordPress/twentytwentyfive) repository. +You can add automated PR preview buttons to your own plugin or theme repository using the WordPress Playground PR Preview GitHub Action. When someone opens a pull request, the action automatically adds a button that launches a configured WordPress instance with the changes ready to test. For detailed setup instructions and advanced configurations, see the [Adding PR Preview Buttons with GitHub Actions](/guides/github-action-pr-preview) guide. ## Clone your site and experiment in a private sandbox. diff --git a/packages/docs/site/docs/main/guides/for-plugin-developers.md b/packages/docs/site/docs/main/guides/for-plugin-developers.md index c6f491a8a1..2630068850 100644 --- a/packages/docs/site/docs/main/guides/for-plugin-developers.md +++ b/packages/docs/site/docs/main/guides/for-plugin-developers.md @@ -58,6 +58,10 @@ To avoid CORS issues, the Playground project provides a [GitHub proxy](https://p [GitHub proxy](https://playground.wordpress.net/proxy) is an incredibly useful tool to load plugins from GitHub repositories as it allows you to load a plugin from a specific branch, a specific directory, a specific commit or a specific PR. ::: +:::tip +If your plugin is hosted on GitHub, you can automatically add preview buttons to your pull requests using the Playground PR Preview GitHub Action. This lets reviewers test your changes instantly without any setup. See [Adding PR Preview Buttons with GitHub Actions](/guides/github-action-pr-preview) for details. +::: + For example, the following `blueprint.json` installs a plugin from a GitHub repository leveraging the https://github-proxy.com tool: ```json diff --git a/packages/docs/site/docs/main/guides/for-theme-developers.md b/packages/docs/site/docs/main/guides/for-theme-developers.md index 0683a45c5d..0e46e955e2 100644 --- a/packages/docs/site/docs/main/guides/for-theme-developers.md +++ b/packages/docs/site/docs/main/guides/for-theme-developers.md @@ -52,6 +52,8 @@ To avoid CORS issues, the Playground project provides a [GitHub proxy](https://p :::tip [GitHub proxy](https://playground.wordpress.net/proxy) is an incredibly useful tool to load themes from GitHub repositories as it allows you to load a theme from a specific branch, a specific directory, a specific commit or a specific PR. + +If your theme is hosted on GitHub, you can automatically add preview buttons to your pull requests using the Playground PR Preview GitHub Action. This lets reviewers test your changes instantly without any setup. See [Adding PR Preview Buttons with GitHub Actions](/guides/github-action-pr-preview) for details. ::: For example the following `blueprint.json` installs a theme from a GitHub repository leveraging the https://github-proxy.com tool: diff --git a/packages/docs/site/docs/main/guides/github-action-pr-preview.md b/packages/docs/site/docs/main/guides/github-action-pr-preview.md new file mode 100644 index 0000000000..fa083a55e8 --- /dev/null +++ b/packages/docs/site/docs/main/guides/github-action-pr-preview.md @@ -0,0 +1,281 @@ +--- +title: Adding PR Preview Buttons with GitHub Actions +slug: /guides/github-action-pr-preview +description: Automatically add Playground preview buttons to pull requests for your WordPress plugin or theme. +--- + +The Playground PR Preview action adds a preview button to your pull requests. Clicking the button launches Playground with your plugin or theme installed from the PR branch: + +![PR Preview Button](@site/static/img/try-it-in-playground.png) + +For complete configuration options and advanced features, see the [action-wp-playground-pr-preview workflow README](https://github.com/WordPress/action-wp-playground-pr-preview/tree/v2). + +## How it works + +The action runs on pull request events (opened, updated, edited). It can either update the PR description with a preview button or post the button as a comment. + +## Basic setup for plugins + +For plugins without a build step, create `.github/workflows/pr-preview.yml`: + +```yaml +name: PR Preview +on: + pull_request: + types: [opened, synchronize, reopened, edited] + +jobs: + preview: + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: write + steps: + - name: Post Playground Preview Button + uses: WordPress/action-wp-playground-pr-preview@v2 + with: + mode: 'append-to-description' + plugin-path: . +``` + +The `plugin-path: .` setting points to your plugin directory. For subdirectories like `plugins/my-plugin`, use `plugin-path: plugins/my-plugin`. + +See [adamziel/preview-in-playground-button-plugin-example](https://github.com/adamziel/preview-in-playground-button-plugin-example/pull/1) for a working example. + +## Basic setup for themes + +For themes, use `theme-path` instead of `plugin-path`: + +```yaml +name: PR Preview +on: + pull_request: + types: [opened, synchronize, reopened, edited] + +jobs: + preview: + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: write + steps: + - name: Post Playground Preview Button + uses: WordPress/action-wp-playground-pr-preview@v2 + with: + theme-path: . +``` + +## Button placement + +By default, the action updates the PR description (`mode: append-to-description`). To post as a comment instead: + +```yaml +with: + plugin-path: . + mode: comment +``` + +The action wraps the button in HTML markers and updates it on subsequent runs. By default, it restores the button if you remove it. To prevent restoration: + +```yaml +with: + plugin-path: . + restore-button-if-removed: false +``` + +## Working with built artifacts + +For plugins or themes requiring compilation, the workflow involves building the code, exposing it via GitHub releases, and creating a blueprint that references the public URL. + +Example workflow (see [complete documentation](https://github.com/WordPress/action-wp-playground-pr-preview/tree/v2#advanced-testing-built-ci-artifacts)): + +```yaml +name: PR Preview with Build +on: + pull_request: + types: [opened, synchronize, reopened, edited] + +permissions: + contents: write + pull-requests: write + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Build + run: | + npm install + npm run build + zip -r plugin.zip dist/ + - uses: actions/upload-artifact@v4 + with: + name: built-plugin + path: plugin.zip + + expose-build: + needs: build + runs-on: ubuntu-latest + permissions: + contents: write + outputs: + artifact-url: ${{ steps.expose.outputs.artifact-url }} + steps: + - name: Expose built artifact + id: expose + uses: WordPress/action-wp-playground-pr-preview/.github/actions/expose-artifact-on-public-url@v2 + with: + artifact-name: 'built-plugin' + pr-number: ${{ github.event.pull_request.number }} + commit-sha: ${{ github.sha }} + artifacts-to-keep: '2' + + create-blueprint: + needs: expose-build + runs-on: ubuntu-latest + outputs: + blueprint: ${{ steps.blueprint.outputs.result }} + steps: + - uses: actions/github-script@v7 + id: blueprint + with: + script: | + const blueprint = { + steps: [{ + step: "installPlugin", + pluginZipFile: { + resource: "url", + url: "${{ needs.expose-build.outputs.artifact-url }}" + } + }] + }; + return JSON.stringify(blueprint); + result-encoding: string + + preview: + needs: create-blueprint + runs-on: ubuntu-latest + permissions: + pull-requests: write + steps: + - uses: WordPress/action-wp-playground-pr-preview@v2 + with: + blueprint: ${{ needs.create-blueprint.outputs.blueprint }} +``` + +The `artifacts-to-keep` setting controls how many builds to retain per PR. For themes, change `installPlugin` to `installTheme`. + +See [adamziel/preview-in-playground-button-built-artifact-example](https://github.com/adamziel/preview-in-playground-button-built-artifact-example/pull/2) for a complete working example. + +## Custom blueprints + +Use blueprints to configure the Playground environment. You can install additional plugins, set WordPress options, import content, or run custom PHP. + +Example installing your plugin with WooCommerce: + +```yaml +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 + + preview: + needs: create-blueprint + runs-on: ubuntu-latest + permissions: + pull-requests: write + steps: + - uses: WordPress/action-wp-playground-pr-preview@v2 + with: + blueprint: ${{ needs.create-blueprint.outputs.blueprint }} +``` + +Or reference an external blueprint: + +```yaml +with: + blueprint-url: https://example.com/path/to/blueprint.json +``` + +See [Blueprints documentation](/blueprints) for all available steps and configuration options. + +## Template customization + +Customize the preview content using template variables: + +```yaml +with: + plugin-path: . + description-template: | + ### Test this PR in WordPress Playground + + {{PLAYGROUND_BUTTON}} + + **Branch:** {{PR_HEAD_REF}} +``` + +Available variables: `{{PLAYGROUND_BUTTON}}`, `{{PLUGIN_SLUG}}`, `{{THEME_SLUG}}`, `{{PR_NUMBER}}`, `{{PR_TITLE}}`, `{{PR_HEAD_REF}}`, and more. + +See the workflow README for the [complete list](https://github.com/WordPress/action-wp-playground-pr-preview/tree/v2#description-template). + +## Artifact exposure + +The `expose-artifact-on-public-url` action uploads built files to a single release (tagged `ci-artifacts` by default). Each artifact gets a unique filename like `pr-123-abc1234.zip`. Old artifacts are automatically cleaned up based on `artifacts-to-keep`. + +Configuration options: [Expose Artifact Inputs](https://github.com/WordPress/action-wp-playground-pr-preview/tree/v2#expose-artifact-inputs) + +## Troubleshooting + +**Button not appearing:** Workflow file must exist on the default branch. Check Actions tab for errors. + +**Preview fails to load:** Verify path points to valid plugin/theme directory. Check build logs for artifacts. + +**Not activated:** Check browser console for PHP errors. Dependencies may be missing. + +**Permissions errors:** Set permissions at job level. + +More: [workflow README](https://github.com/WordPress/action-wp-playground-pr-preview/tree/v2) + +## Examples + +- [WordPress/blueprints](https://github.com/WordPress/blueprints/pull/155) - Blueprint previews +- [adamziel/preview-in-playground-button-plugin-example](https://github.com/adamziel/preview-in-playground-button-plugin-example/pull/3) - Plugin without build +- [adamziel/preview-in-playground-button-built-artifact-example](https://github.com/adamziel/preview-in-playground-button-built-artifact-example/pull/2) - Plugin with build + +## Next steps + +- Add demo content ([guide](/guides/providing-content-for-your-demo)) +- Create custom blueprints ([docs](/blueprints)) +- Integrate with testing workflows +- Customize templates for reviewers diff --git a/packages/docs/site/docs/main/guides/index.md b/packages/docs/site/docs/main/guides/index.md index 1c57835a5d..15aff03977 100644 --- a/packages/docs/site/docs/main/guides/index.md +++ b/packages/docs/site/docs/main/guides/index.md @@ -24,3 +24,7 @@ This guide will show you the essential settings to fully create a theme demo usi ## [WordPress Playground for Plugin Developers](/guides/for-plugin-developers) This guide will show you the basic settings to showcase your plugin using WordPress Playground and how to use it while developing your plugin. + +## [Adding PR Preview Buttons with GitHub Actions](/guides/github-action-pr-preview) + +Learn how to automatically add one-click preview buttons to your pull requests. When someone opens a PR on your plugin or theme repository, they get an instant link to test the changes in a fully configured WordPress instance running in the browser. diff --git a/packages/docs/site/static/img/try-it-in-playground.png b/packages/docs/site/static/img/try-it-in-playground.png new file mode 100644 index 0000000000..d3e040f1d4 Binary files /dev/null and b/packages/docs/site/static/img/try-it-in-playground.png differ