View as Markdown

Routines

A routine starts an AI agent task for you when something happens: a pull request opens, CI fails, a comment contains a command, a schedule fires, or your own system calls a webhook. You write it as one YAML or JSON document.

A routine can also start in two other ways. Connect another system: give it the webhook URL. Start it yourself: Run now (web app, CLI, API). The same limits apply to both. See Custom webhooks and Run now.

Agent hint

Defaults that surprise people, with the page that explains each:

  • A routine already skips drafts, forks, other bots and Forkline’s own activity (draft, fork, bots, self default to exclude). bots and self judge the actor, not the author of the pull request: to skip bot-written pull requests use when: '!pr.authorIsBot' (on GitLab that works only when the merge request is first opened). See Filters.
  • limits.maxRunsPerPr defaults to 3 per pull request and never resets, so a pr.updated review stops after three runs unless you raise it (at most 50). See Concurrency and limits.
  • A ci.failed run may belong to no pull request: add when: 'pr.number != null' when you need one. See Events.
  • concurrency is optional. Without it, a new event for the same pull request or issue replaces the older run, while pushes, schedules, Run now and custom webhooks skip while a run is active. See Concurrency and limits.
  • Every filter and every template variable must exist for every listed event. A when field needs only one listed event that carries it; on the others it is null (guard with pr.number != null && ...). See Spec reference.

Note: Routines are an experimental feature. This documentation is only visible in development mode.

name: review-prs
on:
  events: [pr.opened, pr.updated]
repositories:
  include: all
filters:
  branches:
    include: [main]
agent:
  prompt: |
    Review pull request #{{ pr.number }} "{{ pr.title }}" in {{ repository.fullName }}.

How routines work

Event arrives -> repository selected? -> filters pass? -> `when` is true? -> task starts
  1. Forkline receives an event from your git provider and turns it into one normalized shape, the same on GitHub, GitLab and Forgejo.
  2. Only your own published routines for that repository are considered. An event that matches no routine does no work.
  3. Each routine’s filters run in a fixed order. The first one that fails ends the run for that routine, and the reason is logged.
  4. The prompt is rendered from a template and an agent task starts on the repository. Forkline’s own bot never triggers a routine by default, so a routine cannot start itself in a loop.

Not every event that reaches a routine starts a task. The same delivery is handled once, the routine’s concurrency rule and limits can skip or replace a run, and every event gets a run record with the outcome and the reason, so you can always see why nothing happened.

Routines vs built-in automations

Forkline also has built-in automations that you switch on per repository or account: CI auto-fix, merge-conflict auto-fix, automatic pull request review, and @forkline mention commands. Routines are separate from them. Routines do not replace the built-ins, and the built-ins do not read your routine files.

  • Built-ins are settings with fixed behavior, for example the CI auto-fix attempt limit and its collected failure logs.
  • Routines are your own rules in a file: you choose the events, filters, prompt and limits, and you can test them before they run.

If a built-in automation and a routine react to the same event, both run. For example, with CI auto-fix on and a routine on ci.failed for the same repository, a failed CI run starts two tasks. Forkline does not merge them and does not pick one. To avoid double work, turn the built-in off for that repository (repository automation settings) or narrow the routine with filters and repository selection. The publish dialog warns when a built-in may run on the same events.

Pages

Next steps