Skip to content

Building Flows ​

A flow is an executable diagram: nodes describe the work, edges describe what happens after each outcome, and every run of the flow follows the graph. This guide covers creating flows in the visual editor; for starting them and reading results, see running flows.

Building flows needs the editor role (or admin) in the organization. An operator runs committed flows but cannot change them: on a flow's page the Edit, Duplicate and Delete buttons show a lock, and the tooltip names the role that would unlock them. See the permissions reference for every action and its role.

The Flows screen listing the flow catalog

Create your first flow ​

  1. Open Flows and click New Flow.

  2. Name the flow in the header and confirm it. A suggested name is filled in for you, and naming is the first step: the flow is created there and then, which is what opens the rest of the editor. Rename it any time from the same field.

    Flow names - and node names - follow the platform's object name rules: trimmed, not blank, at most 128 characters, no word longer than 64, and no control characters.

  3. In the Graph tab, click Add Node and pick a node type; drag nodes to arrange them, and drag from a node's output handle to another node's input to wire them. Every new flow starts with a Start node and two terminals, Success and Failure.

  4. Double-click a node to configure it.

  5. Click Save Draft as you work, and Commit when the flow is ready to run - only committed versions can be executed.

The flow graph editor with a flow open

The building blocks ​

NodeWhat it does
StepRuns a handler - a CLI command, an API call, a container, a check. Each step has Success and Failure outputs so you decide both paths.
ApprovalPauses the run until someone approves or rejects (outputs: Approved, Rejected, Expired). See approvals.
PauseWaits for a person to resume the run, optionally with a timeout.
Wait for windowHolds the run until the maintenance window picked in the run form opens (outputs: Success, and Failure when the window was missed). See maintenance windows.
BranchRoutes by rules (if/elif/else) or by matching one expression's value (switch). Cases are checked in order; unmatched tokens take Else.
LoopRepeats its body: while, until, a fixed count, or for-each over a list. Drop the body inside the frame and end it at the loop's end port.
Set VariablesAssigns run-scoped variables, readable later as {{ run.vars.NAME }}.
Fork / JoinSplit into parallel branches and wait for all (or any) of them, with a choice of failure handling.
TerminalEnds the run with Success or Failure.
GroupA purely visual container for tidying the canvas.
NoteA text note on the canvas, written in Markdown. It explains the flow to the people reading it and has no effect on a run.

Choose each step's Handler in the handler browser - what's available depends on the installed plugins (see the step handler reference). A new step opens straight into it; for an existing step, click the Handler field. The browser groups handlers by category, by Used in this flow, and by Recent (the handlers you chose last in this browser). Its search matches the name, the ID and the description, so a word such as expiry finds the TLS certificate check. The highlighted handler's details show what it targets, where it runs, its default timeout and every setting it takes, and - when the step already has a handler - which of the step's settings a switch would remove; settings both handlers take are kept. Arrow keys move the highlight, Enter picks it, Esc closes without changing the step.

A handler whose plugin ships its own documentation page shows it in the browser's Documentation tab, and the step editor offers a Handler documentation link under the Handler field and an Open handler documentation link in the Handler tab - both open the page, served from the wheel installed on this instance, in the Help drawer's Installed Handlers topic, which also lists every installed handler. A setting whose effect needs spelling out, such as Allow legacy SSH algorithms, has a What does this allow? link under it that opens the page with the exact details, here Legacy SSH Algorithms. When a handler renames a setting, a value the step stores under the old name still shows in the field; changing or clearing the field keeps only the new name, so the old value cannot come back. Steps that target devices get a Targets field listing the device roles your form defines.

A step takes only the targets its handler declares. Saving refuses IP targets on a handler that takes none, and a second target role on a handler that takes one; a Git pull or an import carrying them fails for the same reason. The editor keeps steps clear of both: switching a step to another handler drops the targets the new one does not take, picking a role on a handler that takes one target replaces the role already selected, and a step that already carries such targets shows them with a note to remove them before saving. A flow version saved before this rule still runs, and its step's events say when IP targets go unused. Target roles on a handler that takes none, such as a container step, are allowed: they fill {{ device }} and {{ devices }} in its settings, and the flow validation endpoint (POST /flows/{id}/validate) warns that the handler does not take them. The editor gives such a handler no target picker, so it adds none; the panel of a step that carries roles anyway lists them with a note that they still fill those variables, and you can remove them there.

