How to Auto-Narrate a GitHub PR Demo in CI

Code review tells you what changed. A narrated video shows you what it does.

The pattern: when a PR opens, CI records a short walkthrough of the preview deployment with an AI voiceover describing the change. The video posts as a PR comment. Reviewers watch a 30-second narrated demo instead of pulling the branch and running it locally.

The workflow

name: Record PR Demo
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  demo:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Wait for preview deployment
        run: sleep 30  # adjust for your deploy provider

      - name: Record narrated demo
        id: record
        uses: Custodia-Admin/pagebolt/ci/action@main
        with:
          api-key: ${{ secrets.PAGEBOLT_API_KEY }}
          preview-url: ${{ steps.deploy.outputs.preview_url }}
          audio-guide: "true"

      - name: Upload demo video
        uses: actions/upload-artifact@v4
        with:
          name: pagebolt-demo-videos
          path: ${{ steps.record.outputs.artifact-dir }}

      - name: Comment on PR
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## PR Demo\n\nNarrated demo recorded — ${{ steps.record.outputs.videos-recorded }} video(s) attached as [workflow artifacts](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}).`
            })

The action records a narrated MP4 of the preview deployment. Videos are attached as GitHub Actions artifacts on the workflow run — click through from the PR comment to download and watch.

Custom narration script

For precise control over what the voiceover says, pass a narration script via a file in the repo:

- name: Record narrated demo
  uses: Custodia-Admin/pagebolt/ci/action@main
  with:
    api-key: ${{ secrets.PAGEBOLT_API_KEY }}
    ai-api-key: ${{ secrets.OPENAI_API_KEY }}
    preview-url: ${{ env.PREVIEW_URL }}
    audio-guide: "true"
    narration-file: ".pagebolt/pr-narration.txt"

# .pagebolt/pr-narration.txt
This PR adds a new onboarding flow. {{1}} The welcome screen now includes
a progress indicator. {{2}} Each step validates inline before advancing. {{3}}
Completion redirects to the dashboard with a success state.

The {{N}} markers sync narration to specific steps in the recorded sequence.

Why this beats async Loom recordings

The typical PR demo workflow: developer records a Loom, uploads it, pastes the link in the PR description. Problems: takes 5–10 minutes, only happens when the developer remembers, goes stale if the branch is rebased.

With CI narration:

• Zero developer time — no one has to record anything
• Always current — re-runs on every push to the branch
• Consistent format — same frame style, same voice, every PR
• Searchable — video is an artifact attached to the PR, not a third-party link

What reviewers see

A PR comment with an inline GIF showing the key interaction, and a link to the full narrated MP4. No branch checkout, no local setup, no "let me pull this and test it."

The friction between "PR opened" and "reviewer understands the change" drops to 30 seconds.

Try it free — 100 requests/month, no credit card. → pagebolt.dev