GitHub Action PR Preview¶

The erseco/action-facturascripts-playground-pr-preview action automatically posts or updates a sticky comment on a pull request with a live preview link to FacturaScripts Playground.

What it does¶

When added to a PR workflow, the action:

Builds a blueprint.json from the inputs you provide.
Encodes it as base64url and appends it as ?blueprint-data=… to the playground URL.
Posts (or updates) a sticky comment on the PR with the preview link.

This lets reviewers open the plugin or extension being proposed in a real FacturaScripts instance directly from the PR — no local setup required.

When to use it¶

Use this action in any repository that ships a FacturaScripts plugin or extension. Add it to a workflow that triggers on pull_request events so every PR automatically gets a playground preview.

Required permissions¶

The calling workflow must grant write access to pull requests:

permissions:
  contents: read
  pull-requests: write

Minimum required workflow¶

name: PR Preview

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - name: Add FacturaScripts Playground preview
        uses: erseco/action-facturascripts-playground-pr-preview@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          zip-url: https://github.com/${{ github.repository }}/archive/refs/heads/${{ github.head_ref }}.zip

zip-url points to the ZIP of the branch under review. The action installs that ZIP as a plugin inside the playground.

Advanced workflow¶

The action accepts optional inputs that extend the generated blueprint. All optional inputs map directly to the fields described in the blueprint.json reference.

name: PR Preview

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - name: Add FacturaScripts Playground preview
        uses: erseco/action-facturascripts-playground-pr-preview@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          zip-url: https://github.com/${{ github.repository }}/archive/refs/heads/${{ github.head_ref }}.zip
          title: My Plugin PR Preview
          description: Preview this PR in FacturaScripts Playground

          # extra plugins loaded alongside the PR zip
          extra-plugins: '["CommandPalette","https://facturascripts.com/plugins/mi-plugin-remoto"]'

          # open a specific page after boot
          landing-page: /AdminPlugins

          # enable PHP error display
          debug-enabled: true

          # site identity
          site-title: FacturaScripts Demo
          site-locale: es_ES
          site-timezone: Europe/Madrid

          # admin credentials
          login-username: admin
          login-password: admin

          # seed demo data
          seed-json: >-
            {"customers":[{"codcliente":"CDEMO1","nombre":"Cliente Demo","cifnif":"12345678Z"}],
             "products":[{"referencia":"SKU-DEMO-001","descripcion":"Producto demo","precio":19.95}]}

          # final override merged last into the blueprint
          blueprint-json: >-
            {"siteOptions":{"timezone":"Europe/Madrid"}}

Inputs reference¶

Input	Required	Description
`github-token`	✅	GitHub token with `pull-requests: write` permission
`zip-url`	✅	URL of the plugin ZIP to load (maps to `plugins[0]` in the blueprint)
`title`	❌	Blueprint `meta.title`
`description`	❌	Blueprint `meta.description`
`author`	❌	Blueprint `meta.author`
`playground-url`	❌	Override the base playground URL
`extra-plugins`	❌	JSON array of additional plugins (maps to `plugins`) — see plugins
`seed-json`	❌	JSON object for `seed` (customers, suppliers, products) — see seed data
`landing-page`	❌	Maps to `landingPage`
`debug-enabled`	❌	Maps to `debug.enabled` (`true`/`false`)
`site-title`	❌	Maps to `siteOptions.title`
`site-locale`	❌	Maps to `siteOptions.locale`
`site-timezone`	❌	Maps to `siteOptions.timezone`
`login-username`	❌	Maps to `login.username`
`login-password`	❌	Maps to `login.password`
`blueprint-json`	❌	JSON object merged last into the blueprint as a final override

Outputs¶

Output	Description
`preview-url`	The full playground preview URL

How the blueprint is built¶

The action generates a blueprint.json from your inputs, encodes it, and passes it to the playground via ?blueprint-data=. For example, the minimum inputs produce:

{
  "meta": {
    "title": "PR Preview",
    "author": "erseco",
    "description": "Preview this PR in FacturaScripts Playground"
  },
  "plugins": [
    "https://github.com/OWNER/REPO/archive/refs/heads/BRANCH.zip"
  ]
}

When optional inputs are provided they are merged in order, with blueprint-json applied last. The resulting URL looks like:

https://erseco.github.io/facturascripts-playground/?blueprint-data=ENCODED_BLUEPRINT

See blueprint.json for a full description of every supported field.