Docs: How to add Pull Request previews to your repository?

[adamziel]

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.

Warning

Remember to only allow running the action from your repository! Otherwise forks will get access to your secrets.

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

[stoph]

In the github-proxy section, did you mean "https://github-proxy.com" instead of "https://github.com/topics/https-proxy" Not sure if the original links were intentional.

Use GitHub Proxy
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-proxy.com for more details. From there, you'd create a Blueprint

I will also write some additional documentation for it, as well as address some issues

[adamziel]

Relevant PR to add a preview for the Automattic/themes repo from @vcanales: Automattic/themes#7719. Also, this setup is used by the Blueprints community space repo – it updates the preview comment as the PR is updated and merged.

https://github.com/adamziel/blueprints/blob/778ba6fad9e07cec6fa3d0803cbf589bdd5ea8b1/.github/workflows/preview-comment.yml

[adamziel]

Not sure if the original links were intentional.

@stoph just a typo, I was moving too fast :-)

[zzap]

I want to work on this one

[zzap]

A new draft for the intro:

• change the title
• expand the intro to 3 distinctive areas: the problem, the solution, and the prerequisites.

The intro should be used to establish the following:

• the starting point - so you know if you can arrive at the end or need more knowledge
• the finish line - so you know if that's what you're looking for
• any third-party tools/libraries - or other things that are necessary for the result but won't be explained as they have their official docs

This is a kindness to the reader that should help them bail early if the tutorial is not for them and they can't decide from the title. It also introduces the vocabulary (especially with third-party items), which helps them follow the tutorial fluently.

---

Automatically add changes preview links in pull request comments

[describe the problem]

This article assumes you have a GitHub repository where active development happens and that you want to preview changes in each PR. Playground is an excellent tool for quickly opening a new WordPress instance in your browser with one click. However, setting up a custom preview (a specific theme, plugin, or combination) takes a bit more than a click. Setting it up for each PR can add up to time and involve a lot of repetition.

[describe the outcome]

In combination with other tools, available at GitHub, many actions can be automated. This is a tutorial on how to automate creating a comment that contains a Playground preview link to a WordPress instance with all the changes from the current PR.

This functionality is utilized in the wordpress-develop repository's workflow. A CI action comments on every Pull Request with a Playground preview link.

[list the requirements and expected knowledge]

Prerequisites:

• A GitHub repo with a WordPress project - a theme, a plugin, or the whole website.

This tutorial will mention a few things outside of WordPress. Understanding them profoundly is not necessary, but a basic understanding of what they do in general will help in following the tutorial and successfully completing it.

Good to understand:

• GitHub actions
• GitHub workflows

[carstingaxion]

Hello @zzap

currently, the text gave me the feeling, that I will just need to grab the CI action from one of the mentioned repos, but the important is missing (to me), the adaption process, like @adamziel pointed out earlier.

If you do want to add some information on that, I'll happily share some of my good and bad adaption-experiences.