Your CI

Choose this when your team already has a workflow that builds and deploys the app. CI means that automated workflow, such as GitHub Actions.

Start on Verify → your project → PR Testing. You need administrator access and a connected GitHub repository. If you have not configured testing yet, follow PR configuration first. The screenshot shows a local example project.

Set it up

1. In Who Builds Your PR Previews?, choose My CI.
2. On Add Composal to Your Workflow, use Copy CI Setup to copy the project-specific workflow step.
3. Add the step after your preview has finished deploying. Supply its ready URL using preview-url.
4. Store the administrator API token in the GitHub secret named COMPOSAL_TOKEN. Keep its value out of your workflow file and logs.
5. Continue to Turn On PR Testing, then push to a PR so your CI sends its first preview. CI can only hand over previews once testing is set up.
6. To check the connection later, choose Previews → Change. Under My CI the page shows Connected. Your CI sent a preview for #N, with how long ago, or that no preview has arrived yet. Check Again reloads it.

What happens next

Your workflow deploys the app and gives Verify its preview link. Verify tests that preview using this project's saved configuration.

Requesting a run with Verify PR, a label, or /composal-verify starts verification but does not supply the preview. The run waits until your workflow sends the ready URL for the commit being tested. Your existing hosting can serve that URL; Composal does not need to host the preview.

Running saved scenarios directly against a preview URL creates a separate run. It does not connect CI, supply the waiting PR run's preview, or attach those results to the PR.

You can also hand over an existing ready Verify environment instead of a URL. For the complete workflow examples, token setup, and supported inputs, see GitHub Actions setup.

The workflow can request verification even when automatic triggers are off. Keep the preview running until the test run and its cleanup finish.

If the preview is not found

Check that the workflow deployed the current PR version and sent its ready URL. Confirm that the Verify step runs after deployment and uses the correct organization, project, and token.

If the PR's head or base commit changes while a run is waiting, the old request can be superseded. Its reason identifies the changed commit and retains the preview wait message. Fix the preview handoff before requesting a fresh run against the current PR commit.

If no matching preview arrives within one hour, the run is blocked. Fix the setup, then request a new run.

Return to PR configuration to turn on testing, try a PR, and configure merge checks.