Agregar botones de vista previa de PR con GitHub Actions
La acción de vista previa de PR de Playground agrega un botón de vista previa a tus solicitudes de extracción. Al hacer clic en el botón se inicia Playground con tu plugin o tema instalado desde la rama del PR:
Para opciones de configuración completas y características avanzadas, consulta el README del flujo de trabajo action-wp-playground-pr-preview.
Cómo funciona
La acción se ejecuta en eventos de solicitudes de extracción (abierta, actualizada, editada). Puede actualizar la descripción del PR con un botón de vista previa o publicar el botón como un comentario.
Configuración básica para plugins
Para plugins sin un paso de compilación, 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:
- name: Post Playground Preview Button
uses: WordPress/action-wp-playground-pr-preview@v2
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
mode: 'append-to-description'
plugin-path: .
La configuración plugin-path: . apunta a tu directorio de plugin. Para subdirectorios como plugins/my-plugin, usa plugin-path: plugins/my-plugin.
Consulta adamziel/preview-in-playground-button-plugin-example para ver un ejemplo en vivo de este flujo de trabajo en acción.
Configuración básica para temas
Para temas, usa theme-path en lugar de plugin-path:
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:
github-token: ${{ secrets.GITHUB_TOKEN }}
theme-path: .
Ubicación del botón
Por defecto, la acción actualiza la descripción del PR (mode: append-to-description). Para publicar como un comentario en su lugar:
with:
plugin-path: .
mode: comment
github-token: ${{ secrets.GITHUB_TOKEN }}
La acción envuelve el botón en marcadores HTML y lo actualiza en ejecuciones posteriores. Por defecto, restaura el botón si lo eliminas. Para evitar la restauración:
with:
plugin-path: .
restore-button-if-removed: false
Trabajar con artefactos compilados
Para plugins o temas que requieren compilación, el flujo de trabajo implica compilar el código, exponerlo a través de versiones de GitHub y crear un blueprint que haga referencia a la URL pública.
Ejemplo de flujo de trabajo (consulta la documentación completa):
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:
github-token: ${{ secrets.GITHUB_TOKEN }}
blueprint: ${{ needs.create-blueprint.outputs.blueprint }}
La configuración artifacts-to-keep controla cuántas compilaciones se deben retener por PR. Para temas, cambia installPlugin a installTheme.
Consulta adamziel/preview-in-playground-button-built-artifact-example para ver un ejemplo completo en funcionamiento.
Blueprints personalizados
Usa blueprints para configurar el entorno de Playground. Puedes instalar plugins adicionales, establecer opciones de WordPress, importar contenido o ejecutar PHP personalizado.
Ejemplo instalando tu plugin con WooCommerce:
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:
github-token: ${{ secrets.GITHUB_TOKEN }}
blueprint: ${{ needs.create-blueprint.outputs.blueprint }}
O referencia un blueprint externo:
with:
blueprint-url: https://example.com/path/to/blueprint.json
Consulta la documentación de Blueprints para ver todos los pasos y opciones de configuración disponibles.
Personalización de plantillas
Personaliza el contenido de vista previa usando variables de plantilla:
with:
plugin-path: .
description-template: |
### Test this PR in WordPress Playground
{{PLAYGROUND_BUTTON}}
**Branch:** {{PR_HEAD_REF}}
Variables disponibles: {{PLAYGROUND_BUTTON}}, {{PLUGIN_SLUG}}, {{THEME_SLUG}}, {{PR_NUMBER}}, {{PR_TITLE}}, {{PR_HEAD_REF}}, y más.
Consulta el README del flujo de trabajo para ver la lista completa.
Exposición de artefactos
La acción expose-artifact-on-public-url carga archivos compilados en una sola versión (etiquetada como ci-artifacts por defecto). Cada artefacto obtiene un nombre de archivo único como pr-123-abc1234.zip. Los artefactos antiguos se limpian automáticamente según artifacts-to-keep.
Opciones de configuración: Expose Artifact Inputs
Solución de problemas
El botón no aparece: El archivo de flujo de trabajo debe existir en la rama predeterminada. Verifica la pestaña Actions para ver errores.
La vista previa no se carga: Verifica que la ruta apunte a un directorio válido de plugin/tema. Verifica los registros de compilación para artefactos.
No activado: Verifica la consola del navegador para errores de PHP. Pueden faltar dependencias.
Errores de permisos: Establece permisos a nivel de trabajo.
Más información: README del flujo de trabajo
Ejemplos
- WordPress/blueprints - Vistas previas de blueprint
- adamziel/preview-in-playground-button-plugin-example - Plugin sin compilación
- adamziel/preview-in-playground-button-built-artifact-example - Plugin con compilación
Próximos pasos
- Agregar contenido de demostración (guía)
- Crear blueprints personalizados (documentación)
- Integrar con flujos de trabajo de pruebas
- Personalizar plantillas para revisores