Production Deploy Commit Lag and Divergence Gate

This Actor compares the commit that a production site serves with the head of its git release branch. It tells you three things for each site:

• Does production serve the head of the branch?
• If not, for how long has production lagged?
• Does production serve a commit that is not on the branch?

It works for any public site that exposes its build commit, on Vercel, Netlify, Cloudflare Pages, GitHub Pages or any other host. It gives one pass or fail gate for all sites, so a CI job or an agent can trust production before it continues.

The Actor is HTTP only. It uses no browser, no proxy and no database.

When to run it

• On a schedule, for example every 15 minutes. The lag clock needs more than one run.
• From a post-merge CI job, to confirm that the merge reached production.
• At the start of an agent session, before the agent trusts that production matches main.

How it works

For each site, the Actor does these steps:

1. It reads the build identifier from the live site with the build_id_locator. It reads 7 to 40 hex characters.
2. It reads the branch head from the git ref advertisement of the remote (<repo_url>/info/refs?service=git-upload-pack). The read stops after the branch line and never goes past 64 KB. Some large repositories list more than 64 KB of branch names before the target branch. Only for these, the Actor sends one git protocol v2 ls-refs request that asks for the branch only, again under 64 KB. This needs no API token and no API rate limit.
3. It compares the two SHAs. A short live SHA matches when the branch head starts with it.
4. It updates the lag clock in the key-value store.
5. When you give a github_token and the SHAs differ on a github.com remote, it makes one GitHub compare call. This gives the relation and the commits-behind count.
6. It writes one dataset record with the verdict. For a breach or a divergence, it sends one alert to your webhook.

At the end it writes one summary record with the gate result.

Input

Field	Required	Default	Description
sites	Yes	One public demo site	1 to 50 items. Each item has site_url, repo_url, branch (default main) and build_id_locator.
max_lag_minutes	No	30	A mismatch older than this value is a breach. 1 to 10080.
github_token	No	none	A read-only token. The Actor sends it only to api.github.com, for the compare call. Without it, commits_behind is null for a site that does not match.
alert_webhook_url	No	empty	One public HTTPS URL. The Actor sends one JSON POST for each breach or divergence.

The four locator forms

There are no regular expressions. Each form reads 7 to 40 hex characters at the start of the value, or directly after the prefix.

Form	Example	Where the Actor reads
json	{"type": "json", "url": "/version.json", "key": "commit"}	The text value at key in the JSON document. A dotted key such as git.sha reads a nested value.
meta	{"type": "meta", "name": "git-sha"}	The content of <meta name="git-sha"> on site_url.
header	{"type": "header", "name": "x-commit-sha"}	The response header of site_url.
asset	{"type": "asset", "url": "/app.js", "prefix": "build:"}	The text directly after the first occurrence of the fixed prefix in the asset.

A relative url is resolved against site_url.

Example input:

{
  "sites": [
    {
      "site_url": "https://www.example.com/",
      "repo_url": "https://github.com/example/website",
      "branch": "main",
      "build_id_locator": {"type": "json", "url": "/version.json", "key": "commit"}
    }
  ],
  "max_lag_minutes": 30,
  "alert_webhook_url": "https://hooks.example.com/deploy-gate"
}

Most hosts do not publish a build commit by default. Add one at build time, for example write VERCEL_GIT_COMMIT_SHA, COMMIT_REF (Netlify), CF_PAGES_COMMIT_SHA or GITHUB_SHA into /version.json or into a meta tag.

The default input checks the public forum of the Discourse project. The forum writes its commit into its generator meta tag, and the project deploys the public tests-passed branch.

Output

One record for each site

Field	Description
live_sha	The SHA that production serves, or null.
branch_head_sha	The head SHA of the branch, or null.
match	True when the branch head starts with the live SHA. Null when one SHA is missing.
commits_behind	The number of branch commits that production does not have. 0 for a match. Null without a token, or when the compare call gives no answer.
relation	identical, behind, diverged, ahead or unknown.
head_first_seen_at	The time the Actor first saw the current branch head.
lag_minutes	The time since the Actor first saw the current branch head while production did not match it. 0 for a match.
verdict	See the table below.
alert_status, alert_error	The result of the webhook POST, when one was sent.
note	The reason for a missing value.

Verdict	Meaning	Gate
in-sync	Production serves the branch head.	Pass
lagging	Production does not match, and the lag is not more than max_lag_minutes.	Pass
breach	Production does not match, and the lag is more than max_lag_minutes.	Fail
diverged	Production serves a commit that is not on the branch (relation diverged or ahead).	Fail
locator-missing	The Actor could not read a build identifier from the site.	Fail
head-unreadable	The Actor could not read the branch head from the git remote.	Fail

The contract names the first five verdicts. head-unreadable is added so that a wrong repo_url or branch is not reported as a missing locator.

One summary record

site_count, in_sync_count, lagging_count, breach_count, diverged_count, locator_missing_count, head_unreadable_count and gate_pass. gate_pass is true only when every site is in-sync or lagging.

The run ends SUCCEEDED for every verdict. A failed gate is a dataset result and a status message, not a failed run.

The lag clock

The Actor keeps one record for each site in the named key-value store production-deploy-commit-lag-state. The record holds the last branch head SHA, the time the Actor first saw it, and the time since when production has not matched it. A named store stays after the run ends, so the clock continues from one scheduled run to the next.

• The first run that sees a new head starts the clock. A first run with a mismatch reports lagging with a lag of 0.
• A new branch head restarts the clock.
• A match stops the clock.

Pricing

This Actor uses pay-per-event pricing.

Event	Unit	Price (USD)	When it is charged
run-started	one Actor run	0.002	Once for each run, after the input is valid and before the first request.
site-checked	one site build identifier compared with one branch head in one run	0.001	For each site where the Actor read both the live SHA and the branch head. A locator-missing or head-unreadable site is not charged.
lag-breach-flagged	one site that lags past max_lag_minutes or serves a diverged commit	0.01	For each site with the verdict breach or diverged, in each run that finds it.

The default maximum total charge for one run is USD 1.00. When a run reaches the maximum total charge, the Actor starts no more sites and lists them in sites_not_checked.

Examples

Case	Runs	Sites per run	Breaches per run	Cost per run (USD)	Total (USD)
3 sites every 15 minutes for one day, no breach	96	3	0	0.005	0.48
3 sites every 15 minutes for one day, 1 breach in each run	96	3	1	0.015	1.44
One post-merge CI call for 10 sites, no breach	1	10	0	0.012	0.012
One run of 50 sites with a breach on every site	1	50	50	0.552	0.552

The largest run that the input allows costs USD 0.552, which is less than the default maximum total charge of USD 1.00.

Safety and limits

• Only HTTPS. URLs with credentials are refused.
• Every request target, and every redirect hop, is checked. A loopback, private or reserved address is refused.
• At most 3 redirects. The GitHub compare call, the git ls-refs request and the webhook POST follow no redirect.
• The locator read stops at 256 KB, the ref read at 64 KB, the compare answer at 100 KB.
• Each request has a 15 s timeout and a 25 s deadline. At most 5 sites are checked at the same time.
• The token goes only to api.github.com and is never written to the dataset or the log.

Scope

The Actor compares one build identifier with one branch head. It does not check preview deployments, cache headers, DNS or workflow runs.