> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revyl.com/llms.txt
> Use this file to discover all available pages before exploring further.
# GitHub
> Preview builds, proof checks, and workflows on every pull request
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:
```bash theme={null}
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
```yaml theme={null}
pr_review:
enabled: true
skip_drafts: true
path_filters: [] # optional globs, e.g. apps/mobile/**
label_filters: [] # optional; prefix a label with ! to exclude
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: # non-secret build environment values
NODE_ENV: production
secrets: # encrypted org build-secret names
- EXPO_TOKEN
caches: # optional; omitted or [] disables caching
- key: ios-derived-data
paths:
- ios/build
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.
`pr_review.builds.*` uses the same `env`, `secrets`, and `caches` shapes as
`build.platforms.*`. Keep plaintext, non-sensitive values in the `env` mapping
and encrypted secret names in `secrets`; a name cannot appear in both. Cache
lists are independent between the two profiles and are never inherited.
The former PR-review syntax `env: [SECRET_NAME]` still loads for compatibility
and is normalized into `secrets`, but it is deprecated. New and updated files
should always use the canonical fields above.
### 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:
```yaml theme={null}
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:
```yaml theme={null}
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` | `[]` | Run when the PR carries a matching label. Prefix a label with `!` to exclude matches; exclusions take precedence. |
| `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](/tests/workflows) 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](/remote-builds/index).
| 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](/remote-builds/toolchains) 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](/builds/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`.
```yaml theme={null}
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:
```bash theme={null}
revyl build upload \
--file path/to/app.apk \
--app "" \
--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](https://github.com/RevylAI/revyl-cli/blob/main/docs/builds/ci-builds.md)
for more upload examples.
## Related
* [Remote Builds](/remote-builds/index) — the build runners behind PR previews
* [Apps](/builds/index) — where preview builds are registered
* [Workflows](/tests/workflows) — build the workflow IDs referenced by `actions.workflows`