Añadir botones de vista previa de PR con GitHub Actions
La acción Playground PR Preview añade un botón de vista previa a tus pull requests. Al pulsarlo, Playground se inicia con tu plugin o tema instalado desde la rama de la PR:

Empieza por la configuración que corresponda a tu repositorio:
| Tu repositorio | Usa esta configuración |
|---|---|
| El plugin o tema funciona directamente con los archivos del repositorio | Sin paso de compilación |
| El plugin o tema necesita ejecutar Composer, npm, Vite u otro comando de compilación primero | Con un paso de compilación |
| Las PR de forks públicos necesitan vistas previas funcionales | Con un paso de compilación |
| Repositorio privado | La configuración predeterminada no basta; Playground necesita URL públicas que no requieran autenticación. |
Si tienes dudas, usa la configuración sin compilación solo cuando los archivos incluidos en la pull request sean exactamente los que WordPress debe ejecutar. Si la integración continua (CI) debe generar algún archivo antes, usa la configuración con compilación.
Para consultar todas las opciones de configuración, recetas y tablas de referencia, visita la documentación de action-wp-playground-pr-preview.
Cómo funciona
Playground ejecuta WordPress en el navegador. Todo lo que instala, como un ZIP de plugin, un ZIP de tema o un archivo WXR, debe estar disponible en una URL pública cuando alguien pulse el botón de vista previa.
La acción utiliza dos estrategias de URL:
git:directory: Playground obtiene el repositorio en la referencia de la pull request. Usa esta opción para la configuración sin compilación.- Archivos de versiones: la CI genera archivos ZIP y los sube a una versión preliminar pública llamada
ci-artifacts. Usa esta opción cuando la vista previa necesite dependencias de Composer, archivos generados por npm, recursos compilados u otros archivos generados.
Usa la acción y los flujos de trabajo reutilizables en lugares diferentes
La acción directa, WordPress/action-wp-playground-pr-preview@v4, es una acción normal de GitHub. Inclúyela como un paso en jobs.<job_id>.steps[].uses.
La configuración con compilación utiliza los flujos de trabajo reutilizables preview-build.yml@v4 y preview-publish.yml@v4. Inclúyelos en el nivel del job, en jobs.<job_id>.uses.
Sin paso de compilación
Usa esta configuración cuando tu plugin o tema pueda funcionar directamente con los archivos del repositorio, sin instalar dependencias de Composer, compilar con npm ni procesar recursos.
Crea .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@v4
with:
plugin-path: .
github-token: ${{ secrets.GITHUB_TOKEN }}
Para un tema, usa theme-path: . en lugar de plugin-path: .:
with:
theme-path: .
github-token: ${{ secrets.GITHUB_TOKEN }}
Usa un subdirectorio cuando el plugin o tema no esté en la raíz del repositorio:
with:
plugin-path: plugins/my-plugin
github-token: ${{ secrets.GITHUB_TOKEN }}
No necesitas crear secrets.GITHUB_TOKEN; GitHub lo proporciona automáticamente. El bloque permissions concede al token el acceso que necesita esta acción.
Abre una pull request. La acción actualiza la descripción de la PR con un bloque gestionado que contiene el botón de vista previa. Al pulsarlo, Playground se abre con tu plugin o tema instalado y activado desde la referencia de la pull request.
Nota sobre las PR de forks
Esta configuración con un único flujo de trabajo es la más sencilla para las PR del mismo repositorio. Las PR de forks públicos suelen recibir un GITHUB_TOKEN de solo lectura, por lo que la acción puede no tener permiso para editar la descripción de la PR. Si quienes contribuyen desde forks necesitan vistas previas funcionales, usa la configuración con compilación, aunque el comando solo cree un ZIP.
No cambies este flujo de trabajo a pull_request_target para ejecutar código de la PR con permisos de escritura.
Con un paso de compilación
Usa esta configuración cuando la vista previa necesite archivos generados, como dependencias de Composer, paquetes de npm o Vite, u otros resultados de compilación. También ofrece una forma segura de disponer de vistas previas funcionales para las PR de forks públicos.
Crea dos archivos de flujo de trabajo:
- Un flujo de compilación que se ejecuta en
pull_requestcon permisos de solo lectura, ejecuta tu comando de compilación y sube archivos ZIP como un artefacto de GitHub Actions. - Un flujo de publicación que se ejecuta en
workflow_runcuando la compilación termina correctamente, sube esos ZIP a una URL pública de una versión, crea un Blueprint y publica el botón de vista previa.
Flujo de compilación
Crea .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@v4
with:
artifacts: my-plugin=build/my-plugin.zip
node-version: '20'
build-command: |
npm ci
npm run build:plugin-zip
En artifacts: my-plugin=build/my-plugin.zip, my-plugin es el nombre del artefacto y build/my-plugin.zip es el archivo ZIP que debe crear tu build-command. El ZIP debe extraerse en una carpeta con el slug del plugin o tema, como my-plugin/my-plugin.php, y no directamente en archivos en la raíz.
Flujo de publicación
Crea .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@v4
with:
kind: plugin
Usa kind: theme para un único ZIP de tema. Para varios ZIP o pasos adicionales de configuración, usa un blueprint: personalizado, como se muestra en Artefactos compilados con un Blueprint personalizado.
Abre una pull request. El flujo de compilación ejecuta tu comando de compilación. Cuando termina correctamente, el flujo de publicación crea o actualiza la versión preliminar ci-artifacts, sube el ZIP generado y añade un botón de vista previa a la descripción de la PR.
¿Por qué dos archivos de flujo de trabajo?
GitHub no permite que un único flujo de trabajo ejecute de forma segura código no confiable de una PR de un fork y escriba en versiones o descripciones de PR. El flujo de compilación ejecuta el código de la PR con permisos de solo lectura. El flujo de publicación se ejecuta después desde la rama predeterminada con permisos de escritura y nunca hace checkout ni ejecuta el código de la PR.
Blueprints personalizados
Usa Blueprints para configurar el entorno de Playground. Puedes instalar plugins complementarios, definir opciones de WordPress, importar contenido, fijar versiones de PHP y WordPress, abrir una página concreta o iniciar sesión como administrador.
Para una vista previa sin compilación, proporciona un Blueprint completo a la acción directa:
- uses: WordPress/action-wp-playground-pr-preview@v4
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 }}
O referencia un Blueprint alojado:
- uses: WordPress/action-wp-playground-pr-preview@v4
with:
blueprint-url: https://example.com/path/to/blueprint.json
github-token: ${{ secrets.GITHUB_TOKEN }}
Elige el parámetro del Blueprint según el origen del JSON:
- Usa
blueprintcuando la acción directa o el flujo de publicación pueda incluir la cadena JSON completa. - Usa
blueprint-urlcon la acción directa cuando el JSON ya esté alojado en una URL pública. - Usa
blueprint-from-buildenpreview-build.ymljunto conblueprint-from-artifact: trueenpreview-publish.ymlcuando el flujo de compilación genereblueprint.jsonde forma dinámica.
Consulta la documentación de Blueprints para ver todos los pasos y opciones de configuración disponibles.
Artefactos compilados con un Blueprint personalizado
Usa un Blueprint personalizado en el flujo de publicación cuando una vista previa compilada necesite algo más que el comportamiento predeterminado de «instalar y activar». Algunos motivos habituales son instalar varios archivos ZIP, abrir una página de administración concreta, instalar paquetes de extensiones de PHP o iniciar sesión automáticamente.
Coloca artifacts y build-command en jobs.build.with, dentro de .github/workflows/pr-preview-build.yml:
jobs:
build:
uses: WordPress/action-wp-playground-pr-preview/.github/workflows/preview-build.yml@v4
with:
artifacts: my-plugin=build/my-plugin.zip
php-version: '8.2'
build-command: |
set -euo pipefail
composer install --no-dev --optimize-autoloader --no-interaction
mkdir -p build/my-plugin
rsync -a --delete \
--exclude='.git' \
--exclude='.github' \
--exclude='build' \
./ build/my-plugin/
( cd build && zip -qr my-plugin.zip my-plugin )
Después, coloca blueprint en jobs.publish.with, dentro de .github/workflows/pr-preview-publish.yml:
jobs:
publish:
permissions:
contents: write
pull-requests: write
uses: WordPress/action-wp-playground-pr-preview/.github/workflows/preview-publish.yml@v4
with:
blueprint: |
{
"$schema": "https://playground.wordpress.net/blueprint-schema.json",
"landingPage": "/wp-admin/admin.php?page=my-plugin",
"steps": [
{ "step": "login", "username": "admin", "password": "password" },
{
"step": "installPlugin",
"pluginData": {
"resource": "url",
"url": "{{ARTIFACT_URL:my-plugin}}"
},
"options": { "activate": true }
}
]
}
{{ARTIFACT_URL:my-plugin}} se sustituye por la URL pública del ZIP correspondiente. El nombre debe coincidir con el lado izquierdo de la entrada correspondiente de artifacts.
Para un ZIP de tema, usa installTheme con themeData. Los Blueprints personalizados deben usar pluginData o themeData para cumplir con el esquema actual de Blueprints; los campos antiguos pluginZipFile y themeZipFile están obsoletos.
Para un monorepositorio con varios plugins o temas, añade una entrada de artifacts por ZIP y referencia cada uno con {{ARTIFACT_URL:<name>}} en el Blueprint.
Ubicación del botón y plantillas
De forma predeterminada, la acción actualiza la descripción de la PR (mode: append-to-description). Para publicar como comentario:
with:
plugin-path: .
mode: comment
github-token: ${{ secrets.GITHUB_TOKEN }}
En la configuración con compilación, pasa mode: comment a preview-publish.yml.
Personaliza la descripción de la PR con description-template:
with:
plugin-path: .
description-template: |
### Test this PR in WordPress Playground
{{PLAYGROUND_BUTTON}}
**Branch:** {{PR_HEAD_REF}} · **Plugin:** `{{PLUGIN_SLUG}}`
github-token: ${{ secrets.GITHUB_TOKEN }}
Las variables disponibles incluyen {{PLAYGROUND_BUTTON}}, {{PLAYGROUND_URL}}, {{PR_NUMBER}}, {{PR_TITLE}}, {{PR_HEAD_REF}}, {{PLUGIN_SLUG}} y {{THEME_SLUG}}.
La acción restaura el botón si se elimina de la descripción de la PR. Para evitar que se restaure:
with:
plugin-path: .
restore-button-if-removed: false
github-token: ${{ secrets.GITHUB_TOKEN }}
Lista de comprobación para usar un agente de programación
Si pides a un LLM o a un agente de programación que añada vistas previas de PR a un repositorio, indícale que examine el repositorio antes de elegir una configuración.
Prompt sugerido:
Añade WordPress/action-wp-playground-pr-preview@v4 a este repositorio.
Primero comprueba si el plugin o tema de WordPress puede funcionar directamente con los archivos del repositorio o si la CI debe generar archivos antes.
Si no se necesita compilar, añade un flujo de trabajo pull_request con plugin-path o theme-path.
Si se necesita compilar, añade la configuración con los dos flujos preview-build.yml / preview-publish.yml.
Usa la configuración funcional más pequeña. Conserva la CI existente. No uses pull_request_target.
Después de editar, verifica que build-command cree realmente cada ruta de artefacto indicada en artifacts:.
Al revisar el resultado, comprueba que:
- Se referencia
secrets.GITHUB_TOKEN, pero no se crea manualmente. - La acción directa aparece en
jobs.<job_id>.steps[].uses. - Los flujos de trabajo reutilizables aparecen en
jobs.<job_id>.uses. - Los flujos de compilación y publicación usan la misma versión, por ejemplo,
@v4. - Cada entrada de
artifactstiene el formatoname=path/to/file.zip, y el comando de compilación crea el ZIP exactamente en esa ruta. - Los ZIP de plugins y temas se extraen en carpetas con el nombre del slug, y no directamente en archivos en la raíz.
- El flujo de trabajo no usa
pull_request_target.
Resolución de problemas
Error Invalid workflow file o jobs.<id>.uses: Comprueba si usas la acción directa o un flujo de trabajo reutilizable. WordPress/action-wp-playground-pr-preview@v4 debe ir en jobs.<job_id>.steps[].uses. WordPress/action-wp-playground-pr-preview/.github/workflows/preview-build.yml@v4 y preview-publish.yml@v4 deben ir en jobs.<job_id>.uses.
El flujo de publicación muestra startup_failure sin registros: El flujo de publicación reutilizable necesita contents: write y pull-requests: write. Concede esos permisos al job de publicación mediante un bloque permissions: de nivel superior que herede el job, o mediante jobs.publish.permissions:. El ejemplo anterior incluye ambos para que los cambios posteriores no reduzcan accidentalmente los permisos del job de publicación.
El botón no aparece: El archivo del flujo de trabajo debe existir en la rama predeterminada antes de ejecutarse en las PR. Comprueba si hay errores en la pestaña Actions y confirma que el flujo que llama a la acción concede pull-requests: write.
Resource not accessible by integration: El flujo que llama a la acción no puede escribir en la pull request. Para PR del mismo repositorio, añade permissions: pull-requests: write. Para PR de forks públicos, usa la configuración con dos flujos de trabajo y compilación.
El botón aparece, pero la vista previa no carga o devuelve 404: Para flujos con artefactos compilados, comprueba que la compilación haya subido el ZIP esperado y que la versión ci-artifacts sea una versión preliminar, no un borrador. Las nuevas configuraciones v4 crean una versión preliminar automáticamente, pero las versiones antiguas en borrador pueden necesitar una conversión inicial.
El plugin necesita archivos de Composer o de una compilación con npm y aparece vacío: Probablemente el flujo usa plugin-path: directamente. Esa ruta utiliza git:directory, por lo que Playground recibe los archivos del repositorio sin ejecutar un paso de compilación. Cambia a la configuración con compilación.
El plugin o tema no aparece después de instalarlo: Comprueba la estructura del ZIP. Los ZIP de plugins y temas deben extraerse en una carpeta con el nombre del slug, como my-plugin/my-plugin.php, y no directamente en archivos en la raíz.
git diff origin/$GITHUB_BASE_REF...HEAD falla con «no merge base»: El checkout predeterminado tiene un historial limitado. Define fetch-depth: 0 en el parámetro del flujo de compilación reutilizable.
plugin-path o theme-path apunta a un directorio vacío: La ruta es relativa a la raíz del repositorio, no al archivo del flujo de trabajo. Usa . para plugins o temas en la raíz, o una ruta como plugins/my-plugin para subdirectorios.
La vista previa falla con código de salida 255 en PHP.run() y sin stderr: Suele indicar un error fatal durante la activación del plugin, a menudo por dependencias de Composer que faltan. Cambia a la configuración con compilación o comprueba qué genera tu build-command. El flujo de compilación registra la salida de unzip -l para el artefacto final.
Más información en la documentación de action-wp-playground-pr-preview.
Otras formas de previsualizar un repositorio Git
Ejemplos
- Ejemplos de action-wp-playground-pr-preview - Repositorios que usan los flujos de trabajo v4
- WordPress/blueprints - Vistas previas de Blueprints
Próximos pasos
- Añade contenido de demostración (guía)
- Crea Blueprints personalizados (documentación)