GitHub PR checks
Connect a repository and verify the exact pull request commit with browser and code results reported to GitHub.
Pulse runs published Checks on SiteOS runners and reports results to GitHub. Browser Checks test a deployed preview for the exact PR head commit. Code Checks test the exact source snapshot and do not need a preview. Neither requires GitHub Actions.
Connect the repository
- In the intended Organization, open Services → GitHub → Connect GitHub (see Share GitHub repositories). Complete GitHub consent and install SiteOs - Pulse on the selected repositories if needed. Explicitly connect the verified installation; installing the App alone does not connect SiteOS.
- Open the Project environment, then Pulse → Settings → Pull requests, also reachable through Configure checks on the Pull requests page. Under Repository & deployments, choose the repository, target branch and application directory. Production and Staging can have different bindings.
- Click Find deployments in GitHub to discover reported environments and URLs. Choose a suggestion for PR previews or website test updates, then review the draft. You can also enter the settings directly.
- For browser Checks, set the GitHub deployment environment and a Preview hostname dedicated to this Project, such as
*.preview.acme.comorwebsite-*-acme.vercel.app. When Preview URLs change per deployment, use a pattern limited to this project. The preview must be reachable by the runner. Leave both preview fields empty for code-only checks. - Save the repository settings and publish the reviewed Checks. Under Checks to run, choose the selection and turn on Run automatically. A Check must be published, active and eligible. Checks that require Project environment variables or Secrets are unavailable for PRs.
The Use published configuration option follows the participation recorded in the published Check configuration. The Choose checks here option keeps a custom selection for this environment after later publications. Repository and Check settings save independently. Publishing a Check version or connecting GitHub does not enable automatic checks by itself.
Trigger and verify the first result
Open or update a PR within the same repository. Code Checks start from the PR event. Browser Checks wait for a ready Preview of that exact head commit.
Pulse reads readiness through GitHub and verifies the repository, branch, current PR head and allowed URL. A successful Deployment Status must identify:
- The exact source commit deployed for the PR.
- The configured deployment environment.
- An HTTPS preview URL matching the allowed hostname.
A build success or ordinary commit status alone is insufficient. Hosting providers that already report this evidence need no extra connection or build step. For other systems, add the notification described below.
Use relative Playwright navigation so checks run against that preview rather than a hard-coded production URL; Website checks shows an example. A browser preview is not required when the selected checks are code-only.
Open the attempt in Pulse → Pull requests. Confirm the head commit, selected Checks, target URL where applicable and final result. Then check GitHub's Checks and the updating Pulse comment from the SiteOS GitHub App, which lists each Check's result and duration with report links. A new head commit needs its own evidence; a previous commit's pass does not verify the new version.
Waiting Browser checks on open PRs already known to Pulse are retried through GitHub, including when the Preview was ready before the PR opened or a webhook was missed. Lookups are bounded and spaced at least one minute apart per PR. Older PRs never observed by Pulse still need an update. Polling does not rerun completed checks, and a local pass or manual pulse run does not publish a PR verification result.
Report deployments from another build system
If your hosting integration does not create GitHub Deployments, run this once after successful publication:
Use SiteOS CLI 3.0.0 or newer for github deployment report. Your build supplies GH_TOKEN or GITHUB_TOKEN from its secret store, with Deployments: write for this repository. No SiteOS login or hosting token is required. The command records an already published deployment; it does not build or deploy the website.
Use the full source SHA actually shipped and a unique ID for each publication. Retry the same publication with the same ID, and serialize its notifications. For a production release or rollback, omit --preview, select the corresponding environment and report the website's canonical URL after traffic has switched. Each new publication gets a new ID, even when its SHA is unchanged. Existing deployment automation must ignore the siteos-pulse task unless it handles these reports. GitHub Actions is optional; the command works in any build system that can run the CLI.
See tracking in browser checks
When Trace is set up for the same Project environment, browser Checks on a PR also note which tracking events the preview sends to SiteOS Analytics, Google Analytics, Google Ads, Meta Pixel, HubSpot and the data layer, by name only. Once every Check has finished, Trace compares them with your tracking plan, with what production sent in the last 7 days and with what the same Checks sent on the last merged pull request.
The GitHub Check adds an advisory Tracking section only when something changed: a planned property that is missing or has another type, an event the Checks sent on the last merged pull request but not now, or an event that is new to both production and that pull request. The section then also lists planned events that need a consent the Checks never gave and events the Checks did not reach. When tracking is unchanged, there is no section. It never changes the Check's result, and values never leave the test browser.
If Trace uses the SiteOS Cookie banner as its consent source, passing browser Checks also run a short consent pass: up to three pages the Checks visited open again in a fresh browser, once with Accept all and once with Reject all. Events sent after Accept all are compared like the rest, and a Google Analytics, Google Ads, Meta Pixel or HubSpot tag that still sends after Reject all is flagged. Google Analytics cookieless Consent Mode pings are expected. The pass takes at most 60 seconds within the Check's timeout, counts toward its run time, and never records consent receipts in your Cookie reports.
SiteOS Analytics only runs on your website's own addresses, so test visits to previews never count as traffic. The Tracking section says so in one line rather than listing its events as not reached.
Understand the execution boundary
Browser runs use each Check's active published version in SiteOS, not test changes from the pull request. Code runs use the exact PR source with the command configuration you published. The PR cannot silently replace that trusted command configuration. Code and browser results appear as separate GitHub Checks.
Same-repository PRs are supported. Fork PRs and Project Secrets are not supported for PR execution. Up to ten selected Checks run in one attempt; there is no daily PR count quota. Budget, concurrency and eligibility still apply. See Usage & limits.
PR outcomes do not change live monitoring incidents. Pausing scheduled monitoring does not disable automatic PR checks. Enable required checks in branch protection only after a real run has produced the expected result. GitHub names them SiteOS Pulse / <Project name> / <environment> / Browser or / Code; use the exact names GitHub shows for your Project environment.
Configure with the CLI or an agent
On the Pull requests page, Set up PR checks with AI copies a prompt with the selected Organization, Project, environment and saved settings. After selecting the intended Project and environment, inspect the current binding and policy:
Save a reviewed binding with siteos project repository save --input binding.json --json. When editing, use the current binding ID as revision. The binding selects the installation, repository, branch, directory and browser preview requirements where applicable; omit both preview fields for code-only checks. Ask your agent to read the current command contract before preparing the file.
For a policy that follows repository participation, the editable settings are:
Save the reviewed file using siteos pulse pull-requests policy save --input policy.json --json. For a custom selection, set useRepositoryChecks to false and provide exact Check IDs from the selected environment. This does not change schedules. MCP can read the repository binding, Check eligibility and saved PR attempts; the CLI handles these configuration writes.
Share repository access deliberately
In Services → GitHub → Manage resources, use Add repositories through my GitHub to select repositories accessible to both your account and the SiteOS GitHub App. A GitHub administrator may need to grant App access first.
Several managers can contribute repositories to one SiteOS Organization. The same App installation can serve multiple Organizations with independent selections. Refreshing the catalog does not automatically share newly accessible repositories, and changing one Organization's selection does not change another's.
A connected repository still needs an explicit Project environment binding, published Checks and an enabled PR policy.