Click a node to open its panel. On the flow detail page, in a version preview, and on a Git Read-only flow the panel is the editor's own, with each field shown as text instead of a control: the same tabs, the same handler settings, the same targeting, tags, timeouts and container file layout, minus any way to change them. It shows what the editor would show the same person - a handful of settings that can escape the worker sandbox stay admin-only in both. Only the edit page lets you type.

Groups ​

Add a Group from Add Node, select it, and use its resize handles to make room for related nodes. Drop a node with its centre inside the group to make it part of that group. It stays at the drop position, and you can keep dragging it within the group or drag it outside to detach it. You can also drag a new node, note, or frame directly from Add Node into an existing group or loop; the frame under the drop point becomes its parent. For nested frames, the smallest frame containing that point receives it.

Groups can contain other groups. When frames overlap, the smallest frame containing the node's centre receives it. Group membership and positions are preserved when you save and reopen the flow. Groups only organise the canvas; they do not change execution order.

From back to front, the graph shows group and loop frames, notes, connecting edges, then regular nodes. Selecting or dragging a frame or note keeps it in that layer, so it cannot cover nodes or their connections. Nested frames sit above their containing frame, and notes sit above any frame they overlap. This order also applies in read-only and version views.

Notes ​

Add a Note from Add Node to explain part of a flow right next to its steps: why a check exists, who to call before a step, what a branch is for. Double-click a note to write it. The text is Markdown (bold, lists, code, tables, links), up to 4,000 characters, and each note has one of five colours. The editor has a formatting toolbar (or Ctrl+B, Ctrl+I and Ctrl+L for bold, italic and link; ⌘ on a Mac), a Preview of the note, and a Markdown cheat sheet behind its ? button. Form notes use the same editor. Links work only when they start with https://; images and raw HTML are not shown. Drag a note into a group or loop frame and it moves with the frame.

Notes are saved, versioned and exported with the graph, and they show on the flow detail page, in version previews and on a run's graph. They are only for people: notes take no edges, and the run engine never receives them.

Routing edges ​

To tidy a busy graph, select an edge. Drag anywhere along it to add a bend point; drag a bend point to move it, and double-click it to remove it. The edge's reset button clears all of its bend points at once. Bend points move with the nodes when you drag both ends of the edge together: a group, a loop, or several selected nodes.

You can also move a node's ports: the input on its left and the outputs on its right. Select the node and a small grip appears next to each port. Drag a grip and the node shows its 32 points, named after the compass: N is the middle of the top side, NE the top-right corner, and NbE, NNE and NEbN lie between them. The port snaps to the nearest free point when you let go, and every edge on it follows, straight out of the side or diagonally from a corner. To undo, drop the grip back on the port's usual place or double-click it. A loop's inner start port stays where it is.

Routing is only for people; the run engine ignores it.

Tags ​

Every step takes Tags: a short list of key=value pairs you type yourself, in the same shape as device, site and flow tags. They do not steer execution on their own - ordering comes from the edges and the handler decides the work - so a tag never makes a step run, skip or run somewhere else. They annotate the step for the people reading the graph, the run timeline and the evidence list, so write the ones your team actually looks for (env=prod, team=network, risk=high) and leave the field empty when none helps. Every tag a step carries is shown on its node.

Two keys are conventional, and the editor suggests them first with their usual values:

KeySuggested values
phasePREPARE, IMPLEMENTATION, VERIFY, CLEANUP
kindCHECK, ACTION, WAIT, TRANSFER, EXECUTE

