Automations
An automation is a graph of nodes that reacts to an event, a schedule, or a button press, and then changes issues, notifies people, or creates work. This page covers how to build one, run it, and read what it did.
Open Settings → Automations to see every automation on the server. Each row shows its name, the trigger or triggers it runs on, how many action nodes it holds, and an Enabled checkbox. Automations apply to every project — there is no per-project automation list.
You need the automation.manage permission atom to open this page at all.
To create, change, or remove an automation, you need its own separate
atom — automation.create, automation.update, automation.delete. To
name someone else as the acting identity on an action, you need
automation.act_as. An administrator normally holds all four.
An automation is not a list of steps. It is a graph: nodes connected by lines, each line carrying two things forward — which issues are still in play, and the facts about the event that started the run. There are five kinds of node.
| Node | What it does | What leaves it |
|---|---|---|
| Trigger | Starts the run. Every graph needs at least one. | One line, always taken |
| Source | Runs a search and adds what it finds to the run. | One line, always taken |
| Filter | Tests each issue against a condition and splits the set. | A matched line and an unmatched line — both run, even when one carries zero issues |
| Gate | Asks one question about the event, not about any issue. | Exactly one line — the other never runs |
| Action | Does the work: changes an issue, sends a message, creates something. | Passes its issues on unchanged, so a chain can continue past it |
A Filter narrows a set of issues down. It never stops the run, because a matched set of zero issues is still a real answer. A Gate picks one branch of the graph, and the other branch never runs at all — this is how an automation stops early down a path it did not take. Chain two gates for "and". Split from the trigger and merge two branches into one action for "or". Use a gate's untaken side for "not".
Click New rule to open the editor. A new automation starts empty — even the trigger is a node you add, not a default you edit.
The editor has three panes: a node list on the left, the canvas in the middle, and a settings panel on the right for whichever node you selected.
To add a node, do one of the following:
- Click a node in the left-hand panel. Search it first if the list is long.
- Right-click empty canvas. Type to search the same list, then press Enter. Press Escape to close the search without adding anything.
Drag from a node's dot to another node to connect them. A new line dragged from a port that already has one replaces the connection instead of adding a second one. Select a node to edit its settings on the right. Click Delete there to remove it — a trigger node cannot be deleted, because a graph must always have one.
The canvas flows top-to-bottom or left-to-right. Toggle Vertical / Horizontal above it. The server saves this choice with the automation, so it opens the same way next time someone edits it.
Two callouts appear when they apply, and neither blocks you from saving:
- No trigger yet — nodes exist but nothing starts them.
- Unreachable nodes — a node exists that no trigger can reach, so it will never run.
A trigger names one event from the server's full event catalog — an issue created, a comment posted, a state changed, and so on — grouped in the panel by the kind of thing it is about. The server supplies this list, so an event a plugin adds appears here with no change to this page.
A graph can hold more than one trigger node, up to 12. A run starts at whichever trigger fired, and the automation's other triggers do not run that time. This is how you make one automation react to several different events — for example, an issue created or a weekly schedule — instead of building the same graph twice.
Besides an event, a trigger can be:
- On a schedule — runs on a clock: every N minutes, daily, weekly, monthly, or a custom cron expression. A schedule carries no event, so gate nodes cannot follow it — there is nothing about "who acted" to ask. Instead, its own SLQ query selects the issues each run acts on. An empty query selects no issues. The actions that need no issue (below) still fire.
-
Manual — runs from the
/menu in the issue description or a comment, or from a call made outside Radd. Every enabled manual automation on the server appears in that menu, on every issue, labeled with its own name. To run it, you need theitem.updatepermission on the issue's project, notautomation.manage— an administrator curates the rule once, and any member with edit rights on the issue can use it after that.
| Node | Question it asks |
|---|---|
| Field changed | Did a named field change, optionally from and to specific values? |
| Changed by | Was the event caused by one of the people you name? |
| State category is | Is the issue's state category, right now, one you name? |
| Ask the AI | Ask a question about the issues and route by the model's answer — see AI features. |
| Filter items (SLQ) | Which issues match this query, right now? |
Field changed and Changed by read the event itself, so they are exact about what happened — a field-changed test only fires on the change, where a filter would also match an issue that was already in that state. Filter items (SLQ) reads the issue's current state instead, using the same query language as a view.
A Find issues (SLQ) source node runs a query wherever you place it in the graph and adds what it finds to the run. Choose Replace to discard whatever issues arrived at that point and use only the search results, or Add to keep both. Replace is the default, because a silent merge would make the result depend on whatever the trigger happened to carry.
| Action | What it does |
|---|---|
| Set state | Moves the issue to a named state. |
| Set priority | Sets the issue's priority. |
| Set assignee | Assigns the issue to a named person, or clears it. |
| Set team | Sets the issue's team, or clears it. |
| Add label | Adds a label. |
| Remove label | Removes a label. |
| Set cycle | Sets the issue's cycle, or clears it. |
| Set release | Sets the issue's release, or clears it. |
| Set custom field | Sets one custom field's value. |
| Add comment | Posts a comment. |
| Create item | Creates a new issue. |
| Send webhook | Posts a signed JSON body to a URL. |
| Post to chat | Posts a message to a chat webhook. |
| Notify user | Sends an in-app notification to a named person. |
| Send email | Sends an email — see below. |
The first ten actions need one issue to act on. A run that reaches one of them with no issues in play skips it, and says so in the dry run (below). The last five can run with no issue at all — a webhook that reports "nothing matched today" is a legitimate automation.
Every action past the first ten offers a Run choice: Once for all items (one message, however many issues reached it) or Once per item (one message each, capped per run). Choose per item when the message must describe one issue, such as a role recipient on Send email.
An action's text fields accept these tokens. An unresolved token stays in the text exactly as written, so a typo is visible rather than a blank.
| Token | What it gives you |
|---|---|
{{event_type}} |
The event that fired, e.g. item.updated. |
{{actor.name}}, {{actor.email}}, {{actor.id}}
|
Who caused the event. |
{{item.key}}, {{item.title}}, {{item.id}}
|
The one issue this run is about — blank unless exactly one issue is in play. |
{{items.count}} |
How many issues this action is acting on. |
{{items.keys}} |
Their keys, comma-separated. |
{{items.list}} |
One issue per line, key and title. |
{{payload.<path>}} |
Any value from the raw event, by dotted path. |
The To field takes a literal address, or one of three roles: reporter,
assignee, contact. A role resolves against one issue, so a role only
works with Once per item — the editor will not let you save a role
recipient set to run once for the whole set, because it would resolve
nobody. The action needs mail sending configured on the server. Without
that, the server skips and logs the action.
Every action runs as somebody. By default that is the person who created
the automation, not whoever last edited it. A node's Act as field names
a different person by email. Only someone holding automation.act_as can
set it. That person's own permissions apply to the action, and the change
appears under their name in the issue's history. If the named account is
suspended or no longer exists, the action falls back to the automation's
author instead of gaining higher permissions.
Save the automation once before you can dry-run it. The Dry run panel then lets you pick which trigger to start from (if the graph has more than one), a project, and — optionally — one issue to run as if the trigger had fired for it. Leave the issue empty for a graph fed by a search node or a schedule. It finds its own issues instead.
Click Run. Every node plans what it would do, but the server turns off the part that applies it, so nothing changes. The result lists every node, including ones that never ran, with what arrived and what left by each of its lines. Each action it would have taken shows Would apply or Skipped, with a plain reason for a skip — for example, naming a state that no longer exists in that project.
Select the Enabled checkbox in the automations list to turn a rule on or off. A disabled automation keeps its graph and its schedule bookkeeping. It does not run until you turn it back on.
In a dry run, a node that could not resolve its target shows Skipped with the reason in plain words.
In a live run, the server rolls back only the failing action. The rest of the graph keeps going, so one bad webhook URL does not stop the automation's other branches. The server writes the failure to its own log, not to the product. Radd keeps no record of a live run that you can open afterward: the issue's history shows whatever an action DID change, under whichever identity it ran as, but not an action that was attempted and skipped.
A graph holds at most 60 nodes, 120 lines between them, and 12 triggers.
A single run may execute at most 200 nodes and take at most 2000 per-issue actions. A scheduled trigger's own search is capped at 200 issues. A run that hits either limit stops there, and the dry run names exactly what it had to drop instead of quietly doing less.
The server marks every change an automation makes as automated. An event-triggered automation never fires again from its own action, however many nodes the change passes through on its way out — this is what stops a rule that both watches and sets the same field from running forever.
Mirrored from project.radd-hq.com on 2026-09-12. Documentation is written there; this copy is regenerated by scripts/publish_wiki.py and hand edits do not survive it.