Search Composal documentation

Search public documentation, commands, and release notes.

Verify guides

Test GitHub pull request previews

Set up browser checks for GitHub pull request previews. Connect a repository, choose a preview source, and review user-journey evidence before merging.

On this page

Prepare a saved test

Start with one user journey that a pull request could break, such as signing in and creating a project. Save its starting conditions, actions, and observable expected outcomes as project Scenarios. Include a test account when the journey needs sign-in. You need administrator access and Verify enabled for the organization to configure PR testing.

Use the Scenario reference for the YAML format and testing authenticated journeys for account setup.

Connect GitHub and the preview

  1. Open your project's PR Testing page and choose Add GitHub Repository. Select the account and repository, or use Manage Access if the repository is missing.
  2. Prepare a ready external environment template with the personas, credential references, and safety policy the PR previews should use.
  3. Select the repository and environment template in PR Testing. Choose the preview source that matches your delivery: a Composal preview, GitHub deployment, or a URL supplied by your CI.
  4. Save the settings and choose which events should trigger a run. Draft PRs wait until they are ready for review.

The GitHub configuration guide covers each preview source, required GitHub App permissions, and the GitHub Action setup. For a preview behind a VPN or firewall, first configure private access.

Verify a pull request

Open or update a PR using an enabled trigger, or choose Verify a PR for an already-open PR. Verify selects relevant saved Scenarios from the PR diff and runs them against the preview for that commit. A waiting preview is a setup dependency; it is not a passing test.

Follow the run from its GitHub results comment or check. Keep the preview available while its browser journeys run. Use the GitHub troubleshooting steps when a preview is missing or a run cannot start.

Review the evidence before merging

Confirm the run belongs to the current PR commit. Inspect the selected journeys, terminal results, recordings, and findings. A green result covers the tests that actually ran, rather than every feature in your app. Resolve failed assertions and distinguish a product failure from a preview or sign-in problem.

Use the results and merge checks guide to configure the checks your team requires. For how verdicts and evidence work, read the Verify agent guide.