Check pages on a schedule (hosted runs)
The marketing site changes several times a week, and none of it goes through your pull requests. A hosted run opens the pages of a read-only scenario on Kaloko's own browsers every day or week, takes full-page screenshots in every language and screen size, checks what can be read from the page and shares the run under your name. Nobody has to start the CLI. Hosted runs are part of the Business plan (2,000 loaded pages a month) and Enterprise (10,000).
1. Prepare a read-only scenario
The scenario's steps open pages. To start from the pages themselves:
npx kaloko draft https://example.com/ https://example.com/pricing
2. Schedule it
npx kaloko schedule add --scenario qa/flows/public.yml --env production --every day --at 5
npx kaloko schedule add --scenario qa/flows/public.yml --env production --every week --weekday mon
--at is the hour in UTC. --every manual creates a schedule that runs only when you start it.
Pages behind a gate work too. HTTP Basic credentials of the environment are sent once and kept encrypted. For signed-in pages, a person saves a session with npx kaloko auth save --env production --account member, and the schedule uses it with --account member.
3. Manage it
npx kaloko schedule list # next and last run, pages used this month
npx kaloko schedule run <id> # run it now
npx kaloko schedule pause <id>
npx kaloko schedule resume <id>
npx kaloko schedule remove <id>
Settings → Integrations on kaloko.app shows the same schedules, with the next run and how many health results the last run found new and fixed.
Run after a deploy
A schedule can also start when your site is deployed. Create its trigger URL and secret:
npx kaloko schedule hook <id> # prints the URL and the secret, once
or in Settings → Integrations → Hosted runs → Run after a deploy. Keep the secret in your CI or hosting secrets, never in the repository. A second call makes a new secret and the old one stops working; --remove removes the trigger.
Every call that carries the secret starts the run at the next quarter hour. Calls before the run starts make one run; a call during a walk gets its own run after it. At most 30 calls an hour per schedule are accepted, and each one is in the audit log.
From any CI job, after the deploy step:
curl -fsS -X POST "$KALOKO_HOOK_URL" -H "Authorization: Bearer $KALOKO_HOOK_SECRET"
Vercel. Vercel reports every deployment to GitHub, so a small workflow calls the trigger when production is up. Add the repository secrets KALOKO_HOOK_URL and KALOKO_HOOK_SECRET, then commit .github/workflows/kaloko-after-deploy.yml:
name: Kaloko after deploy
on: deployment_status
jobs:
kaloko:
if: github.event.deployment_status.state == 'success' && github.event.deployment.environment == 'Production'
runs-on: ubuntu-latest
steps:
- run: curl -fsS -X POST "$KALOKO_HOOK_URL" -H "Authorization: Bearer $KALOKO_HOOK_SECRET"
env:
KALOKO_HOOK_URL: ${{ secrets.KALOKO_HOOK_URL }}
KALOKO_HOOK_SECRET: ${{ secrets.KALOKO_HOOK_SECRET }}
Netlify. Site configuration → Notifications → Deploy notifications → Add notification → Outgoing webhook. Event "Deploy succeeded", the trigger URL as the URL, the secret as the "JWS secret token". Kaloko checks Netlify's signature.
Your own sender. Instead of the bearer token you can sign the body: send X-Kaloko-Signature: sha256=<hex>, the HMAC-SHA256 of the request body with the secret as the key.
Read the result
The run appears among the others, compared with the scenario's baseline, with the same canvas, comments and approvals. Checks of selectors, texts, titles and meta tags are decided. Criteria that need the full walk say "not evaluated" and give the reason.
Checks of packs (SEO, accessibility) land in the run's health, not in its verdict. When a run has a new error-level finding compared with the previous one, the schedule tells the scenario's followers, the channels that take "Health got worse" and the health.worse webhook. Each schedule can alert on new errors (the default), on new warnings too, or not at all: in Settings → Integrations → Hosted runs, or with --health-alert error|warning|off on kaloko schedule add. More in Check the health of your app.
Stack steps: many pages of one template
A stack step stands for a family of pages, every product page for example. A hosted run lists its pages from items.urls, items.sitemap or items.robots (gzipped sitemaps and sitemap indexes included). match, exclude, limit and rotate: week work as in kaloko walk, so both pick the same pages in the same week.
Each page is opened once, in the step's first screen size, and read without a screenshot. Checks that need only the page's elements (selectors, texts, titles, meta tags) are decided; the index fields title, H1, description, word count and JSON-LD types are filled in; everything else says "not evaluated" with the reason. The HTTP status of a page stays empty. On the canvas the step is a stack with its index, as after a walk.
A big stack is read over several quarter-hour rounds, at most 150 pages per round. kaloko schedule list and Settings → Integrations show how far it got, and the run is shared once every page has been read. While it runs, Run now, a deploy trigger or a saved change waits for it and starts afterwards; pausing the schedule ends it. One run reads at most 1,000 stack pages, and from the sitemaps at most 5 × limit matching addresses per language (20,000 at most). If a round fails or gets nowhere (a sitemap server that is down), the next round tries again; after three such rounds in a row the run is given up and the schedule waits for its next date.
Sitemaps may live on another host, a CDN for example. Kaloko fetches them without the environment's password or cookies, and only when the name resolves to public addresses, after every redirect too. Pages are opened only on the environment's own addresses; others in the sitemap are left out with a note. match and exclude may be up to 300 characters, without backreferences or lookaround.
A stack with items.variants: hreflang groups the language versions of a page as kaloko walk does: the list, the week's window and the ids come from source_locale, and every other language opens each page's hreflang alternate. Before the pages, the run reads each source page's HTML head for its hreflang. Each such read counts as one page, both in the monthly budget and in the 150 a round reads, so a stack of 100 products in three languages takes 400 pages: 100 reads and 300 pages. A page without its translation is marked in the stack index and counted in HC1005, as after a walk. The reads stay on the environment's own addresses, also after a redirect, and carry the schedule's password or cookies there, the same ones the hosted browser gets. When the hreflang names production while the run walks staging, each alternate's path is opened on the language's staging address. A source page that redirects off the environment is not followed there: unlike kaloko walk, the run reports it as a missing translation (cannot read the page).
One address per language
When the environment has a base_url per language, the hosted run picks it the way kaloko walk does: the language's own address, otherwise default.
environments:
production:
base_url: { default: "https://www.example.com", cs: "https://www.example.cz/cs" }
readonly: true
What hosted runs cannot do
They only open pages and read them. Nothing is clicked, typed, submitted or created, so steps that do more than open a page are left out and named. Native apps, local or private addresses and credentials sent as headers also need the full walk, and so do stack steps that list their pages with crawl, script or file. Edit links from items.resolve are not filled in by hosted runs.
For those, export the schedule as a GitHub Actions workflow that walks the scenario with the full CLI:
npx kaloko schedule export github --scenario qa/flows/checkout.yml --env staging --every week
The workflow names the secrets it needs.
How pages are counted
Every loaded page counts: each step in each language and screen size. A scenario of 10 pages in 2 languages on desktop and mobile loads 40 pages per run, so a daily run uses about 1,200 pages a month.
Each page of a stack counts once, when it is read. A weekly stack of 100 pages in 3 languages uses about 1,300 pages a month. When the month's budget runs out halfway through a stack, the run waits up to a day for more (a new month, a higher limit), then shares the pages read so far and names the rest as not walked.