Pular para o conteúdo principal

Adicionando botões de pré-visualização de PR com GitHub Actions

A ação Playground PR Preview adiciona um botão de pré-visualização aos seus pull requests. Ao clicar no botão, o Playground é iniciado com seu plugin ou tema instalado a partir da branch do PR:

Botão de pré-visualização de PR

Comece pela configuração que corresponde ao seu repositório:

Seu repositórioUse esta configuração
O plugin ou tema funciona diretamente com os arquivos do repositórioSem etapa de compilação
O plugin ou tema precisa executar Composer, npm, Vite ou outro comando de compilação primeiroCom etapa de compilação
PRs de forks públicos precisam de pré-visualizações funcionaisCom etapa de compilação
Repositório privadoA configuração padrão não basta; o Playground precisa de URLs públicas que não exijam autenticação.

Em caso de dúvida, use a configuração sem compilação somente quando os arquivos incluídos no pull request forem exatamente os que o WordPress deve executar. Se a integração contínua (CI) precisar gerar algum arquivo antes, use a configuração com etapa de compilação.

Para consultar todas as opções de configuração, exemplos de uso e tabelas de referência, veja a documentação de action-wp-playground-pr-preview.

Como funciona​

O Playground executa o WordPress no navegador. Tudo o que ele instala, como um ZIP de plugin, um ZIP de tema ou um arquivo WXR, precisa estar disponível em uma URL pública quando alguém clicar no botão de pré-visualização.

A ação usa duas estratégias de URL:

  • git:directory: o Playground busca o repositório na referência do pull request. Use esta opção na configuração sem compilação.
  • Arquivos de versões: a CI gera arquivos ZIP e os envia para um pré-lançamento público chamado ci-artifacts. Use esta opção quando a pré-visualização precisar de dependências do Composer, arquivos gerados pelo npm, recursos compilados ou outros arquivos gerados.

Use a ação e os fluxos de trabalho reutilizáveis em locais diferentes

A ação direta, WordPress/action-wp-playground-pr-preview@v4, é uma ação comum do GitHub. Referencie-a como uma etapa em jobs.<job_id>.steps[].uses.

A configuração com compilação usa os fluxos de trabalho reutilizáveis preview-build.yml@v4 e preview-publish.yml@v4. Referencie-os no nível do job, em jobs.<job_id>.uses.

Sem etapa de compilação​

Use esta configuração quando seu plugin ou tema puder funcionar diretamente com os arquivos do repositório, sem instalar dependências do Composer, executar uma compilação com npm ou processar recursos.

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@v4
with:
plugin-path: .
github-token: ${{ secrets.GITHUB_TOKEN }}

Para um tema, use theme-path: . no lugar de plugin-path: .:

with:
theme-path: .
github-token: ${{ secrets.GITHUB_TOKEN }}

Use um subdiretório quando o plugin ou tema não estiver na raiz do repositório:

with:
plugin-path: plugins/my-plugin
github-token: ${{ secrets.GITHUB_TOKEN }}

Você não precisa criar secrets.GITHUB_TOKEN; o GitHub o fornece automaticamente. O bloco permissions concede ao token o acesso necessário para esta ação.

Abra um pull request. A ação atualiza a descrição do PR com um bloco gerenciado que contém o botão de pré-visualização. Ao clicar nele, o Playground é aberto com seu plugin ou tema instalado e ativado a partir da referência do pull request.

Observação sobre PRs de forks

Esta configuração com um único fluxo de trabalho é mais simples para PRs do mesmo repositório. PRs de forks públicos geralmente recebem um GITHUB_TOKEN somente para leitura, então a ação pode não conseguir editar a descrição do PR. Se as pessoas que contribuem por forks precisarem de pré-visualizações funcionais, use a configuração com etapa de compilação, mesmo que o comando apenas crie um ZIP.

Não altere este fluxo de trabalho para pull_request_target para executar código do PR com permissões de gravação.

Com etapa de compilação​

Use esta configuração quando a pré-visualização precisar de arquivos gerados, como dependências do Composer, pacotes do npm ou Vite, ou outros resultados de compilação. Ela também oferece uma forma segura de disponibilizar pré-visualizações para PRs de forks públicos.

Crie dois arquivos de fluxo de trabalho:

  • Um fluxo de compilação que é executado em pull_request com permissões somente para leitura, executa seu comando de compilação e envia arquivos ZIP como um artefato do GitHub Actions.
  • Um fluxo de publicação que é executado em workflow_run após a compilação ser concluída com sucesso, envia esses ZIPs para uma URL pública de versão, cria um Blueprint e publica o botão de pré-visualização.

