This is a very rough draft of a new documentation page. Let's turn it into a PR and refine it before shipping. CC @ockham @ironprogrammer @stoph

Done is

• A Pull Request for this repository proposing a new documentation page at packages/docs/site/docs/02-start-using/04-how-to-add-pull-requests-previews-to-your-repository.md
• Any limitations encountered documented as a PR for the limitations page (could be the same PR).
• A YouTube video would be amazing

Related resources

• Introduction to Playground
• Contributing to Playground documentation.

Draft below:

Using Playground PR Preview Comments

Playground offers a built-in functionality for creating previews directly from pull requests. This functionality is utilized in the wordpress-develop repository's workflow (https://make.wordpress.org/core/handbook/contribute/git/github-pull-requests-for-code-review/). A CI action comments on every Pull Request with a Playground preview link:

Preparing a GitHub CI action

Adapt this wordpress-develop workflow to your repository. If you're not sure how, get familiar with GitHub actions first.

Preparing a Zip file for the preview

Loading a Pull Request in WordPress Playground requires exposing a .zip file with a WordPress-installable artifact (a theme, a plugin, an entire site, etc.).

There's a few ways you can expose that zip:

1. Include it in PR
2. Upload to GitHub Artifacts
3. Use github-proxy.com

Include it in the PR

While less ideal, the built zip artifact file can be directly included within the pull request itself. From there, you could reference it from https://raw.githubusercontent.com/.

Upload to GitHub Artifacts

This approach mirrors the method used in wordpress-develop previews. It leverages the /plugin-proxy.php endpoint to bypass GitHub authentication and CORS.

To get it running, you'd need to:

1. Create an artifact for every PR in your repo
2. Propose a PR to plugin-proxy.php to allow it to access your repo
3. Create a Blueprint to setup Playground with your artifact loaded

Use github-proxy.com

https://github.com/stoph/github-proxy solves the ZIP file problem, too. You can use it to download zipped directories and branches from your public repo. See https://github.com/stoph/github-proxy/issues for more details. From there, you'd create a Blueprint:

{
    "landingPage": "/wp-admin/plugins.php",
    "steps": [
        {
            "step": "login",
            "username": "admin",
            "password": "password"
        },
        {
            "step": "installPlugin",
            "pluginZipFile": {
                "resource": "url",
                "url": "https://github-proxy.com/archive/ORG/REPO/main"
            },
            "options": {
                "activate": true
            }
        }
    ]
}

Gotchas

If a user without permissions in the repo submits a PR via a fork, the action always failed with an error such as:

Run actions/github-script@v7
RequestError [HttpError]: Resource not accessible by integration

The solution is to use a pull_request_target trigger for the workflow instead of pull_request. Example: See how this Blueprints PR has a preview link even though it comes from a fork. The workflow in the Blueprints Gallery repo runs on pull_request_target