Make a trigger rule

You make a trigger rule in a project, test it against the last seven days, and save it. From then on it starts, stops, pauses or messages runs when GitHub, Linear or a schedule says so.

Before you start

• Turn on Triggers in Settings > Experimental features. See Turn triggers on.
• For a GitHub rule, save a GitHub token. See Settings.
• For a Linear rule, save a Linear key in Settings > Linear.

Make a rule

1. Open the rules.

   Open Triggers in the sidebar, or the trigger rules section of a project’s page.

   

   A project's page lists the rules that belong to it.

2. Start a rule.

   Choose New rule. Or start from a ready-made rule: “Review every new pull request”, “Improve the codebase every weekday morning” or “Stop the run when its Linear issue is cancelled”.

3. Name the rule and pick what sets it off.

   Give the rule a name. Then pick its source and the event it waits for. Sources and events shows the events for each source.

4. Pick what the rule does.

   Choose whether it starts a run, or stops, pauses or messages runs. To start a run, choose the workflow and write its goal. You can also pick the harness and model. What a rule does lists the values the goal can use.

5. Add conditions if you need them.

   Under “Only if”, add the conditions that narrow the rule down. See Conditions.

6. Try it and save.

   Choose Try it and save. Orbital looks back over the last seven days and reports what the rule would have done. Saving turns the rule on.

Caution

A saved rule acts on its own. It can start, stop or pause runs without you pressing anything. Read what Try it and save reports before you rely on the rule.

Sources and events

GitHub

A GitHub rule sets off “When a pull request or issue changes”. Choose issues, pull requests or both, and the event: opened, closed, reopened, labelled, unlabelled, assigned, unassigned, or a review requested.

Pick pull requests, issues or both, then the event.

Linear

A Linear rule sets off “When a Linear issue changes”. Choose the event: created, moved to another state, handed to someone else, or a label added or removed.

Pick the change to the Linear issue that sets the rule off.

Schedule

A schedule rule sets off “At set times, such as every weekday morning.” Under “How often?”, pick a preset, choose “Pick days and a time” and select the days and time, or write a cron expression. It uses the time zone of the machine that runs Orbital. A schedule can only start runs.

The dialog lists the next times the rule will fire.

Follow a rule

The rules list shows whether each rule is on and when Orbital last checked. It also shows what the rule did, such as “Started a run” or “Fired 2 times in the last 7 days”.

A rule that cannot check its source says why, for example that GitHub or Linear refused the saved token.

Related

• Triggers: sources, actions, goal values and conditions.
• Review pull requests: a complete rule, from start to finish.
• Start a run: what a started run does.
• Permissions: what a run asks you before its agent acts, on each harness.
• Troubleshooting: fixes for a rule that does not fire.