These are suggestions, not rules: write them like any other tag - phase=VERIFY - and any value works, under those keys and under every other key. Nothing enforces them; they exist so that phase chips and evidence rows read the same across flows written by different people. In the flow itself they are ordinary entries of the step's tags map (tags: {phase: VERIFY, kind: CHECK}) - a step has no phase or kind field of its own. As you type, the field suggests keys - the conventional ones first, then every key the other steps of this flow and your organization's other flows already carry - and, once you have typed key=, the values seen under that key. So a second author reuses env instead of inventing environment, and the list refreshes each time the flow is saved.

To tag several steps at once, select them together (Ctrl-click or Cmd-click, or drag a box with Shift held) and use the small panel that appears next to Triggers in the toolbar. It also clones or deletes the whole selection. Its tag editor shows the tags every selected step shares; adding one applies it to all of them, removing one removes it from all of them, and tags that only some of the steps carry are listed underneath, untouched.

Tags are readable while a step runs, as {{ tags.env }} - and the two conventional keys the same way, as {{ tags.phase }} and {{ tags.kind }}; there is no shorter form. A tag reaches the work two ways. A step whose config or params references one resolves it into that step's input, exactly like any other template variable, so changing the tag changes what that step is handed. And the handler always receives the whole map as ctx.tags, so a handler can read a tag the author never referenced in a template. Tags are snapshotted onto the step run - so editing the flow later never rewrites what a past run recorded.

One catch: a tag reference only exists on a step that carries that tag. {{ tags.phase }}, {{ tags.kind }} and {{ tags.env }} on a step without them fail when the step runs, the same way any other unknown variable does (templates render with StrictUndefined) - so clear the tag and the reference together.

Filtering runs, flows or evidence by tag is not available yet: tags are shown wherever a step appears, but the lists do not take a tag as a filter. The run's snapshot is stored ready for it.

Step timeouts ​

A step still running at its step timeout is stopped and fails. Like any other failed step, it then takes its failure edge, so the flow can clean up or report; with no failure edge the run fails. A step whose worker stops responding fails the same way, without waiting for its timeout: within two minutes for a container-backed step and ten minutes for any other. The timeout is the step's Timeout Override (under Advanced Options on the General tab), else the flow's Default Step Timeout, else the handler's own default: 300 seconds for most handlers, longer for long-running ones such as tf.apply or flow.run. When the flow has no default, the step editor shows the handler's default if the handler declares one. A flow default replaces the handler's default even when it is shorter, so flow validation warns about a step without an override that the flow default would stop early, such as a flow.run step under a 300-second flow default.

Some handlers also take an overall time limit of their own in their settings, and stop their work when it runs out. When the handler declares that field to the platform, the step gets at least that limit plus a margin (60 seconds unless the handler asks for more), whatever the override or the flow default says, so the step ends on its own limit and still saves its output. The limit is the one the step sets, also under an earlier name of the field, or the field's default when the step sets none. The step editor then says, under Timeout Override, how long the step gets, and flow validation warns about an override shorter than that. A limit set to one of the run's inputs ({{ inputs.wait }}, also with | int) is read from that input's value when the run starts, and raises the timeout the same way. Any other template (a variable, a loop item, an earlier step's output) is known only when the step runs, so it does not raise the timeout: when it renders to a limit longer than the step's timeout, the step's log says so and names the override to set. A limit longer than 30 days raises it to 30 days plus the margin.

A Sleep step (general.sleep) waits on a timer the run keeps, not on a worker. A worker that restarts, or is replaced, while the step sleeps does not start the wait over or hold the step up: the step ends when its duration has passed since it started, whichever worker records it. Cancelling the run ends the wait at once. A duration only known when the step runs (a template other than one run input) that is longer than the step's timeout waits for the timeout and fails the step, naming the override to set. Its retries do not apply: there is no run of it to repeat. A run that reached a Sleep step before the platform was upgraded to this keeps sleeping on its worker, as before, until it ends. While the step sleeps, the run's graph counts down the time left on it (see Running Flows).