Fluxo de compilação​

Crie .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

Em artifacts: my-plugin=build/my-plugin.zip, my-plugin é o nome do artefato e build/my-plugin.zip é o arquivo ZIP que seu build-command deve criar. Ao extrair o ZIP, os arquivos devem ficar em uma pasta com o slug do plugin ou tema, como my-plugin/my-plugin.php, e não diretamente na raiz.

Fluxo de publicação​

Crie .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

Use kind: theme para um único ZIP de tema. Para vários ZIPs ou etapas extras de configuração, use um blueprint: personalizado, como mostrado em Artefatos compilados com um Blueprint personalizado.

Abra um pull request. O fluxo de compilação executa seu comando de compilação. Após a conclusão com sucesso, o fluxo de publicação cria ou atualiza o pré-lançamento ci-artifacts, envia o ZIP gerado e adiciona um botão de pré-visualização à descrição do PR.

Por que dois arquivos de fluxo de trabalho?

O GitHub não permite que um único fluxo de trabalho execute com segurança código não confiável de um PR de fork e grave em versões ou descrições de PRs. O fluxo de compilação executa o código do PR com permissões somente para leitura. O fluxo de publicação é executado depois, a partir da branch padrão, com permissões de gravação, e nunca faz checkout nem executa o código do PR.

Blueprints personalizados​

Use Blueprints para configurar o ambiente do Playground. Você pode instalar plugins complementares, definir opções do WordPress, importar conteúdo, fixar versões do PHP e do WordPress, abrir uma página específica ou entrar com uma conta de administrador.

Para uma pré-visualização sem compilação, forneça um Blueprint completo à ação direta:

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

Ou referencie um Blueprint hospedado:

- uses: WordPress/action-wp-playground-pr-preview@v4
with:
blueprint-url: https://example.com/path/to/blueprint.json
github-token: ${{ secrets.GITHUB_TOKEN }}

Escolha o parâmetro do Blueprint de acordo com a origem do JSON:

  • Use blueprint quando a ação direta ou o fluxo de publicação puder incluir a string JSON completa.
  • Use blueprint-url com a ação direta quando o JSON já estiver hospedado em uma URL pública.
  • Use blueprint-from-build em preview-build.yml junto com blueprint-from-artifact: true em preview-publish.yml quando o fluxo de compilação gerar blueprint.json dinamicamente.

Veja a documentação de Blueprints para consultar todas as etapas e opções de configuração disponíveis.

Artefatos compilados com um Blueprint personalizado​

Use um Blueprint personalizado no fluxo de publicação quando uma pré-visualização compilada precisar de mais do que o comportamento padrão de “instalar e ativar”. Alguns motivos comuns são instalar vários arquivos ZIP, abrir uma página específica do painel, instalar pacotes de extensões PHP ou entrar automaticamente.

Coloque artifacts e build-command em jobs.build.with, no arquivo .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 )

Depois, coloque blueprint em jobs.publish.with, no arquivo .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}} é substituído pela URL pública do ZIP correspondente. O nome deve corresponder ao lado esquerdo da entrada em artifacts.

Para um ZIP de tema, use installTheme com themeData. Blueprints personalizados devem usar pluginData ou themeData para atender ao esquema atual de Blueprints; os campos antigos pluginZipFile e themeZipFile estão obsoletos.

Para um monorepositório com vários plugins ou temas, adicione uma entrada em artifacts para cada ZIP e referencie cada um com {{ARTIFACT_URL:<name>}} no Blueprint.

Posicionamento do botão e modelos​

Por padrão, a ação atualiza a descrição do PR (mode: append-to-description). Para publicar como comentário:

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

Na configuração com compilação, passe mode: comment para preview-publish.yml.

Personalize a descrição do PR com 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 }}

As variáveis disponíveis incluem {{PLAYGROUND_BUTTON}}, {{PLAYGROUND_URL}}, {{PR_NUMBER}}, {{PR_TITLE}}, {{PR_HEAD_REF}}, {{PLUGIN_SLUG}} e {{THEME_SLUG}}.

A ação restaura o botão se ele for removido da descrição do PR. Para impedir a restauração:

with:
plugin-path: .
restore-button-if-removed: false
github-token: ${{ secrets.GITHUB_TOKEN }}

Lista de verificação para usar um agente de programação​

Se você pedir a um LLM ou agente de programação para adicionar pré-visualizações de PR a um repositório, peça que ele examine o repositório antes de escolher uma configuração.

Sugestão de prompt:

