Scheduled execution

The repository ships a scheduled workflow that runs the executor on a cron. It is the recommended way to keep watches running, because it needs no server.

What the job does

pnpm run-due

Loads every watch, skips the ones that are not due, runs the rest, and exits. Each run is a fresh process: everything it needs comes from the database and the environment.

Configuration

1. Add the secrets the run needs to your CI provider’s secret store:

   Secret	Purpose
   Google API key	The model that evaluates conditions (also embeddings)
   MongoDB URI	All state
   Telegram bot token and chat id	Alert delivery
   Tavily API key (optional)	search sources and better page extraction
   Groq API key (optional)	The second-opinion model
   Jina API key (optional)	Higher limits on the reader tier
   Config encryption key (optional)	So the job can use keys managed in the panel
   Firebase service account (optional)	Push delivery

2. Check the schedule. The shipped workflow runs hourly in UTC. Every run still honours each watch’s own cron, so one workflow serves watches with many different schedules.

3. Allow-list the runners if your database restricts access by IP.

4. Confirm overlap protection. The workflow is configured so a slow run does not have another started on top of it.

Choosing a frequency

Run the job	When
Hourly	The sensible default for most watches
Every 15–30 minutes	You have time-sensitive watches and CI minutes to spare
Daily	Slow-moving subjects; also the cheapest

Remember the resolution rule: a watch is checked at the slower of its own cron and the job’s cron. Making a watch’s cron faster than the job achieves nothing. See Scheduling.

CI minutes are a real budget

Each run installs dependencies and executes — call it a couple of minutes. Hourly is roughly 1,500 minutes a month, which fits inside common free allowances but does not leave room for much else. Slow down the cron before you run out.

Reading the output

Ran 4 watch(es) from MongoDB

• framework-releases: nothing-new (collected 10, fresh 0, sent 0)
• product-restock: notified (collected 1, fresh 1, sent 1)
• security-advisories: skipped (not due)
• portal-notices: collection-failed (collected 0, fresh 0, sent 0)
    ↳ source page https://example.gov/notices skipped: Page fetch failed (503 …)

• One line per watch, with its outcome and counts.
• Skipped sources are printed underneath the watch they belong to.
• The job exits non-zero if any watch failed with a real error. A model that merely could not produce a valid verdict is reported as transient and does not fail the job.

Manual runs

The workflow accepts a manual trigger with a force toggle, which ignores due-filtering and runs every enabled watch. Use it after changing a watch, or to confirm the pipeline works after a configuration change.

Failure visibility

A crashed run, or any watch whose sources all failed, produces a ⚠️ health alert to your admin chat — so you do not have to watch the job’s logs. See Monitoring.

Scheduled jobs get disabled

Many CI providers disable scheduled workflows on repositories with no recent activity. If alerts stop arriving for no obvious reason, check that the schedule is still enabled before debugging anything else.

Running it elsewhere

Nothing about the executor is CI-specific. Any scheduler that can run a command with environment variables works: a cron entry on a VPS, a container scheduled task, or a serverless scheduler invoking the same command.