livecodes - SKILL.md Agent Skill

name: livecodes/gh-action description: > Use the "Preview in LiveCodes" GitHub Action to generate preview playground links for pull request code changes. Automates playground creation and PR comments. type: composition library: livecodes library_version: 0.13.0 requires: [] sources: - live-codes/preview-in-livecodes:README.md - live-codes/livecodes:docs/docs/gh-action.mdx

LiveCodes — GitHub Action: Preview in LiveCodes

The Preview in LiveCodes GitHub Action generates preview links to LiveCodes playgrounds for code changes in pull requests and posts them as PR comments.

Use case: Library authors can preview changes in the playground before merging PRs.

How It Works

PR is created or updated
Action optionally installs dependencies and builds the project
Action scans .livecodes/ folder for playground configurations
Generates playground URLs with your new code
Posts comment with preview links to the PR

Setup

Two Required Workflow Files

The action requires two workflow files that must be merged to the default branch first.

1. Trigger workflow .github/workflows/livecodes-preview.yml:

name: livecodes

on: [pull_request]

jobs:
  build_and_prepare:
    runs-on: ubuntu-latest
    name: Generate Playgrounds
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Build and generate
        uses: live-codes/preview-in-livecodes@v1
        with:
          # Optional: install-command: "npm install"
          # Optional: build-command: "npm run build"
          # Optional: base-url: "https://{{LC::REF}}.my-project.pages.dev"

2. Comment workflow .github/workflows/livecodes-post-comment.yml:

name: comment

on:
  workflow_run:
    workflows: ['livecodes']
    types:
      - completed

jobs:
  upload:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    if: >
      github.event.workflow_run.event == 'pull_request' &&
      github.event.workflow_run.conclusion == 'success'
    steps:
      - uses: live-codes/pr-comment-from-artifact@v1
        with:
          GITHUB_TOKEN: ${{ github.token }}

Two separate workflows are needed because each runs in a different security context. See GitHub security article for details.

Action Inputs

Input	Required	Description
`install-command`	No	Install command (e.g., `npm install`)
`build-command`	No	Build command (e.g., `npm run build`)
`base-url`	No	Base URL for deployed assets. Supports dynamic values.
`artifact`	No	Artifact name (default: `pr`)
`GITHUB_TOKEN`	No	GitHub token (default: `${{ github.token }}`)

Action Outputs

Output	Description
`message`	Markdown message with preview links for PR comment

Configure Playgrounds

Create JSON files in .livecodes/ folder. Each file becomes a playground link.

Example Configure Project JSON

.livecodes/hello-world.json:

{
  "title": "JavaScript Starter",
  "markup": {
    "language": "html",
    "content": "<h1>Hello, World!</h1>"
  },
  "script": {
    "language": "javascript",
    "content": "import { demo } from 'my-lib';\n\ndemo();"
  },
  "imports": {
    "my-lib": "{{LC::TO_DATA_URL(./index.js)}}"
  }
}

The title property becomes the playground name in the message. If omitted, filename is used.

Dynamic Values

Use these placeholders in project JSON and base-url:

Placeholder	Description
`{{LC::REF}}`	Branch or tag name of PR head
`{{LC::SHA}}`	Full commit SHA
`{{LC::SHORT_SHA}}`	Short SHA (first 7 characters)
`{{LC::PR}}`	Pull request number
`{{LC::REPO}}`	Repository name

File Placeholders (project JSON only)

Placeholder	Description
`{{LC::TO_URL(./file.js)}}`	URL of file with `base-url` prepended
`{{LC::TO_DATA_URL(./file.js)}}`	File converted to data URL (for small files)

Using Newly Added Code in Playgrounds

Three strategies to make PR code available to playgrounds:

1. Deploy to Preview URL (Recommended)

Use Cloudflare Pages or Netlify for automatic preview deployments.

# workflow
base-url: 'https://{{LC::REF}}.my-project.pages.dev'

In project JSON:

{
  "imports": {
    "my-lib": "{{LC::TO_URL(./dist/index.js)}}"
  }
}

2. Use CDN Mirroring GitHub

Link to files via jsDelivr or similar:

# workflow
base-url: 'https://cdn.jsdelivr.net/gh/{{LC::REPO}}@{{LC::SHA}}/'

3. Data URLs (Small Files Only)

Encode files directly. Stored at dpaste.com (limit: 1M chars, expires after 365 days).

{
  "imports": {
    "my-lib": "{{LC::TO_DATA_URL(./index.js)}}"
  }
}

Common Mistakes

HIGH Workflow files not on default branch

The workflow files must be merged to the default branch (e.g., main) before the action can be triggered by PRs.

Wrong:

# Creating PR with workflow files
# Action won't run until merged to default branch

Correct:

# First merge workflow files to default branch
git checkout main
git merge feature/add-gh-action
git push

# Now PRs can trigger the action

Source: GitHub Actions documentation on workflow_run event

MEDIUM Missing permissions for PR comments

The comment workflow needs pull-requests: write permission.

jobs:
  upload:
    permissions:
      pull-requests: write # Required!

MEDIUM Using data URLs for large files

Data URLs are limited to ~1M characters at dpaste.com. Large builds will fail.

Wrong:

{
  "imports": {
    "my-lib": "{{LC::TO_DATA_URL(./dist/bundle.js)}}" // Too large!
  }
}

Correct:

# Use base-url and TO_URL for large files
base-url: 'https://{{LC::REF}}.my-project.pages.dev'

Example PR Comment Output

## Preview in LiveCodes

**Latest commit:** abc1234  
**Last updated:** Jan 15, 2024 3pm (UTC)

|   Playground   | Link                                                               |
| :------------: | ------------------------------------------------------------------ |
| **JavaScript** | [https://livecodes.io?x=code/...](https://livecodes.io?x=code/...) |
|   **React**    | [https://livecodes.io?x=code/...](https://livecodes.io?x=code/...) |

See [documentations](https://github.com/live-codes/preview-in-livecodes) for usage instructions.

Related Skills

import-export - Understanding project configuration objects
self-hosting - Using custom appUrl for self-hosted playgrounds