GitHub PR Previews

The Peach GitHub App attaches a playable preview to each pull request and keeps branch builds available for inspection. A PR-diff-driven agent boots your app in headless Peach, drives the surface your change touched, and posts a single sticky comment with the recording.

PR preview links default to unlisted, including for private GitHub repositories: anyone with the URL can open them without signing in to peach. The preview share menu shows Public link enabled for these links. An authorized owner can turn it off to require account or repository access. See Preview uploads & sharing.

Your repo does not need a provider API key or PEACH_API_KEY. The workflow authenticates with the GitHub installation token, and Peach Cloud owns the agent, model proxy, upload, and PR comment.

PR previews and branch builds require a funded account. The agent runs on Peach’s cloud and model keys, so the automated preview/build flows charge the repo’s account balance. Without available balance or spending-cap room, billable preview work is refused until billing is updated.

Preview a project without a pull request

Sign in with peach login, install your Expo project’s dependencies, then run:

terminal
peach preview ./my-expo-app --open
peach preview ./my-expo-app --platform android --json

Platform defaults to ios.

Peach starts your project’s installed Expo packager with its existing Metro configuration and environment. The hosted build runner captures the app, its assets and a first painted frame, then returns a runnable /preview/<id> link and an artifact receipt. Keep the command running until it returns; Ctrl+C cancels the hosted build and stops its packager and tunnel. Hosted project builds currently require cloud early access for the account you selected at login, plus operator authorization.

For an existing Metro JavaScript bundle, run peach preview ./dist/main.js. Peach discovers and embeds its assets and publishes it through the same build share store. These links open a live app, with no generated walkthrough. The existing account preview upload policy and build billing apply to both inputs.

What lands on the PR

One sticky comment per pull request, updated in place as the run progresses. When the preview is ready it looks like this:

🎬 I generated a 6-step demo flow for you · 14s

The diff touches the checkout sheet, so the flow adds an item and opens checkout to the payment step.

Open the interactive preview → https://peachsim.com/preview/ab-x7k2…

a row of tappable screenshot thumbnails, each opening the recording

The step count and duration are deliberate: a 1-step, 3-second flow reads as thin at a glance instead of hiding behind a generic “Preview” link. The blockquote is the agent’s own one-line reason for the route it chose. Reviewers open the link in any browser: recording, live app, and a scrubbable timeline, nothing to install. Failed and skipped runs update the same comment with the reason and a link to the run logs.

Set up a repo

Install the Peach GitHub App and select the repo. GitHub sends you back to peachsim.com, where you sign in (GitHub sign-in is one click), the repo is connected to your account, and a bootstrap PR opens that adds .github/workflows/sootsim.yml tuned to your repo. Merge it and you are done. If you grant the app every repository instead of selecting some, nothing is pushed: add the workflow by hand to the repos you want previews on.

To write the workflow by hand, add one job that checks out and calls sootbean/soot-preview-action@v1:

name: Peach
on:
push:
pull_request:
types: [opened, synchronize, reopened, ready_for_review]
permissions:
contents: read
pull-requests: write
issues: write
actions: read
jobs:
contrast:
if: ${{ github.event.pull_request.draft != true }}
runs-on: ubuntu-latest
timeout-minutes: 25
steps:
- uses: actions/checkout@v4
- uses: sootbean/soot-preview-action@v1
with:
start: npm run dev # whatever boots your app dev server

The action installs your dependencies, boots the dev server in the background, waits for it to be ready, drives the app, and reports back. On a pull_request it runs the preview agent; on a push to a tracked branch it runs the branch build.

Package manager

The action auto-detects your package manager from the lockfile or the package.json packageManager field and installs with it (npm ci, yarn install --immutable/--frozen-lockfile, pnpm install --frozen-lockfile, or bun install --frozen-lockfile). Override with package-manager: or a custom install: command for a monorepo.

If your workflow already runs its own setup (checkout, Node, install, e.g. a repo ./.github/actions/setup composite), run it before this action and pass package-manager: none so the action skips straight to the preview:

