PR Preview com WordPress Playground: o que muda na versão 3 da GitHub Action

Revisar um Pull Request de plugin ou tema sempre demanda tempo. Para testar de verdade, alguém precisava baixar a branch, subir um WordPress local e ativar o código manualmente. Por isso, existe a GitHub Action de PR Preview do WordPress Playground: ela adiciona um botão “Preview in WordPress Playground” diretamente no PR. Dessa forma, qualquer revisor abre o ambiente já com o código aplicado, no navegador, sem instalar nada.

A action já existia na v2. No entanto, a versão 3 passou por uma simplificação importante: a “cola” manual que cada projeto tinha que escrever para builds deu lugar a reusable workflows prontos. Neste post, portanto, vou cobrir o que ela faz, por que vale a pena, como configurá-la nos dois cenários possíveis, exemplos práticos e o passo a passo para migrar da v2.

O que a action de PR Preview do WordPress Playground faz

Em resumo, ela publica um link de prévia no Pull Request. Esse link aponta para uma instância do WordPress Playground — ou seja, um WordPress completo rodando via WebAssembly (WASM) no navegador do usuário. O Playground sobe limpo, instala o plugin ou tema da branch do PR e ativa tudo automaticamente.

O resultado, portanto, é um ambiente descartável e isolado, criado sob demanda, que reflete exatamente o estado daquela branch.

Por que usar

• Teste em um clique: o revisor não precisa de configuração local nem de WordPress instalado.
• Funciona com forks: contribuições externas recebem uma prévia sem expor segredos do repositório.
• Plugin, tema ou os dois: dá para montar cenários combinando vários artefatos.
• Lida com builds complexos: projetos que dependem de Composer, npm ou Vite também são suportados por meio de workflows dedicados.
• Sandbox real: o código roda no navegador do usuário, isolado, sem tocar em nenhum servidor.

Cenário 1: sem etapa de build

Esse é o caminho mais simples. Use quando os arquivos versionados no repositório já rodam direto, sem compilação, um plugin em PHP puro, por exemplo.

Primeiramente, crie .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 }}

Para um tema, troque plugin-path: . por theme-path: .. Além disso, o bloco permissions é obrigatório: a action precisa de pull-requests: write para escrever o link no PR e contents: read para ler o código.

Inputs principais da action direta

Você fornece um entre plugin-path, theme-path, blueprint ou blueprint-url. Já o mode decide se o link entra no corpo da descrição do PR ou como comentário.

Cenário 2: com etapa de build

Quando o preview depende de compilação (npm run build, Composer, etc.), a v3 usa dois workflows que se conversam. Primeiramente, faz-se o build do código não confiável do PR com permissões somente leitura. Em seguida, o outro publica o resultado a partir da branch padrão, com permissões de escrita, sem nunca executar o código do PR. O único ponto de contato entre os dois é o arquivo ZIP gerado — e é justamente isso que mantém o fluxo seguro.

O workflow de build fica em .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

Já o workflow de publicação fica em .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

O campo artifacts usa o formato nome=caminho/para/arquivo.zip — um por linha, se houver vários. Já o kind no publish indica se o artefato é plugin ou theme. Além disso, os reusable workflows cuidam de criar automaticamente um prerelease ci-artifacts para hospedar os ZIPs publicamente. Afinal, o Playground precisa baixar o asset, e por isso ele não pode ficar em um release draft.

Inputs do workflow de build

Exemplo prático: Blueprint customizado

Às vezes você precisa de mais do que “instalar e ativar”, digamos, um plugin do PR rodando junto com o WooCommerce e já logado como admin. Nesse caso, use um Blueprint. Ele é uma receita em JSON que descreve o estado inicial do site. Se quiser se aprofundar no formato, vale conferir o post sobre o WordPress Playground e os Blueprints.

- uses: WordPress/action-wp-playground-pr-preview@v3
  with:
    blueprint: |
      {
        "$schema": "https://playground.wordpress.net/blueprint-schema.json",
        "preferredVersions": { "php": "8.3", "wp": "7.0" },
        "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 }}

Esse Blueprint fixa PHP 8.3 e WordPress 7.0, instala o código da branch do PR, adiciona o WooCommerce do repositório oficial e já entrega o ambiente logado. Para cenários com build, além disso, dá para referenciar os ZIPs gerados dentro do Blueprint usando o placeholder {{ARTIFACT_URL:<nome>}}. Dessa forma, a v3 resolve a URL pública do artefato para você.

Migrando da v2 para a v3

Na prática, a migração varia conforme a complexidade do seu setup.

Plugins e temas simples (sem build): aqui praticamente nada muda. Troque a referência da action de @v2 para @v3 e mantenha os mesmos inputs.

# funciona igual na v2 e na v3
- uses: WordPress/action-wp-playground-pr-preview@v3
  with:
    plugin-path: .
    github-token: ${{ secrets.GITHUB_TOKEN }}

Projetos com build: aqui está o ganho real. Na v2, você precisava de um workflow de build, mais o parsing manual do nome do artefato, mais um helper expose-artifact-on-public-url, mais a geração manual do Blueprint e ainda a publicação manual do release. A v3, em contrapartida, substitui tudo isso pelos dois reusable workflows (preview-build.yml e preview-publish.yml) mostrados acima. O passo a passo, portanto, fica assim:

1. Crie o pr-preview-build.yml com o template do workflow de build.
2. Crie o pr-preview-publish.yml com o template do workflow de publicação.
3. Defina os artefatos no campo artifacts (formato nome=caminho).
4. Indique kind: plugin ou kind: theme no publish — ou, então, use blueprint com placeholders {{ARTIFACT_URL:<nome>}} para setups com múltiplos ZIPs.

Inputs como artifact-name, artifact-filename, artifact-source-run-id, pr-number e commit-sha, que existiam só para a cola manual, deixam de ser necessários na maioria dos casos.

Por fim, atenção à limpeza obrigatória de releases: a mudança que mais quebra na prática é que releases em draft não funcionam mais. Afinal, o Playground não consegue baixar assets de um release draft sem autenticação. Portanto, se você tiver releases ci-artifacts em draft, converta para prerelease ou apague.

Pegadinhas comuns

• Erro 404 ao abrir o preview: provavelmente o release está como draft em vez de prerelease. Ajuste na aba Releases do repositório.
• Plugin não aparece instalado: o ZIP precisa ser extraído para uma pasta com o nome do slug. Garanta isso no seu build. Por exemplo:
  bash mkdir -p stage/my-plugin && rsync -a ./ stage/my-plugin/ && (cd stage && zip -r ../my-plugin.zip my-plugin)
• Build falhando ao comparar com a base: se você usa git diff contra a branch base, defina fetch-depth: 0 no workflow de build. Afinal, o checkout padrão traz só o último commit.
• Erro de permissão: falta o bloco permissions no nível do workflow ou do job.

Conclusão

Se você já usava a v2 para builds, vale migrar: assim, você reduz a quantidade de linhas de código manual e ganha workflows testados e mantidos pela comunidade no lugar. Por outro lado, se ainda não usa PR preview no seu repositório de plugin ou tema, o cenário sem build resolve com poucas linhas de YAML — e melhora bastante a experiência de quem revisa código no seu projeto.

A documentação completa está em wordpress.github.io/action-wp-playground-pr-preview. Para os casos mais específicos, consulte também o guia de migração detalhado.