PR previews with GitHub Actions¶

The ateeducacion/action-moodle-playground-pr-preview action posts an Open in Moodle Playground button on every pull request, so reviewers can boot the PR's plugin (or Moodle core changes) in the browser with one click. No checkout, no local Moodle, no server.

This page is a task-focused how-to. For the full input/output list see the Action reference.

Smallest useful workflow¶

For a plugin that lives at the repository root, this is all you need:

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 Moodle Playground preview button
        uses: ateeducacion/action-moodle-playground-pr-preview@v1
        with:
          plugin-path: "."
          github-token: ${{ secrets.GITHUB_TOKEN }}

The action detects the plugin type and name from the repository name (the moodle-TYPE_NAME convention, e.g. moodle-mod_board becomes type mod, name board), builds a blueprint that installs the plugin from the PR branch, and appends the preview button to the PR description.

Scenarios¶

Each snippet below shows only the with: block that changes. Keep the rest of the workflow (trigger, permissions, runs-on) as in the minimal example.

Plugin in a subdirectory¶

Point plugin-path at the plugin directory:

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

Inline blueprint¶

Provide a blueprint as a JSON string. When blueprint is set, plugin-path is ignored:

        with:
          blueprint: |
            {
              "steps": [
                { "step": "installMoodle" },
                { "step": "login", "username": "admin" }
              ]
            }
          github-token: ${{ secrets.GITHUB_TOKEN }}

Blueprint from a file in the repo¶

Use blueprint-file to read a JSON file from the checked-out repository. This requires actions/checkout first:

    steps:
      - uses: actions/checkout@v4
      - name: Post Moodle Playground preview button
        uses: ateeducacion/action-moodle-playground-pr-preview@v1
        with:
          blueprint-file: ".github/preview.blueprint.json"
          github-token: ${{ secrets.GITHUB_TOKEN }}

Blueprint from a URL¶

Link to a remote blueprint. The preview link uses ?blueprint-url=:

        with:
          blueprint-url: "https://example.com/preview.blueprint.json"
          github-token: ${{ secrets.GITHUB_TOKEN }}

Large blueprints via a proxy¶

Long inline blueprints can exceed URL limits and fail with HTTP 414. Serve the blueprint through a GitHub proxy (a CORS-enabled endpoint that returns one repo file) instead of inlining it:

        with:
          blueprint-file: ".github/preview.blueprint.json"
          proxy-url: "https://your-github-proxy.example.com"
          github-token: ${{ secrets.GITHUB_TOKEN }}

Comment vs. description¶

By default the button is appended to the PR description (mode: append-to-description). To post it as a comment instead:

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

Moodle core PR overlay¶

To preview changes to Moodle core (not a plugin), set preview-type: core. The action boots a prebuilt base for the target branch and overlays the PR's changed files at runtime — no per-PR bundle is built:

        with:
          preview-type: "core"
          github-token: ${{ secrets.GITHUB_TOKEN }}

The base version is inferred from the target branch (for example MOODLE_404_STABLE maps to 4.4). Override it with base-version if needed.

Required permissions¶

The job must grant:

    permissions:
      contents: read
      pull-requests: write

github-token defaults to the workflow's GITHUB_TOKEN; passing ${{ secrets.GITHUB_TOKEN }} explicitly is recommended for clarity.

Limitations¶

• Ephemeral runtime. The preview holds no data after the tab closes — it is for review, not storage.
• Outbound network. Plugin/theme/language downloads happen in the browser; Firefox and Safari cannot make outbound calls from WASM PHP, so Chromium is the most reliable browser for previews. A proxy may be needed for ZIP fetches.
• Branch must be pushed. The plugin install URL points at the PR's remote branch, so the branch has to exist on the remote (not just locally).
• Core overlay fidelity. See the warning above.
• SQLite via an experimental PDO driver patch — not full production parity.

Common errors¶

See also¶

• Action reference — full inputs and outputs tables.
• Blueprints overview — what blueprints can do.
• Action repository — README with advanced options.