- uses: ./.github/actions/setup # your own composite
- uses: sootbean/soot-preview-action@v1
with:
package-manager: none
start: pnpm dev:all:lite

Fit previews into an existing CI job

Use the existing job when it already checks out the PR, installs the same dependencies, and runs on a machine that can also host the app. Pick placement from the app server’s lifecycle:

  1. 1.
    Parallel: start the preview after install, run independent checks, then wait near the end. This avoids a second install and overlaps wall-clock time, but the preview and tests compete for CPU and memory.
  2. 2.
    Before tests: use the normal action invocation when the preview needs a clean state or its app server would collide with test ports or processes.
  3. 3.
    After tests: use the normal invocation when tests build the artifact or leave the exact staging server the preview needs running. Do not assume a server survives a completed action step unless the workflow deliberately keeps that process alive.
  4. 4.
    Separate job: keep isolation when runner labels, permissions, secrets, process lifetime, or resource limits differ. This repeats checkout and often install, but avoids slowing or destabilizing the main test lane.

Parallel example:

- uses: ./.github/actions/setup
- uses: sootbean/soot-preview-action@v1
with:
phase: start
package-manager: none
start: pnpm dev
- run: pnpm test
- uses: sootbean/soot-preview-action@v1
if: always()
with:
phase: wait

Inputs

inputdefaultdescription
startemptycommand that boots your dev server in the background; leave blank only if the app is already up on port
phaserunrun | start | wait; split start/wait to overlap the preview with other steps in one job
port8081dev server port (Metro/Expo default)
package-managerautoauto | npm | yarn | pnpm | bun | none
installemptyoverride the install command (monorepo filters, etc.)
node-version24Node version installed via actions/setup-node
modeautoauto | preview | build
pr_numberemptyPR number for workflow_dispatch re-runs (${{ inputs.pr_number }}); ignored on PR events
maestroemptyMaestro flow paths to run against the preview bundle, or auto to use the same workspace discovery as peach test
runnerlocalwhere the recording executes: local (your CI runner) or hosted (a Peach GPU recorder)
build-envemptynewline KEY=VALUE pairs baked into the captured bundle (Clerk / API keys); source from ${{ secrets.* }}

Full input list and behavior: the action’s README.

Where the recording runs

The runner input decides where Peach and the recording execute. Your app’s install and dev server always run on your own CI runner either way. The choice is only about the machine that drives and records it.

runner: local runs everything on your workflow’s runner. Nothing leaves your CI beyond the finished upload, and there is no extra plan requirement beyond previews themselves. The trade-off is hardware: standard hosted CI runners have two CPU cores and no GPU, so Peach renders through software. Short recordings and quick flows are fine; longer recordings come out choppy, and on complex apps the recording can slow the interaction itself.

runner: hosted keeps your CI runner serving the dev server and moves the driving and recording to a Peach GPU recorder. Your workflow opens a one-off tunnel for the run, gated by a per-run token so only the assigned recorder can reach your dev server, and tears it down as soon as the run ends. The recorder renders with a real GPU, which is what makes the recording watchably smooth, and heavier Maestro suites do not eat your CI minutes. Hosted recording currently requires separate operator authorization as well as a funded account. Installing the GitHub App or adding balance does not enable it; use runner: local for self-service setup.

Start with local. Once hosted recording is authorized for your workflow, consider hosted for design review, sharing with non-engineers, or flows long enough that software rendering visibly degrades them. If your policy forbids exposing a dev server through any tunnel, even token-gated and per-run, stay on local, because that constraint outranks video quality.

Preview vs build

Peach publishes two share types from GitHub Actions:

typeURLbehavior
PR preview/preview/<id>recording of the changed surface, including bundle, events, storage, captured network data, and snapshots
branch build/build/<owner>/<repo>/<branch>?platform=ioslive configured app build that keeps talking to the endpoint your workflow configured

Keep those modes separate. A recorded PR preview should replay what CI captured; it should not silently fall through to a live backend for missing requests. A branch build is the live inspection mode, so auth and API failures there usually mean the app’s build-time configuration needs work.