A step's retries (under policy in the flow's definition; the editor keeps the value but has no field for it) runs the step again only when a run of it ends without a result: it timed out, stopped heartbeating or lost its worker. A step whose handler reports a failure is not run again; it takes its failure edge. The other policy settings older flows may carry (on_failure, evidence_required, required_artifacts) are not used.

Commands that ask questions ​

Some device commands stop at a question before the prompt returns, such as the Delete filename [x]? and [confirm] of a delete. A CLI step waits for the prompt, so such a command runs into its command timeout. Where the step's handler offers Answers to questions (netcli.execute in a step plugins release that has it), add one row per question:

  • Command pattern - a regular expression on the command's text, such as ^delete\s; empty applies the row to every command.
  • Question - a regular expression on the last line the device printed, such as \[confirm\].
  • Answer - what to type before Enter; empty sends Enter alone.
  • Every time - answer each time the question comes, not only once per command (for example a delete /recursive that confirms each file).

Only the listed questions are answered. Any other question fails the command and names the line the device is waiting at. The handler's own page lists the details.

Calling another flow ​

A Run Flow step (flow.run) launches another committed flow as a child run. Pick the child from the step's Flow field and choose whether it runs the latest committed version or a pinned one, then map the parent's values onto the child's run form.

A step can name its child two ways. Picking one from the list stores its id. Bundles imported through configuration exchange instead carry the child's name, because ids are assigned per instance and would not survive the move; the name resolves to the newest matching flow each time the step runs. The editor shows either form the same way, and keeps whichever one the step already uses when you change the child flow, so an imported flow stays portable. A name matching no flow you can see is called out under the picker rather than left blank — it still resolves when the step runs, on whatever the instance holds then.

Each device-target field on the child's form gets its own row with three choices. Use child default sends the devices the child's form preselects; Map from parent target forwards the devices this run was given for one of the parent's own target fields; None sends nothing. Mapping from a parent target is unavailable while the parent flow has no target fields, and a row whose child default is empty says so — a required target with no default and no mapping fails when the step runs. Default targets travel in exported bundles as device names and are matched to devices at import, so a default naming a device the instance does not have yet arrives empty.

Validation follows Run Flow steps into their children, and their children's children, and reports an error when a chain leads back to a flow already on it. That check loads at most 256 distinct child flow versions and follows at most 32 levels of nesting; a flow whose children go beyond that is reported as nesting too many flows to check.

Branches, loops and run variables ​

Branch ​

A Branch takes one token in and sends exactly one out. Cases are checked in order and the first that matches wins; later cases are not evaluated. Else must be wired, and takes the token when no case matches. An optional error outcome takes it when an expression fails or reads an undefined value; left unwired, that fails the run like a failed step. Several cases may lead to the same next node: only one path runs, so no merge node is needed. The Branch's step record shows which case won and what each evaluated case returned.

Loop ​

A Loop's outcomes are iterate (into the body), done (the loop finished: the condition decided to stop, or the items or the count ran out) and an optional max_iterations (the cap was reached; left unwired, the run fails). A break does not take done: the token follows the break edge instead, so a step wired only to done does not run after a break.

  • while checks before each pass (zero or more passes); until checks after (at least one); count runs a fixed number; for-each runs once per item.
  • The body is every node on a path from the loop's start port to its end port. Dropping nodes into the frame is only for looks: what counts is reachability.
  • Inside the body, {{ loop.index }} is the pass number (from 0), and {{ loop.item }} the current item (for-each). In nested loops these name the innermost loop; reach an outer one as {{ loops.<loop_node_id>.index }}. {{ steps.X }} reads the latest run of step X, so in a body it is the current or previous pass.
  • Collect gathers a value from each pass into {{ steps.LOOP_ID.output.results }}, in pass order.
  • Break is any edge from a body node to a node outside the body: the loop ends with exit reason break before that node runs. A body that contains a fork cannot break, because another branch could still be running.
  • A failed step in the body fails the run. To stop the loop on a failure instead, wire that step's failure edge out of the body: that is a break.
  • Parallel passes: a count or for-each loop with max parallel iterations above 1 runs that many passes at once, still within the flow's Engine Concurrency window (Settings → General → Advanced Options, default 20, at most 100), which fork branches share. Collected results stay in pass order. When a pass fails, Finish running iterations, then fail (the default) starts no new passes, Cancel running iterations and fail stops the running ones, and Run every iteration, then fail runs them all; each then fails the run and names the failed passes. A parallel body may not contain a fork or join, a nested loop, a Set Variables node or a step that keeps per-node state (tf.plan, tf.apply), and may not break. Read {{ loop.item }} and {{ loop.index }} rather than {{ steps.X }} there, and gather results with collect.

