GitHub - Revyl Documentation

The Revyl GitHub App connects your repositories to Revyl. Once installed, it can:

Create preview builds for pull requests and post links to runnable preview sessions.
Run proof checks that open the new build, exercise the change, and report what happened.
Run saved workflows automatically against the pull request build.

Connect GitHub

From the terminal, one command connects GitHub, scaffolds the config, and applies it:

revyl github setup

Or run the steps individually:

Command	What it does
`revyl github connect`	Opens the GitHub App install page in your browser and waits for the installation to become active. Already installed → no-op.
`revyl github status`	Shows connection status and repo access.
`revyl github init`	Detects your build setup and scaffolds a `pr_review` block in `.revyl/config.yaml`. Use `--framework expo_ios` etc. to pick explicitly.
`revyl github push`	Uploads your local `.revyl/config.yaml` and applies its `pr_review` block immediately — no commit or merge required.

Prefer the dashboard? Install the app and configure repos under Integrations → GitHub. The settings page shows the equivalent revyl github setup command so you can hand off to the CLI at any point.

Configure PR previews

At minimum, each enabled platform needs a Revyl app, a build command, and an artifact path. You can configure these in the dashboard, through revyl github setup, or as code in a pr_review block. When configured as code, Revyl reads the first matching file, in order: .revyl/config.yaml, .revyl/config.yml, revyl.yml, revyl.yaml. Only the pr_review section is used by the GitHub integration; other sections such as build or hotreload are safe to keep in the same file.

How the config gets applied

On a PR that touches the file: Revyl previews the parsed config in a PR comment so you can review the change before it takes effect.
On the default branch: the file becomes the source of truth. The repo’s settings page shows Managed by .revyl/config.yaml and the UI controls become read-only.
Removing the block (or the file) reverts the repo to UI-managed. The last applied policy is preserved and stays editable in the UI.

Reconciliation is by content hash, so re-pushing an unchanged file is a no-op. If the file fails to parse, the PR comment and settings page show the error instead of silently ignoring it. revyl github push applies your local file without waiting for a merge.

Example

