Ajout de boutons d'aperçu de PR avec GitHub Actions

L'action d'aperçu de PR Playground ajoute un bouton d'aperçu à vos pull requests. Cliquer sur le bouton lance Playground avec votre plugin ou thème installé depuis la branche du PR :

Pour les options de configuration complètes et les fonctionnalités avancées, consultez le README du workflow action-wp-playground-pr-preview.

Comment ça fonctionne

L'action s'exécute sur les événements de pull request (ouvert, mis à jour, édité). Elle peut mettre à jour la description du PR avec un bouton d'aperçu ou publier le bouton sous forme de commentaire.

Configuration de base pour les plugins

Pour les plugins sans étape de build, créez .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: .

Le paramètre plugin-path: . pointe vers le répertoire de votre plugin. Pour les sous-répertoires comme plugins/my-plugin, utilisez plugin-path: plugins/my-plugin.

Consultez adamziel/preview-in-playground-button-plugin-example pour un exemple en direct de ce workflow en action.

Configuration de base pour les thèmes

Pour les thèmes, utilisez theme-path au lieu 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: .

Positionnement du bouton

Par défaut, l'action met à jour la description du PR (mode: append-to-description). Pour publier sous forme de commentaire à la place :

with:
    plugin-path: .
    mode: comment
    github-token: ${{ secrets.GITHUB_TOKEN }}

L'action enveloppe le bouton dans des marqueurs HTML et le met à jour lors des exécutions suivantes. Par défaut, elle restaure le bouton si vous le supprimez. Pour éviter la restauration :

with:
    plugin-path: .
    restore-button-if-removed: false

Travailler avec des artefacts compilés

Pour les plugins ou thèmes nécessitant une compilation, le workflow implique de compiler le code, de l'exposer via les releases GitHub et de créer un blueprint qui référence l'URL publique.

Exemple de workflow (voir la documentation complète) :

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 }}

Le paramètre artifacts-to-keep contrôle combien de builds conserver par PR. Pour les thèmes, changez installPlugin en installTheme.

Consultez adamziel/preview-in-playground-button-built-artifact-example pour un exemple complet fonctionnel.

Blueprints personnalisés

Utilisez les blueprints pour configurer l'environnement Playground. Vous pouvez installer des plugins supplémentaires, définir des options WordPress, importer du contenu ou exécuter du PHP personnalisé.

Exemple d'installation de votre plugin avec 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 }}

Ou référencez un blueprint externe :

with:
    blueprint-url: https://example.com/path/to/blueprint.json

Consultez la documentation des Blueprints pour tous les pas disponibles et les options de configuration.

Personnalisation du template

Personnalisez le contenu de l'aperçu en utilisant des variables de template :

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}}, et plus.

Consultez le README du workflow pour la liste complète.

Exposition des artefacts

L'action expose-artifact-on-public-url télécharge les fichiers compilés vers une seule release (étiquetée ci-artifacts par défaut). Chaque artefact obtient un nom de fichier unique comme pr-123-abc1234.zip. Les anciens artefacts sont automatiquement nettoyés en fonction de artifacts-to-keep.

Options de configuration : Expose Artifact Inputs

Dépannage

Le bouton n'apparaît pas : Le fichier de workflow doit exister sur la branche par défaut. Vérifiez l'onglet Actions pour les erreurs.

L'aperçu ne se charge pas : Vérifiez que le chemin pointe vers un répertoire de plugin/thème valide. Vérifiez les logs de build pour les artefacts.

Non activé : Vérifiez la console du navigateur pour les erreurs PHP. Les dépendances peuvent être manquantes.

Erreurs de permissions : Définissez les permissions au niveau du job.

Plus d'informations : README du workflow

Exemples

• WordPress/blueprints - Aperçus de blueprint
• adamziel/preview-in-playground-button-plugin-example - Plugin sans build
• adamziel/preview-in-playground-button-built-artifact-example - Plugin avec build

Prochaines étapes

• Ajouter du contenu de démonstration (guide)
• Créer des blueprints personnalisés (documentation)
• Intégrer avec les workflows de tests
• Personnaliser les templates pour les réviseurs