A commit is refused when:

  • an edge enters the body from outside (the only way in is the start port);
  • a body node has an edge back to its own loop (the end port is the only way to the next pass);
  • two loop bodies overlap without one being fully inside the other;
  • two parallel branches of the same fork can reach one loop before a join;
  • a join in a loop body is not set to All Branches (AND) with Let Finish, or a body holds an until-join monitor;
  • max_iterations is below 1.

A fork and its join may both sit inside a sequential loop body; the join then waits once per pass. A loop inside a fork branch counts as one arrival at the join, like a step.

Limits ​

  • max_iterations defaults to 100 for while and until. Count and for-each default to their own bound (the count, or the number of items).
  • Execution budget: one run executes at most 750 nodes by default, and a flow's max_total_node_executions can raise that to 2000 at most. When a flow is committed, the worst case (each node times the max_iterations of every loop around it) is checked against the budget: above 80% gives a warning, above 100% refuses the commit. While the run goes, a guard ends it cleanly before its history grows too large for Temporal.
  • Plan for loops of hundreds of passes, not tens of thousands. Parallel passes finish sooner but count against the budget the same way.

Set Variables ​

A Set Variables node assigns run-scoped variables, in order (a later assignment sees the earlier ones). Read them anywhere after as {{ run.vars.NAME }}; they also appear on the run's detail page. The step record shows each value before and after. Expressions cannot call secret(), so no secret ends up in a variable. A typical use is a counter for retries:

yaml
type: set_vars
assignments:
  - {name: attempts, expr: "(run.vars.attempts | default(0) | int) + 1"}

How a flow gets started ​

The Start node carries the flow's trigger nodes: a Manual card always, plus a card for each schedule and webhook pointing at this flow, and one for each parent flow whose Run Flow step launches it. They are a live overlay, not part of the definition — they never enter drafts, commits, or diffs, and acting on one (pausing a schedule, running it now, turning Manual off) takes effect without a commit. Hide them with the Triggers toggle in the editor toolbar.

A parent flow that calls this flow from several steps still gets one card, which says how many ("3 flow.run steps"); its panel lists each step. Past eight cards, the rest fold into one +N more card that says what it holds ("14 parent flows · 2 schedules"). Its panel groups them by kind, names each parent's calling steps, and can filter a long list by flow or step name.

A webhook card also names how its endpoint checks a caller: Bearer (a shared token), HMAC (Hegemony's own signature) or HMAC-SHA512 (the signature NetBox puts on its webhooks).

Each kind is turned off in its own way: a schedule is paused and a webhook is disabled from its card here or its own page, a parent flow's call is removed by editing that parent, and the Manual card has Turn off. Turning Manual off makes the flow automation-only — only a schedule, a webhook or a parent flow can then start it. That is what a subflow wants, since its parameters come from its caller. See manual run control.

A trigger shows only on the flow version it would actually start, so a schedule pinned to an older version appears on that version's preview in History rather than on the current graph; the Manual card counts any hidden that way. Triggers themselves are managed on the Triggers page — see schedules and webhooks.

Using data in steps ​

Fields with the braces button accept template expressions - click it to open the Variable Picker, or type directly:

text
{{ inputs.NAME }}             an answer from the run form
{{ steps.NODE_ID.field }}     a previous step's output
{{ device.hostname }}         the device the step targets
{{ vars.NAME }}               a global variable
{{ secret('backend://path/key') }}   a secret

A secret a step used is replaced by [redacted] in that step's output, so a later step reading steps.NODE_ID.output never sees it; a step that needs the secret references it itself (see Secrets).

The outputs of earlier steps are handed to a step in one bundle of at most 100 KB. When a run's outputs add up to more than that, step metrics are left out first and then the largest output values, which then read as empty (the step's entry carries output_truncated: true); keep large data in files or evidence rather than in step outputs.