What the bot does

For each non-draft PR, the workflow:

  1. 1.
    reads the PR diff;
  2. 2.
    asks Peach Cloud whether the change has an app surface worth previewing (and whether the account is entitled);
  3. 3.
    boots your app and opens it in headless Peach;
  4. 4.
    lets the agent drive the relevant surface while recording, then uploads the bundle, events, storage, snapshots, network replay data, and the recording;
  5. 5.
    verifies the upload is playable (share metadata plus a headless render of the preview page);
  6. 6.
    runs your committed Maestro flows when maestro is set, each uploading its own replay;
  7. 7.
    updates one sticky PR comment with the preview result, the Tests table, and branch build links.

For pushes to configured branches, the build lane uploads the branch build without running the PR agent.

Verify a preview

Failed preview and branch-build capture return a nonzero action exit. Generated workflows preserve that failure in the job. Peach Preview reports the preview outcome, and Peach Tests reports the independent Maestro result. Remove continue-on-error from both the action step and its job in existing workflows so the workflow conclusion reflects the action’s result.

Before treating a preview as ready:

  • +
    read the Peach sticky comment and confirm it says ready, not failed or skipped;
  • +
    open the linked /preview/<id>;
  • +
    confirm the recording loads when present;
  • +
    switch to Live and confirm the app catches up to the recorded point;
  • +
    scrub the timeline and confirm the live app follows without getting stuck;
  • +
    check that the frames show the changed surface, not just a login screen or the starting tab twice;
  • +
    open the branch build link separately when you need live staging data.

Skipped previews are valid for docs-only, CI-only, and backend-only changes. If the PR changed user-visible UI and the bot skipped it, adjust the app map or preview guidance instead of accepting the skip.

Troubleshooting

  • +
    Preview billing refused: the repo’s account needs available balance and spending-cap room. Update Billing, then re-run the PR workflow.
  • +
    Preview skipped on a UI change: the relevance gate judged the diff had no observable short-clip delta. Adjust your preview guidance, or open the contrast-agent-logs artifact on the Actions run to see the decision reason.
  • +
    Boot never became ready: the action waits for port (default 8081). If your dev server binds a different port, set port:; if it needs env to boot, pass it via build-env.
  • +
    Auth failed inside the build: the captured bundle needs a runtime key whose allowed origins include peachsim.com. Bake it in with build-env sourced from a repo secret.
  • +
    Deeper diagnostics: every run uploads a contrast-agent-logs artifact (each probe’s stdout/stderr) to the Actions run page; download it for post-mortems.

Re-running previews

When you need to regenerate history, rerun the original pull request workflow run. That preserves the PR event shape the agent expects:

terminal
gh run rerun <pull_request_run_id> -R owner/repo

Do not use a push run when you need a PR preview; push runs only update branch builds.

Generated workflows also accept a manual dispatch with a PR number, for re-running a preview without pushing an empty commit. Dispatch from the PR’s branch so the run sees the PR’s code:

terminal
gh workflow run sootsim.yml --ref <pr-branch> -f pr_number=<n> -R owner/repo

Do not use workflow_dispatch on a hand-written workflow unless it forwards pr_number to the action; without it the run has no PR context and exits having done nothing.

From a PR comment

Faster than pushing an empty commit. Comment on the PR itself (needs write access to the repo):

  • +
    @peach rerun - re-run the preview for the current head commit
  • +
    @peach rerun and focus on the create-thread flow - re-run with one-off steering for this PR only
  • +
    @peach only run on branches release/* - branch filter, persists per repo
  • +
    @peach skip PRs titled 'chore: …' - title filter, persists per repo
  • +
    @peach remember: this app expects EXPO_OS in env - durable guidance for every future run
  • +
    @peach show settings - print the current filters and guidance
  • +
    @peach help - full command list

Path filters (only run on PRs that touch apps/one/**) skip the run unless one changed file matches. When the changed file list cannot be read, the PR still passes through the relevance gate described above.