Schedule triggers
Overview
Section titled “Overview”A schedule trigger runs standing instructions you write on a repeating cron schedule, with no triggering event. It works like an API trigger with a clock attached. Each time a scheduled time comes due, Promptless runs your instructions against your docs and connected context sources. It creates suggestions when the docs need an update, and otherwise finishes quietly.
Use a schedule trigger to:
- Check every week that your release notes reflect what shipped.
- Audit a changelog against a release-notes page.
- Sweep for documentation drift that no single event would catch.
Before you start
Section titled “Before you start”- At least one active doc collection and a saved configuration. Promptless drops a scheduled run when either is missing.
- An organization admin role, to create or edit triggers.
- Every repository and context source your instructions name, connected through source control and context sources so Promptless can read them.
Set up a schedule trigger in the dashboard
Section titled “Set up a schedule trigger in the dashboard”-
On the Configuration page, select the Triggers tab.
-
Select Add an automatic or scheduled trigger.
-
Under On a schedule, select A recurring schedule.
-
Under When should Promptless run?, select a preset or enter a five-field cron expression. The help text describes the schedule. For Every 2 hours, it ends with “Runs every 2 hours, on the hour.”
Preset Cron expression Every 2 hours 0 */2 * * *Every day at 9am 0 9 * * *Every weekday at 9am 0 9 * * 1-5Every Monday at 9am 0 9 * * 1First of the month 0 9 1 * * -
Under In which timezone?, select the timezone the schedule runs in. It defaults to UTC.
-
Under What should Promptless do each time?, enter your standing instructions.
-
Select Add trigger.
The schedule runs at its next matching time after you save. Promptless doesn’t run it for times that have already passed.
Set up a schedule trigger in YAML
Section titled “Set up a schedule trigger in YAML”For precise control, add the schedule trigger to the triggers section of your promptless.yaml file:
triggers: weekly-release-notes-check: trigger_type: schedule match: - cron: "0 9 * * 1" timezone: America/Los_Angeles # optional; defaults to UTC instructions: | Compare the changelog in acme/api against docs/release-notes.md and open a suggestion for anything that shipped but isn't documented.The trigger takes these fields:
| Field | Description |
|---|---|
trigger_type | Set to schedule. |
cron | Required. Five-field cron expression inside a match clause. Runs at most once an hour. |
timezone | Optional. IANA timezone name inside a match clause. Defaults to UTC. |
instructions | Required, non-empty. The standing instructions Promptless runs each time. |
instructions sits alongside match, outside any clause, because one set of instructions covers every clause. Each match clause is a cron and timezone pair, and the trigger needs at least one. Add clauses to run the same instructions on several cadences, for example Mondays and Thursdays at 9am:
triggers: twice-weekly-check: trigger_type: schedule match: - cron: "0 9 * * 1" timezone: America/Los_Angeles - cron: "0 9 * * 4" timezone: America/Los_Angeles instructions: | Compare the changelog in acme/api against docs/release-notes.md and open a suggestion for anything that shipped but isn't documented.Write standing instructions
Section titled “Write standing instructions”The standing instructions are the whole job, because no pull request or message describes the work. Name the repositories and files to compare, and say what to open a suggestion for.
Instructions can’t be empty, and they have no maximum length. Promptless trims leading and trailing whitespace.
Cron schedule rules
Section titled “Cron schedule rules”A schedule uses a standard five-field cron expression: minute, hour, day of month, month, and day of week. Promptless rejects six-field expressions that add seconds, and shorthand aliases such as @daily.
A schedule can run at most once an hour. Promptless checks the expression’s actual run times. It rejects any expression that would run more than once in an hour, however the expression is written.
| Accepted | Rejected (too frequent) |
|---|---|
0 9 * * 1 | */5 * * * * |
0 9 * * * | 0,30 * * * * |
0 * * * * | 0-10 * * * * |
0 9,10 * * * | * * * * * |
0 9 1 * * | |
30 2 * * 1-5 |
Timezones and daylight saving
Section titled “Timezones and daylight saving”The timezone is an optional IANA name, such as America/Los_Angeles, and defaults to UTC. A schedule keeps its wall-clock time across daylight-saving changes. A schedule set for 9am local runs at 9am local through both spring-forward and fall-back.
What to expect
Section titled “What to expect”- Promptless skips a missed occurrence. If Promptless is briefly unavailable when a scheduled time passes, it doesn’t run that occurrence later.
- If an earlier run of the same schedule is still in progress, Promptless skips the next occurrence.
- A run that finds nothing worth changing finishes with no suggestion and no notification.
- A scheduled run goes through the same pipeline as every other trigger. Its suggestions follow your policies for publishing and notifications, and a policy rule can target it by its trigger key.
View schedule triggers
Section titled “View schedule triggers”Scheduled runs appear on the Triggers page like any other trigger, labeled as a scheduled run. Each entry shows when the occurrence ran and what it produced.
See also
Section titled “See also”- API triggers, to start documentation work from your own systems
- Notifications, to choose where scheduled runs report
- Triggers, for how triggers work and how to follow what one did
- Configuration Reference, for the full trigger schema