GitHub App
Install the App once and every pull request gets a check and a comment, with no workflow file and no token in the repository.
What it is
The GitHub App is the pull-request check without the workflow file. Install it once from Settings → GitHub in the Studio (owners and admins), connect a repository to a project, and every pull request gets a check run named Simulathic and one comment: the same simulated people through the same journeys on the pull request’s build and on production, what got worse, what broke only on the PR, with recordings. Nothing goes in the repository, no workflow and no token.
Draft pull requests wait until they are ready for review. The installation belongs to your workspace; uninstalling the App on GitHub stops the checks, and nothing else changes.
Connecting a repository
Connecting a repository is mostly telling the App how a pull request becomes a URL it can open. There are four ways, one per kind of setup:
| You have | Choose | What starts the check |
|---|---|---|
| Preview deployments (Vercel, Netlify, Cloudflare Pages, Render, any host that reports GitHub deployments) | Preview deployments | The deployment’s success for the PR’s commit. A protected Vercel preview needs the project’s Protection Bypass for Automation secret (Vercel → Settings → Deployment Protection), pasted once. |
| A preview URL per pull request that you build yourselves | A URL pattern | The push, after the minutes you say a deploy takes, once the URL answers. The pattern takes {pr}, {sha} or {branch}, as in https://pr-{pr}.staging.acme.com. |
| One staging site deployed from a branch | One staging site | The push to that branch (a merge, usually), after the deploy’s minutes. The check reports on the pull requests that push merged. |
| A native app | Builds uploaded from CI | The upload of a build for the PR’s commit: CI builds the app and runs simulathic upload, which tags the build with the commit, branch and pull request by itself. The base is the newest uploaded build of the PR’s base branch, so the default branch uploads too. No build within 60 minutes ends the check neutral. |
The same form asks for the production URL the pull request is compared with, whether to run only what the change reaches (see below), and which severity of finding fails the check besides a regression: high (the default), medium, or never.
- run: curl -fsSL https://app.simulathic.com/cli/install.sh | sh
- run: ~/.simulathic/cli/simulathic upload build/MyApp.appWhat runs
Every journey on every device your visitors use, unless the repository is set to run only what the pull request can reach: the changed files are matched to pages and endpoints, and each journey runs or is skipped with a one-line reason. That matching knows the Next.js app router today; other frameworks run everything, and in doubt everything runs. Journeys written for the change, every way a person reaches the touched page crossed with the controls the change touches, run on top. The plan is on the check run and in the comment.
Journeys written from the code
A connected repository gets its journeys from its code. The App reads the UI sources at the commit, in memory and never stored, and a model writes the screens and the journeys a careful tester would run, each with the text that proves it worked. That is more accurate than a map explored by clicking, and it covers every screen and control rather than what the explorer happened to reach.
It reads a Next.js app, whose route files name the pages, or a Vite / React Router app, where the pages come from the routes the code declares: <Route path>, createBrowserRouter, the v7 routes.ts or app/routes/ files. The app may live in a subdirectory of a larger repository (frontend/ next to backend/); a file too large to read whole is read as the lines it renders. A staging-site repository’s map is saved under the staging origin too, where its checks run.
A native app’s map is written when the repository is connected (once a build has named the app) and on every push to the default branch. A web app’s is written when the repository is connected and its origin has no map yet, or only the explorer’s, untouched, and again on production deployments that changed a UI source. A journey the code still has keeps its name from one map to the next, so a check reads against the last one.
A map someone edited or pinned is kept. On the Simulate page, Write them from the code asks for the code map when you want it, and the set before it stays restorable. A journey you add to a code map or rewrite is yours: it stays on top through every later map from the code, and one you remove stays out. The map treats the stored sign-in as your own test account: its own content may be published, archived and deleted and its own features used; money, the account itself, other people and the session are never touched. Mapping with the explorer (simulathic map, or map_product from a coding agent) remains the way in without a repository.
On the pull request
A check run named Simulathic: queued, in progress, then success, failure or neutral. Branch protection can require it. And one comment, edited in place on later pushes: the verdict, each journey on base and on the PR per device, new defects with evidence and a fix prompt where the cause is clear, and links to the recordings.
| Comment | What it does |
|---|---|
/simulathic rerun | Runs the last check again. |
/simulathic all | Runs every journey, whatever the repository’s policy. |
Re-running from GitHub’s Checks tab works too. Both need write access to the repository, nothing more.
Reading results elsewhere
The Studio’s Overview lists the checks the App started alongside the rest. From a coding agent, list_checks, get_check and check_comment work the same; their source is github-app.