GitHub Actions PR Previews for Moodle Plugins and Core

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 required — the entire Moodle instance runs inside WebAssembly in the reviewer’s browser. This page is a task-focused how-to. For the full input/output reference see the Action Reference.

Minimal setup

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

Add the workflow file

Create .github/workflows/pr-preview.yml in your plugin repository with the following content:

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

Push and open a PR

Commit and push the file. On the next opened or updated pull request, the action automatically appends a preview button to the PR description.

Click to preview

Reviewers click Open in Moodle Playground in the PR description. The browser boots a full Moodle instance with the plugin installed from the PR branch — no setup required on their end.

Always pin the action to @v1. This keeps your workflow stable across action releases.

The action detects the plugin type and name from the repository name using the moodle-TYPE_NAME convention — for example, moodle-mod_board becomes type mod, name board. It then 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, uses:) identical to the minimal example above.

Plugin in a subdirectory

Point plugin-path at the plugin directory when it is not at the repository root:

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

Inline blueprint

Provide a blueprint as a JSON string directly in the workflow. 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 as a preceding step:

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

For blueprint-file, any installMoodlePlugin or installTheme GitHub archive URL that points at this repository is automatically rewritten to the PR branch, so reviewers test the PR code and not the base branch.

Blueprint from a URL

Link to a remote blueprint file. The generated preview link uses a ?blueprint-url= query parameter rather than inlining the blueprint content:

        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 CORS-enabled GitHub proxy endpoint instead of inlining it:

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

The proxy must be a CORS-enabled endpoint that returns a single repository file. Using proxy-url together with blueprint-file keeps the preview link short regardless of blueprint size.

Comment vs. description mode

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

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

Comment mode is useful when you do not want to modify the PR description, or when the description is managed by another tool. The action creates or updates a single comment per PR so repeated runs do not flood the comment thread.

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 Moodle version is inferred automatically from the PR target branch — for example, MOODLE_404_STABLE maps to 4.4. Override the inferred version with the base-version input if needed.

Core overlays replace whole files only and are capped at 80 files and 256 KiB per file by default; binary files are skipped. There is no Composer install, asset build, or full database upgrade, so fidelity is lower than a real core build. Use core overlays for quick visual and behavioral review, not deep testing.

Required permissions

The job must grant both contents: read and pull-requests: write so the action can read the repository and post or update the preview button:

    permissions:
      contents: read
      pull-requests: write

github-token defaults to the workflow’s built-in GITHUB_TOKEN. Passing ${{ secrets.GITHUB_TOKEN }} explicitly is recommended for clarity and auditability.

Limitations

Ephemeral runtime. The preview holds no data after the tab closes. It is intended for review, not persistent storage.
Outbound network. Plugin, theme, and language pack downloads happen entirely in the browser. Firefox and Safari cannot make outbound calls from WASM PHP, so Chromium-based browsers are the most reliable 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. The branch must exist on the remote — it cannot be a purely local branch.
Core overlay fidelity. Overlays are subject to the caps and exclusions described in the warning above.
SQLite only. The playground uses an experimental PDO driver patch for SQLite — this is not full production parity with MySQL or PostgreSQL.

Common errors

Symptom	Cause and fix
`Resource not accessible by integration`	The job is missing `pull-requests: write`. Add it to the `permissions` block.
Plugin missing in the preview	The PR branch is not on the remote. The install URL requires the pushed branch — push it before opening the PR.
HTTP 414 (URL too long)	The inline blueprint is too large. Use `blueprint-url`, or `blueprint-file` with `proxy-url` to avoid embedding the blueprint in the URL.
Core overlay incomplete	Hitting the overlay caps (file count, size limit, or skipped binaries) or a missing database upgrade. Reduce the changeset size or test those parts locally.

Action Reference

Full inputs and outputs tables for action-moodle-playground-pr-preview@v1.

Blueprints Overview

What blueprints can do and the full list of supported steps.

Action Repository

README with advanced options and latest release notes.

Get Started

Blueprints

Integrations

Reference

GitHub Actions PR Previews for Moodle Plugins and Core

Minimal setup

Scenarios

Plugin in a subdirectory

Inline blueprint

Blueprint from a file in the repo

Blueprint from a URL

Large blueprints via a proxy

Comment vs. description mode

Moodle core PR overlay

Required permissions

Limitations

Common errors

See also

Action Reference

Blueprints Overview

Action Repository

Build docs developers (and LLMs) love

Get Started

Blueprints

Integrations

Reference

Documentation Index

​Minimal setup

​Scenarios

​Plugin in a subdirectory

​Inline blueprint

​Blueprint from a file in the repo

​Blueprint from a URL

​Large blueprints via a proxy

​Comment vs. description mode

​Moodle core PR overlay

​Required permissions

​Limitations

​Common errors

​See also

Action Reference

Blueprints Overview

Action Repository

Build docs developers (and LLMs) love

Minimal setup

Scenarios

Plugin in a subdirectory

Inline blueprint

Blueprint from a file in the repo

Blueprint from a URL

Large blueprints via a proxy

Comment vs. description mode

Moodle core PR overlay

Required permissions

Limitations

Common errors

See also