env() and file() are not available in flows: they read the platform's own environment, so only platform configuration may use them (see Secrets).

Branch conditions and loop expressions are written without {{ }} (for example steps.check.output.free_gb | int < 10) and are linted as you type. The picker's Syntax Help section carries the full cheat sheet, including filters like | default('x') and | int.

A field is rendered when it holds a {{ }} or {% %} block, even one that spans lines. For example, {{ items | join('\n') }} in a double-quoted YAML string holds a real line break and still renders. This also applies to text that is not meant as a template: a {{ with a }} on a later line makes the field a template, and the step fails if it does not render. Wrap such text in {% raw %} and {% endraw %} to keep it as written.

Templates and expressions refuse to build oversized values: an operation (*, **, %, +, ~, padding such as | center(n) or '%10s', .format(), | format, | indent, | replace, | join and .expandtabs()) that would produce more than 4,194,304 characters or list items, or an integer of more than 65,536 bits, fails the step, branch, loop or approval text with a SecurityError, and the check also runs when a branch, loop or set-vars expression is saved. For a format, the widths and values of all its fields count together. | regex_search and | regex_replace match with RE2, whose run time grows linearly with the value. It reads Python's pattern syntax except backreferences in the pattern (\1; \1 in the replacement still works) and lookaround ((?=, (?!, (?<=, (?<!), and a pattern using them fails with unsupported or invalid pattern. The pattern may be up to 2,048 characters and the value up to 1,048,576. A for_each items expression reads at most one item past its 10,000-item cap before failing.

A value that ends up in a shell command line needs | quote, which makes it one literal word: systemctl restart {{ inputs.service | quote }}. Without it, an input such as nginx; rm -rf ~ would run a second command. The shell.execute step refuses to run a command with an unquoted {{ }} value, or one placed inside quotes, a comment, backticks or a here-document, where | quote would not keep it one word (write echo {{ x | quote }}, not echo "{{ x | quote }}"). A handler can refuse unsafe templates like this before they are rendered, on every run. | quote fails the step on a value that contains a line break, because commands are split into lines after rendering; pass such a value as an environment variable instead.

Just before a step runs, its handler also checks the settings as rendered: the rules behind its settings form, plus any checks of its own. A value that does not fit - a missing field, or text where a number belongs - shows as a warning in the step's events, naming the field and the problem. Text from the settings that a message would quote is shown as [redacted], as secrets are (text shorter than 4 characters excepted). The step still runs, and the handler may still fail on that value.

The run form (parameters and targets) ​

The Form tab is where you design what a person fills in when starting the run: sections, input fields, and device-target fields. Fields become the flow's parameters, and device fields become its target roles - the Settings tab lists both read-only. Use Preview to see the form as runners will. Details: flow interface builder.

Drafts, commits, and versions ​

Edits accumulate in a draft (the amber Draft pill) and never affect runs until you Commit, which snapshots the flow as an immutable version (v1, v2, ...). From History you can view any version, Compare two versions, Run an older version, or Restore to draft to continue from it. Revert throws the draft away and returns to the last committed state.

The YAML tab shows what a commit would change. While the saved draft differs from the last committed version, removed lines are marked red and added lines green, with a count of the changes. Changed parts only folds away everything else, and the arrows jump between changes. The marks compare the saved draft, so click Save Draft first to see your latest edits. They go away once you commit or revert.