Adicione WordPress/action-wp-playground-pr-preview@v4 a este repositório.
Primeiro, verifique se o plugin ou tema WordPress pode funcionar diretamente com os arquivos do repositório ou se a CI precisa gerar arquivos antes.
Se não for necessário compilar, adicione um fluxo de trabalho pull_request usando plugin-path ou theme-path.
Se for necessário compilar, adicione a configuração com os dois fluxos preview-build.yml / preview-publish.yml.
Use a menor configuração funcional. Preserve a CI existente. Não use pull_request_target.
Após a edição, verifique se cada caminho de artefato listado em artifacts: é realmente criado por build-command.

Ao revisar o resultado, verifique se:

  • secrets.GITHUB_TOKEN é referenciado, mas não criado manualmente.
  • A ação direta aparece em jobs.<job_id>.steps[].uses.
  • Os fluxos de trabalho reutilizáveis aparecem em jobs.<job_id>.uses.
  • Os fluxos de compilação e publicação usam a mesma versão, por exemplo, @v4.
  • Cada entrada de artifacts segue o formato name=path/to/file.zip, e o comando de compilação cria o ZIP exatamente nesse caminho.
  • Os ZIPs de plugins e temas são extraídos para pastas com o nome do slug, e não diretamente para arquivos na raiz.
  • O fluxo de trabalho não usa pull_request_target.

Solução de problemas​

Erro Invalid workflow file ou jobs.<id>.uses: Verifique se você está usando a ação direta ou um fluxo de trabalho reutilizável. WordPress/action-wp-playground-pr-preview@v4 deve ficar em jobs.<job_id>.steps[].uses. WordPress/action-wp-playground-pr-preview/.github/workflows/preview-build.yml@v4 e preview-publish.yml@v4 devem ficar em jobs.<job_id>.uses.

O fluxo de publicação apresenta startup_failure sem registros: O fluxo de publicação reutilizável precisa de contents: write e pull-requests: write. Conceda essas permissões ao job de publicação com um bloco permissions: no nível superior, que o job herda, ou com jobs.publish.permissions:. O exemplo acima inclui ambos para evitar que edições posteriores reduzam acidentalmente as permissões do job de publicação.

O botão não aparece: O arquivo do fluxo de trabalho precisa existir na branch padrão antes de ser executado em PRs. Verifique se há erros na aba Actions e confirme que o fluxo que chama a ação concede pull-requests: write.

Resource not accessible by integration: O fluxo que chama a ação não pode gravar no pull request. Para PRs do mesmo repositório, adicione permissions: pull-requests: write. Para PRs de forks públicos, use a configuração com dois fluxos de trabalho e etapa de compilação.

O botão aparece, mas a pré-visualização não carrega ou retorna 404: Para fluxos com artefatos compilados, verifique se a compilação enviou o ZIP esperado e se a versão ci-artifacts é um pré-lançamento, e não um rascunho. Novas configurações v4 criam um pré-lançamento automaticamente, mas versões antigas em rascunho podem precisar ser convertidas uma vez.

O plugin precisa de arquivos do Composer ou de uma compilação com npm e aparece vazio: O fluxo provavelmente usa plugin-path: diretamente. Esse caminho usa git:directory, então o Playground recebe os arquivos do repositório sem executar uma etapa de compilação. Mude para a configuração com compilação.

O plugin ou tema não aparece após a instalação: Verifique a estrutura do ZIP. Os ZIPs de plugins e temas devem ser extraídos para uma pasta com o nome do slug, como my-plugin/my-plugin.php, e não diretamente para arquivos na raiz.

git diff origin/$GITHUB_BASE_REF...HEAD falha com “no merge base”: O checkout padrão tem histórico limitado. Defina fetch-depth: 0 no parâmetro do fluxo de compilação reutilizável.

plugin-path ou theme-path aponta para um diretório vazio: O caminho é relativo à raiz do repositório, não ao arquivo do fluxo de trabalho. Use . para plugins ou temas na raiz, ou um caminho como plugins/my-plugin para subdiretórios.

A pré-visualização falha com código de saída 255 em PHP.run() e sem stderr: Geralmente, isso indica um erro fatal durante a ativação do plugin, muitas vezes por falta de dependências do Composer. Mude para a configuração com compilação ou verifique o que seu build-command produz. O fluxo de compilação registra a saída de unzip -l para o artefato final.

Saiba mais na documentação de action-wp-playground-pr-preview.

Outras formas de pré-visualizar um repositório Git​

Exemplos​

Próximos passos​

  • Adicione conteúdo de demonstração (guia)
  • Crie Blueprints personalizados (documentação)