Triggers and scheduling

An AgentWorkflow's triggers say when it runs. Besides a person starting it (Run now, Start a Change, or POST /v1/orgs/<org>/agentworkflowruns), four kinds of trigger start runs on their own:

Trigger	Starts a run when	Needs
event on an issue	An issue on a Product repo is opened or labeled.	The GitHub App's webhook
onChange	A pull request on a Product repo is opened, reopened or gets new commits.	The GitHub App's webhook
event: release.cut	A Release cuts its tag.	Nothing more
cron	A schedule comes due.	The org's scheduled runs switched on

Only enabled AgentWorkflows start. A run always belongs to one Product: the Product whose spec.repos lists the repo the event came from.

Issue events

Event	Fires when
issue.opened	An issue is opened. Issues opened by a bot, including Infrared's own, are skipped.
issue.labeled	An issue gets a label.

A trigger with labels narrows the match. For issue.labeled, the label just added must be in the list; for issue.opened, the issue must carry one of them. Pull requests, which GitHub also reports as issues, are never issue events.

triggers:
  - type: event
    event: issue.labeled
    labels: [needs-hydration]

The catalog's issue hydration AgentWorkflow runs on issue.opened, and again on issue.labeled with needs-hydration.

Pull request triggers

onChange fires when a pull request is opened, reopened or synchronized (new commits pushed to its branch). The run's Change is that pull request.

Filter	Matches when
branches	The pull request's base branch matches one of the globs, such as main or release/*.
labels	The pull request carries one of the labels.

Pull requests from branches named infrared/* are skipped: those are the branches agents work on, already inside a run.

triggers:
  - type: onChange
    branches: [main]

The catalog's Change AgentWorkflow has an onChange trigger with no filters, so while it's enabled every pull request to a Product repo gets reviewed. Switch it off, or add filters, if you want reviews on some pull requests only.

One run at a time per target

An event doesn't start a second run of the same AgentWorkflow for the same issue or pull request while one is still going. New commits on a pull request under review don't pile up runs; the next event after the run finishes starts a fresh one.

Connect the webhook

Issue and pull request triggers need GitHub to send events to Infrared, through the GitHub App the setup wizard created.

1. Infrared needs a public URL. See Expose Infrared over HTTPS.

2. In GitHub, open the App's settings (Settings → Developer settings → GitHub Apps → infrared-<platform org>). Under Webhook, check Active and set the URL:

   https://<host>/api/v1/webhooks/github

   The setup wizard creates the App with the webhook inactive, or without one when you ran the wizard on a private address, so this step is always needed. Keep the webhook secret the App already has: Infrared checks every delivery's X-Hub-Signature-256 against it (the Secret github-app, key webhook-secret, in the org's namespace). If you set a new secret on GitHub, write the same value to that key.

3. Under Permissions & events → Subscribe to events, check Issues and Pull request.

GitHub's Advanced tab on the App lists each delivery and Infrared's response: 202 when the signature matched (whether or not it started a run), 401 when it matched no org's webhook secret.

Release tags

When a Release cuts its tag, Infrared starts every enabled AgentWorkflow in the org with an event: release.cut trigger, once, for that Product and version. The Release records the runs it started in status.cutRuns. See Go-to-market workflows.

Scheduled runs

A cron trigger takes a standard five-field schedule:

triggers:
  - type: cron
    schedule: "0 6 * * *"

At each scheduled time Infrared starts one run per Product in the org (Products with at least one repo). Scheduled runs are off for every org until someone turns them on, because each run spends model tokens.

Turn them on. An org admin opens Settings → Scheduled runs, sets the time zone the schedules are read in (for example America/New_York; empty means UTC) and turns them on. Or:

curl -X PUT https://<host>/api/v1/orgs/<org>/scheduling \
  -H "Authorization: Bearer $INFRARED_TOKEN" -H 'Content-Type: application/json' \
  -d '{"enabled": true, "timeZone": "America/New_York"}'

This sets spec.scheduling on the Organization. Each AgentWorkflow with a cron trigger then shows its schedule and next run in status.schedule and status.nextScheduledAt; while scheduling is off, status.schedule says so.

Infrared catches up at most one missed time: if the control plane was down across several scheduled times, one run starts when it's back. The first time you turn scheduling on, an AgentWorkflow whose last scheduled time has passed since it was created runs right away.

Run now on an AgentWorkflow in Agents starts it immediately whether or not scheduled runs are on.

Merge conflicts in a run

A step's when can be pullRequest.conflicted: true when GitHub reports that the Change's pull request can't merge cleanly into its base branch. The step runs only then, and is Skipped otherwise.

In the catalog's Change (quick) AgentWorkflow, the resolve-conflicts step, after human approval and before the merge, runs the merge conflict resolver under that condition. If the base branch moves again and the merge step finds the pull request conflicted, the run goes back to the latest step before the merge with a pullRequest.conflicted condition and continues from there, up to 3 rounds. After the third, the merge step fails as it would without a resolver. The AgentWorkflowRun counts the rounds in status.conflictRounds.