pr_review:
  enabled: true
  skip_drafts: true
  path_filters: []             # optional globs, e.g. apps/mobile/**
  label_filters: []            # optional PR labels, e.g. needs-qa

  actions:
    preview_link: true         # post a running preview session link
    proof_of_changes: false
    workflows: []              # optional saved Revyl workflow IDs

  builds:
    ios:
      enabled: true
      framework: expo_ios
      app: "My App iOS"        # Revyl app name or app id
      root_dir: ./             # app subdirectory for monorepos
      image: ios-macos-26-xcode-26.5   # optional toolchain pin
      build_command: |
        bun install
        bunx expo prebuild --platform ios
        cd ios && pod install
        cd ios && xcodebuild -workspace YourApp.xcworkspace -scheme YourApp -configuration Release -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' -derivedDataPath build ARCHS=arm64
      artifact_path: ios/build/Build/Products/Release-iphonesimulator/*.app
      env: []                  # org secret NAMES the build needs

    android:
      enabled: true
      framework: expo_android
      app: "My App Android"
      build_command: |
        bun install
        bunx expo prebuild --platform android
        cd android && ./gradlew assembleRelease
      artifact_path: android/app/build/outputs/apk/release/*.apk

On every matching pull request, Revyl builds the selected targets, registers the output artifacts, and posts preview links back to GitHub.

Proof of changes

Turn on proof checks when you want Revyl to exercise the pull request build and report whether the change behaves as expected:

pr_review:
  actions:
    proof_of_changes: true
    checks:
      - "App launches to the home screen"
      - "Login with email succeeds"
    system_prompt: "Prefer a short launch-screen smoke proof."

The agent starts a session with the new build, performs the requested checks, and posts the result on the pull request.

Run workflows

Add workflow IDs when you want existing Revyl workflows to run automatically against the pull request build:

pr_review:
  actions:
    workflows:
      - 8dd6f660-4e91-4ac5-b3f1-2a56e2f7f9c7

Workflow results appear alongside the preview build status, so reviewers can see both the runnable build and the automated checks that ran against it.

Top-level fields

Field	Default	Description
`enabled`	`true`	Turns PR automation on. Automation only runs when at least one preview build is configured and all referenced secrets exist.
`preset`	derived	Optional preset for common action combinations.
`skip_drafts`	`true`	Wait until a draft PR is marked ready for review.
`path_filters`	`[]`	Only run when the PR touches a matching glob (e.g. `apps/mobile/**`).
`label_filters`	`[]`	Only run when the PR carries a matching label.
`actions`	—	What Revyl posts and runs on the PR.
`builds`	—	Per-platform preview builds.

Actions

Field	Default	Description
`preview_link`	`true`	Post a link to a running preview session built from the PR.
`proof_of_changes`	`false`	Have the agent exercise the build, verify the change, and attach screenshots as evidence.
`checks`	`[]`	Natural-language assertions verified on the preview build during proof runs.
`system_prompt`	`""`	Extra guidance prepended to proof-of-changes runs.
`workflows`	`[]`	Saved Revyl workflow IDs to run against the preview build.

Builds

Declare a preview build per platform under builds.ios / builds.android. Preview builds run on the same runners as remote builds.

Field	Default	Description
`enabled`	`true`	Turn this platform’s preview build on.
`framework`	by platform	One of `expo_ios`, `expo_android`, `react_native_ios`, `react_native_android`, `native_ios`, `native_android`. Naming a framework gives you a runnable default `build_command` and `artifact_path`.
`app`	—	Revyl app name or ID the builds belong to. Revyl resolves or creates it per platform.
`root_dir`	repo root	Source subdirectory the build runs in (monorepos).
`image`	platform default	Toolchain image key to build on.
`build_command`	framework default	Build command(s), newline-separated for multiple steps.
`artifact_path`	framework default	Glob to the built artifact.
`use_existing_ci`	`false`	Skip Revyl-managed builds and wait for your CI to provide the build instead.
`env`	`[]`	Org secret names (never values) the build needs.

iOS artifacts must be simulator .app bundles; Android artifacts must be installable .apk files (not .aab). See artifact requirements.
env lists secret names only. The secrets must already exist in Revyl (add them under Settings) — missing secrets are reported on the PR instead of running with gaps.
Only declare platforms your repo actually builds.

Generate with AI

In the GitHub setup flow, Generate with AI has your coding agent inspect the repo and write the pr_review block. It produces the same schema documented here.

Use your own CI

Revyl can run the build for you, but it does not have to. If your team already has custom CI, private dependency setup, or a specialized build pipeline, use your own CI as the build step and still keep GitHub previews, proof checks, and workflow runs. There are two common patterns:

Trigger a Revyl remote build from CI when you want Revyl runners but need CI-specific setup or environment variables.
Upload a finished artifact from CI when your pipeline already produces the .app or .apk.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Remote build on Revyl
        env:
          REVYL_API_KEY: ${{ secrets.REVYL_API_KEY }}
          API_URL: ${{ secrets.PREVIEW_API_URL }}
        run: |
          curl -fsSL https://revyl.com/install.sh | sh
          export PATH="$HOME/.revyl/bin:$PATH"
          revyl build --remote --platform ios --env API_URL="$API_URL" --json

Or upload an artifact your CI produced:

revyl build upload \
  --file path/to/app.apk \
  --app "<your-app-id>" \
  --platform android \
  --version "$GITHUB_SHA" \
  --yes

Use this path by setting use_existing_ci: true for the target in your pr_review config or choosing Use your own CI in the dashboard. Revyl will wait for your CI-provided build, then use it for the same preview links, proof checks, and workflow runs. See Building in CI for more upload examples.

Remote Builds — the build runners behind PR previews
Apps — where preview builds are registered
Workflows — build the workflow IDs referenced by actions.workflows

​Connect GitHub

​Configure PR previews

​How the config gets applied

​Example

​Proof of changes

​Run workflows

​Top-level fields

​Actions

​Builds

​Generate with AI

​Use your own CI

​Related