Edit YAML lets you change the flow as text, which is quicker for bulk changes such as renaming a value used in many steps:

  • Each pause in typing checks the text with the same checks as a save from the canvas. Problems are underlined on their line and listed below the editor; click one to jump to it. A problem that would only stop a commit is a warning: the draft still saves.
  • The marks show your edits against the saved draft. Switch Compare with to the committed version to see what a commit would change.
  • Apply to draft (or Ctrl+S) saves the text as the draft and reloads the canvas and the other tabs. The server rewrites the text in its standard form, so YAML comments and custom formatting are not kept.

Only the flow's definition, name, description and tags can be changed this way. Notification subscriptions, attached files and Git settings are shown for reference: change them in their own tabs. Editing is not offered while other tabs have unsaved changes (save or discard them first), nor for a flow synced read-only from Git. If the draft is saved elsewhere while you edit, Apply to draft is refused so neither edit is lost: copy your edits and Start over from the new draft.

A misspelt key is an error, not silently dropped, down to a step's retry policy and other nested settings; free-form maps such as step parameters accept any key.

Save Draft from the canvas is protected the same way: if the draft changed since the editor loaded it (applied from the YAML tab in another window, saved by someone else, or pulled from Git), the save is refused instead of replacing that newer draft. Copy your changes and reload the page.

A flow graph holds at most 2,000 nodes and 5,000 edges. Saving, importing or syncing a larger graph is refused, and validation and commit report it.

Files ​

The Files tab attaches scripts, templates, and configs to the flow - create, upload (single files or folders), organize, and download as ZIP. Container steps mount these files; their node editor shows exactly where they appear in the container filesystem.

Larger shared files (software images, packages) live in the file repositories instead. A download step's File setting has two modes: Pick file opens the repository browser and stores the file's repository and path, and Template takes a reference such as {{ inputs.firmware }}, the value of a Repository file field on the run form. See Use repository files in flows.

Git sync ​

