Adicionando Botões de Pré-visualização de PR com GitHub Actions
A ação de Pré-visualização de PR do Playground adiciona um botão de pré-visualização aos seus pull requests. Clicar no botão inicia o Playground com seu plugin ou tema instalado a partir da branch do PR:
Para opções de configuração completas e recursos avançados, consulte o README do workflow action-wp-playground-pr-preview.
Como funciona
A ação é executada em eventos de pull request (aberto, atualizado, editado). Ela pode atualizar a descrição do PR com um botão de pré-visualização ou postar o botão como um comentário.
Configuração básica para plugins
Para plugins sem uma etapa de build, 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:
- 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: .
A configuração plugin-path: . aponta para o diretório do seu plugin. Para subdiretórios como plugins/my-plugin, use plugin-path: plugins/my-plugin.
Veja adamziel/preview-in-playground-button-plugin-example para um exemplo ao vivo deste workflow em ação.
Configuração básica para temas
Para temas, use theme-path em vez 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: .
Posicionamento do botão
Por padrão, a ação atualiza a descrição do PR (mode: append-to-description). Para postar como um comentário:
with:
plugin-path: .
mode: comment
github-token: ${{ secrets.GITHUB_TOKEN }}
A ação envolve o botão em marcadores HTML e o atualiza em execuções subsequentes. Por padrão, ela restaura o botão se você o remover. Para evitar a restauração:
with:
plugin-path: .
restore-button-if-removed: false
Trabalhando com artefatos compilados
Para plugins ou temas que requerem compilação, o workflow envolve compilar o código, expô-lo através de releases do GitHub e criar um blueprint que referencia a URL pública.
Exemplo de workflow (veja a documentação 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 }}
A configuração artifacts-to-keep controla quantos builds manter por PR. Para temas, altere installPlugin para installTheme.
Veja adamziel/preview-in-playground-button-built-artifact-example para um exemplo completo funcionando.
Blueprints personalizados
Use blueprints para configurar o ambiente do Playground. Você pode instalar plugins adicionais, definir opções do WordPress, importar conteúdo ou executar PHP personalizado.
Exemplo instalando seu plugin com 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 referencie um blueprint externo:
with:
blueprint-url: https://example.com/path/to/blueprint.json
Consulte a documentação de Blueprints para todos os passos disponíveis e opções de configuração.
Personalização de template
Personalize o conteúdo da pré-visualização usando variáveis de template:
with:
plugin-path: .
description-template: |
### Test this PR in WordPress Playground
{{PLAYGROUND_BUTTON}}
**Branch:** {{PR_HEAD_REF}}
Variáveis disponíveis: {{PLAYGROUND_BUTTON}}, {{PLUGIN_SLUG}}, {{THEME_SLUG}}, {{PR_NUMBER}}, {{PR_TITLE}}, {{PR_HEAD_REF}}, e mais.
Consulte o README do workflow para a lista completa.
Exposição de artefatos
A ação expose-artifact-on-public-url faz upload de arquivos compilados para um único release (marcado como ci-artifacts por padrão). Cada artefato recebe um nome de arquivo único como pr-123-abc1234.zip. Artefatos antigos são automaticamente limpos com base em artifacts-to-keep.
Opções de configuração: Expose Artifact Inputs
Solução de problemas
Botão não aparece: O arquivo de workflow deve existir no branch padrão. Verifique a aba Actions para erros.
Pré-visualização falha ao carregar: Verifique se o caminho aponta para um diretório válido de plugin/tema. Verifique os logs de build para artefatos.
Não ativado: Verifique o console do navegador para erros de PHP. As dependências podem estar faltando.
Erros de permissão: Defina permissões no nível do job.
Mais informações: README do workflow
Exemplos
- WordPress/blueprints - Pré-visualizações de blueprint
- adamziel/preview-in-playground-button-plugin-example - Plugin sem build
- adamziel/preview-in-playground-button-built-artifact-example - Plugin com build
Próximos passos
- Adicionar conteúdo de demonstração (guia)
- Criar blueprints personalizados (documentação)
- Integrar com workflows de testes
- Personalizar templates para revisores