# Pull request configuration

Choose when pull request tests run, select a preview source, and configure shared test settings.

Set up Verify to test your app when a GitHub pull request changes. Choose when a test run starts and where Verify finds the version of your app to test.

A **preview** is a running copy of your app with the pull request's changes. Verify needs a working preview link before it can open a browser and test those changes.

This guide covers GitHub pull requests. For GitLab merge requests, use the [GitLab setup guide](/docs/verify/source-control/gitlab).

## Before you start

You need:

- Administrator access to your Composal organization, with Verify enabled.
- A GitHub repository connected to your project. On **PR Testing**, use **Add GitHub Repository** if it is missing.
- Saved [Scenarios](/docs/verification#expectations-as-code): the tests Verify can choose from for each change.
- A Verify environment in the same project. This holds the test setup, including people to test as, login credentials, and safety settings.

Open **Verify → your project → PR Testing**. Choose the **Source Repository** you want to configure. Each project saves its own PR testing configuration.

The screenshots show the real settings page in a local example project. Replace the example names with your own project, environment, and deployment settings.

## How a pull request is tested

1. A GitHub event, a manual request, or your workflow starts verification.
2. Verify checks the changes. It can skip changes you have explicitly excluded, such as documentation-only edits.
3. Verify waits for a preview from the source you choose below.
4. Verify selects saved Scenarios related to the changes and runs them in a browser using the chosen environment's test setup.
5. A results comment appears on the PR with links to the run, findings, and recordings. The optional GitHub check reports the outcome.

The preview must contain the changes being tested. A working link to an older version of your app is not enough.

## Choose when to run

**Run Triggers** controls which GitHub events can start a run. You can turn on several triggers.

Choose the events that should start testing. The main switch pauses automatic runs.

| Setting | When it starts a run |
| --- | --- |
| **On every push** | When a PR opens, reopens, or gets new commits. |
| **When a PR is ready for review** | When someone changes a draft PR to ready for review. |
| **When a label is added** | When someone adds the label you enter, such as `qa`. |
| **On a comment command** | When a repository owner, member, or collaborator posts `/qa`, `/verify`, or `/composal-verify` as the whole comment. |

Push and ready-for-review triggers are on by default. Label and comment-command triggers are off by default. Draft PRs wait until they are ready for review.

Turning off the main **Run Triggers** switch pauses automatic requests. You can still request runs manually or from your workflow.

A comment command requests a run. The **PR Comments** preview source below supplies the link that a requested run will test.

## Choose a preview source

Choose the option that matches how your team deploys previews. You only need one preview source.



## Choose the test setup

The **Verify Environment** holds the setup the browser needs: who to test as, login credentials, and safety settings.

For **GitHub Deployment**, **Composal Preview**, and **PR Comments**, choose an **external environment template** in the same project. Verify uses its setup for each new preview URL. For **Your CI**, choose the environment that defines your test setup; the workflow supplies the ready preview.

If the list is empty, open your project's **Environments** page and add one first. Save test logins in [Credentials](/docs/verify/credentials), and check that the browser can reach your preview. Private apps may also need [private-network access](/docs/verify/private-networks).

In **Advanced Settings**, you can exclude paths that need no browser testing and change the run's time budget. A PR is skipped for path exclusions only when every changed path matches. Browser parallelism follows your organization's limit.

## Save the settings and try a PR

1. Choose **Save Settings**. The page shows **All changes saved** when it is done.
2. In **Verify a PR**, enter the number of an open, ready-for-review PR.
3. Choose **Verify PR** and follow the run to see whether it is waiting, testing, or finished.
4. Open the results comment on GitHub to review the outcome and links to findings and recordings.

Save edits before starting a manual run. Switching repositories or leaving the page warns you about unsaved changes.

Keep **GitHub Check** on if you want Verify to report a merge check. To make that check block merging, require **Composal Verify** in GitHub branch protection. See [merge protection setup](/docs/verify/source-control/github#results). If you turn the check off, the results comment and run history remain available.

## If a run is waiting for a preview

Open your preview source guide above for the checks specific to your deployment setup.

If no matching preview arrives within one hour, the run is blocked. Fix the preview setup, then request a new run. An accepted workflow step or a reachable preview URL alone does not mean the tests passed; read the run's final outcome.

Continue with [GitHub Actions and CLI instructions](/docs/verify/source-control/github), [writing Scenarios](/docs/verification#expectations-as-code), or [setting up test credentials](/docs/verify/credentials).