A flow can be linked to a Git repository (the editor's Git tab): Synced pushes each commit and pulls remote changes, Read-only only pulls - the flow then cannot be edited in the UI, though its node panels still show the settings. See the Git integration guide.

Flow settings worth knowing ​

  • Default Step Timeout - inherited by every step unless overridden. See step timeouts.
  • Run Limits - refuse new runs beyond a concurrency cap, rate window, or cooldown. See run limits.
  • Manual runs - whether a person may start the flow by hand. Turned off from the Manual trigger card, not this panel, because it takes effect without a commit. See manual run control.
  • Egress Policy - the outbound-network policy enforced on the flow's steps. Every step that runs a container - container.run, ansible.playbook, tf.plan, tf.apply - can narrow it further in its node editor; widening it needs the admin role. A container.build step can too; its build gets a network, and may push to a registry other than the platform's, only while the policy is open. Each step records the policy it ran under; see egress policy in the evidence.
  • Notifications - send run and approval events to configured destinations, with customizable templates. See notifications.

Egress policy in the evidence ​

Each step that runs under an egress policy saves the policy it ran under, as an egress_report artifact named egress-policy on the run's Artifacts tab. The worker writes it from what it enforced for the step, not from the flow's settings, and saves it when the step succeeds, fails or is cancelled. A step refused before it started, because its policy could not be enforced, saves none.

FieldMeaning
mode, allow, denyThe step's effective policy: the flow's policy, narrowed by the step's own egress settings.
sourcesWhere it came from: flow (the flow's Egress Policy), step (the step's own egress mode and rules), or both.
enforcementHow it was carried out (below).
enforced_allow, enforced_denyThe rules programmed on the sandbox, with a service name such as gitea:3000 replaced by the address it resolved to then. sandbox_firewall only.
platform_api_ruleThe allow rule the platform added so the container can reach the API: a tf.plan or tf.apply step that keeps its state on the platform, under a policy that did not already allow it.

enforcement is one of:

  • sandbox_firewall - the container ran on its own network on the sandbox, behind firewall rules for the policy.
  • no_network - the container ran with no network (a deny-all policy), or an image build ran its RUN instructions with none (any policy but open with no Deny rules).
  • network_disabled - the container step turns its own network off, which is narrower than any policy.
  • worker_gate - the step runs in the worker (network CLI, probe and shell steps, for example), and every connection the worker opens for it is checked against the flow's policy before it is made. These steps have no egress settings of their own.
  • none - the policy is open with no Deny rules, so there was nothing to enforce.

A step whose flow has no egress policy, and which sets no egress mode of its own, runs open and saves no egress-policy artifact. An address taken from a secret shows as [redacted], as in the rest of the evidence.

What the policy did is saved next to it: egress-report holds a container step's packet counts per rule, and egress-report-worker the connections the worker allowed and refused for the step.

Finding a flow ​

The Flows screen searches and groups the list without leaving the page.

Search matches the flow name, its description, its tags, and its git repository and path, so "backup" finds the flow whether that word is in the name or only in the folder it is stored in. Several words all have to match.

Group by collects the rows under collapsible headings:

Group byGroups are
Tag: keyThe values of one tag key - Tag: team puts every team=netops flow together. One entry per tag key in use. Flows without the key collect under No key tag.
SourceThe git repository and folder a flow is stored in, then flows kept only in the database (Local), then read-only Shared templates.
Name prefixThe part of the name before the first / or : - name a flow network/backup config and it groups under network. Names without a separator collect under No prefix.
StateDraft (never committed), Uncommitted changes, and Committed.

A grouped list shows every flow at once instead of paging, with Collapse all to fold it down to the headings.

Table or library ​

The Table / Library switch changes how the same filtered, grouped list is drawn.

  • Library (the default) draws each flow as a card with its full description, its tags, how many schedules point at it, and how its last run went - with Run as the button on the card. Groups become shelves. A flow that has never been committed cannot run yet, so its Run button is disabled until you commit a version.
  • Table is the dense view: sortable columns, per-column filters, and the row menu for edit, duplicate and delete.

Cards have no column headers to click, so the library has its own Sort by control: by Name, by Newest (when the flow was created), or by Recently updated. It orders the cards inside every shelf, the pinned one included. The table sorts by its columns instead, so it does not show this control.

Pin a flow (the pin on its card) to keep it on a Pinned shelf at the top. A pin belongs to the flow, not to your browser: everyone in the organization sees the same pinned shelf, and it follows you to another machine. It is also part of the flow's configuration, so a configuration bundle can arrive with the flows a new deployment should start from already pinned.

The deleted tab is always a table: restoring and purging is list work, not browsing.

The tab, search, grouping, sort and view you pick are all part of the address, so a filtered view can be bookmarked or pasted to a colleague. Anything left at its default is left out of the address, so a plain /flows stays plain.

Tagging flows ​

A flow carries tags - the same key=value map devices and sites use. Set them in the editor's Settings tab, under General, one chip per tag: team=netops, risk=high, domain=wan.

Tags are what the flow list groups by, and they are worth agreeing on as a team before spreading them: team, owner and domain cover most of what people look for. A flow can carry as many as it needs - that is the point of tags over folders, since a flow rarely belongs in exactly one place.

Three things worth knowing:

  • Saving a flow replaces its whole tag set. A tag you remove in the editor is gone on save; there is no per-tag merge.
  • Duplicate copies the tags too, so a fork of a shared template lands in the same grouping.
  • Tags are flow metadata, not part of the versioned definition: committing a version does not snapshot them, and a git pull does not overwrite them (a pull brings the definition; your own grouping stays yours). A push does write them into the flow's file, so a repository carries them for anyone importing it fresh. The pin follows exactly the same rules.

Duplicate, delete, restore ​

Duplicate copies any flow (including read-only shared ones) into an editable copy and opens the editor. A shared flow has no Edit or Delete, but its Run starts a run in your organization (see Organizations). Deleting is soft: the flow moves to the Deleted tab for restore or permanent removal - both are blocked while schedules or webhook endpoints still reference the flow, and the error links to the offending records.

Released as open source under the AGPL-3.0-or-later license. Development is sponsored by Rexonix s.r.o. Contact — [email protected].