How to connect AdaptOrch to GitHub pull requests

You wire AdaptOrch into a pull request once, and every AI-generated patch after that gets a verdict before a human reviewer even opens the diff. Instead of pulling a Cursor or Codex branch locally to run tests by hand, connect AdaptOrch to GitHub pull requests so the sandbox run happens automatically on every push and posts a readable receipt as a check.

Why this matters

AI coding agents produce patches fast, and fast patches hide slow-to-spot problems: a test that fails because the sandbox has no network access looks identical, at a glance, to a test that fails because the patch broke the function. Reviewers waste time chasing failures that have nothing to do with the code.

AdaptOrch separates the two by running the before-and-after diff in an isolated sandbox and labeling the result as a real code failure or a runner/environment failure. Wiring that into the pull request means the separation happens the moment a Cursor, Claude Code, or Codex patch lands as a PR, not after someone spends twenty minutes debugging a flaky CI job.

Before you start

• GitHub organization admin access, or repo-level admin rights on every repository you plan to connect - the GitHub App install screen requires this to grant read/write on pull requests and checks.
• A repository where pull requests already run some form of CI (GitHub Actions, or another runner) - AdaptOrch reads the pull_request event and doesn't require you to abandon existing checks.
• The gotcha: GitHub does not pass repository secrets to workflows triggered by pull_request events coming from forks, by design, as of 2026. If your AI agents open PRs from forks rather than branches on the same repo, decide up front whether AdaptOrch runs on pull_request or pull_request_target, because that choice determines whether the sandbox run has access to anything secret-gated at all.

Set up the AdaptOrch GitHub App

1. From your AdaptOrch account, start the GitHub connection flow and you'll land on GitHub's own Install App screen - this is GitHub's screen, not AdaptOrch's, so the labels come from GitHub.
2. Choose Repository access: pick Only select repositories rather than All repositories. Scoping to the repos where AI agents actually open PRs keeps the permission surface small and keeps the check list on unrelated repos clean.
3. Confirm the install. GitHub redirects you back to AdaptOrch with the connection active.
4. Expected result: the connected repositories show up in your AdaptOrch workspace with a status of "connected," and GitHub's own Installed GitHub Apps settings page lists AdaptOrch under your organization.

Choose which repositories to verify

1. In AdaptOrch, open the list of connected repositories and toggle verification on for each one individually - connecting the GitHub App and enabling verification are two separate steps on purpose, so a repo can be connected without every PR triggering a run.
2. If you only want verification on repos where AI agents are doing the committing (rather than every human-authored PR too), keep the toggle off on the rest and revisit later.
3. Expected result: enabled repositories show a green "verification on" indicator; disabled ones stay listed but inactive.

Configure the pull request trigger

1. Set the trigger to run on pull_request opened and pull_request synchronize - opened catches the first commit, synchronize catches every push after that.
2. Decide the fork-PR policy from the gotcha above: run against pull_request for same-repo branches only, or accept the reduced secret access that comes with covering forked PRs.
3. Save the trigger. Expected result: opening a new PR against a connected, verification-enabled repo produces a pending check within moments, then a pass or fail once the sandbox run finishes.

Read the verdict on the PR

1. Open the PR's Checks tab in GitHub. AdaptOrch's check appears alongside any existing CI jobs.
2. Click into the check to open the receipt: a plain-language summary distinguishing a real code failure (the patch broke something) from an environment or runner failure (the sandbox itself had a problem unrelated to the diff).
3. Expected result: a reviewer can skip re-running failed tests manually to figure out which bucket a failure belongs to - the receipt already says so.

Verify pushes to an existing PR branch

This is the adjacent workflow worth setting up alongside the initial connection: re-verification whenever an AI agent pushes a fix commit to a PR that's already open, rather than only on the first commit.

1. Confirm the pull_request synchronize trigger from the step above is still enabled - it's the one that fires on every new push to an open PR.
2. No separate configuration is needed inside AdaptOrch for this; the same sandbox run and receipt format apply to the third push on a PR as to the first.
3. Expected result: each commit posts its own check run, so a reviewer can see the failure-to-pass history across a PR's lifetime instead of just the final state.

For teams running the equivalent flow through Actions rather than relying on the GitHub App's default triggers, the GitHub Actions to verified AI patches workflow covers wiring AdaptOrch as an explicit job step instead. Teams whose patches originate in Cursor specifically should also look at the Cursor to sandbox verification pipeline, which covers the handoff from editor to PR before AdaptOrch ever sees the diff.

Troubleshooting

• The check never shows up on the PR. Verification is likely still toggled off for that repo, or the PR comes from a fork and your trigger is scoped to same-repo pull_request events only.
• A failing AdaptOrch check doesn't block the merge button. Branch protection rules require each check to be explicitly named as required - go to the repo's branch protection settings and add the AdaptOrch check by name.
• The receipt keeps flagging environment failures on a repo with real flaky infrastructure. That's the tool doing its job correctly: repeated environment-failure verdicts on the same repo are a signal to fix the runner, not the patch. See flagging environment failures when Claude Code tests fail for what that pattern usually means.
• Two checks post for the same push. This happens when both the GitHub App trigger and a manually added Actions step call AdaptOrch on the same event - pick one integration path per repo.
• A forked PR's check silently skips secret-gated steps. Expected behavior per the gotcha above, not a bug - either accept the reduced scope on forked PRs or switch to pull_request_target with the tradeoffs that implies.

Customize your workflow

Once the base connection is running, the next step for most teams is separating real regressions from noisy infrastructure at scale rather than PR by PR - the pattern covered in catching flaky tests vs. real bugs. Platform and DevOps teams running this across many repositories in 2026 typically also standardize which trigger policy (fork-safe vs. full-secret) applies org-wide, rather than deciding per repo.

FAQ

One last thing

The fork-secrets behavior isn't an AdaptOrch quirk - it's GitHub's own security model, and it trips up more integrations than just this one. If your team's AI agents open PRs from forks even occasionally, decide the trigger policy before you connect the first repo, not after the first confusing skipped check.

Related guides

• Catching flaky tests vs. real bugs