Manage your workflows

Building one workflow and living with twenty are different jobs. The Build your first workflow tutorial covers the canvas, the node palette and the trigger lane; this page covers the list they all land in — how to find the workflow you want, read whether it is healthy, start it by hand, move it between projects with YAML, and retire it safely.

Where the list lives

The workflows list is the first tab of the Build hub, and the hub landing is the list itself. The canonical URL is /build — not /build/workflows, which holds only the deeper pages (the builder, the template gallery, the unrouted-email view). The sibling tabs Scripts, Apps and Schedules sit one segment deeper.

An old /workflows bookmark still works: it redirects to /build, and /workflows/<id> redirects to /build/workflows/<id>. The redirect is a courtesy for stale links, so share the hub URL rather than the redirect — see Navigation and hubs.

The list is scoped to one project

Everything on this page — the counters, the rows, the facets — is scoped to the project chosen in the action row beside the tabs (labelled Project). A workspace with several projects shows one project at a time; switch it to see another project’s workflows. If the workspace has no projects yet, the page says so instead of showing an empty table.

Read the list

A strip of five counters sits above the table. All five cover the selected project, and the three time-boxed ones cover the last 24 hours:

• Active runs — runs of this project’s workflows that are still going, with a sub-line naming how many distinct workflows they span.
• Workflows — how many exist, and across how many projects in total.
• Success 24h — completed runs divided by completed plus failed runs. The sub-line names the exact sample, so a flattering percentage over three runs is visible as such.
• Failed 24h — the failure count, plus how many workflows were affected. The card inks red as soon as it is non-zero.
• Duration — the median run duration (not the mean, so one pathological run does not move it), over the sample named in the sub-line.

Each row below then describes one workflow:

Column	What it tells you
Workflow	The name, behind a coloured tile carrying the first letter of its trigger kind. The sub-line reads project · detail, where the detail is the trigger’s concrete setting — a git branch, a Telegram command, the +slug of an email alias, a subject filter. Triggers with no such detail (manual, webhook, schedule, Discord, IMAP) show the project alone.
Status	The last run’s outcome, as Running, Done, Error, Ready or Cancelled. A workflow that has never run reads Ready.
Nodes	How many nodes the graph has.
Runs 24h	How many runs started in the last 24 hours, in any state. Always a number, 0 included.
Success	Completed divided by completed plus failed, over the same 24 hours, as a percentage. An em-dash means no run finished in the window — either nothing ran, or everything that ran is still in flight.
Trigger	The kind of the workflow’s primary trigger.
Last run	How long ago the most recent run started, or Never run.

The Runs 24h and Success columns fold away on a phone, where the card keeps the name, the status word and the node count.

Reading a low success rate

Success is a ratio over a deliberately narrow window, so read it together with its neighbours before concluding anything:

• A low percentage next to a high Runs 24h is the real signal — the workflow is firing often and failing often. Open it and look at where the runs stop.
• A low percentage next to Runs 24h of 1 or 2 is arithmetic, not a diagnosis. One failure out of two runs is 50%.
• An em-dash with a non-zero Runs 24h means the runs have not finished — a workflow parked at a human-approval node sits here indefinitely, because nothing has decided it yet.
• Cancelled runs count in neither half of the ratio. They inflate Runs 24h without moving Success at all.

Find the one you want

The toolbar above the table filters and sorts on the server, so it searches the whole project, not just the page you are looking at.

1. Use Filter to pick a lifecycle view. The four buckets are precise:

   • All — no filter.
   • Active — the latest run is still going. A run paused at a human approval counts as active, which is usually what you want: it is waiting on a person, not stuck.
   • With errors — the latest run failed outright. Cancelled runs do not appear here.
   • Scheduled — the workflow’s primary trigger is a Schedule. This is a property of how it fires, not of any run.

2. Narrow further with Trigger (Manual, Schedule, Git, Webhook, Telegram, Discord, IMAP, Email, App run) and Status (Running, Done, Error, Ready, Cancelled). Both default to All and combine with the view above.

3. Type in the search box to match workflows by name.

4. Click a column header to sort. Workflow, Status, Nodes, Runs 24h, Success, Trigger and Last run are all sortable — sorting by Last run is the quickest way to surface a workflow that quietly stopped firing.

5. Use Columns to hide any column you do not need on a narrow screen.

Which trigger is the primary one

A workflow can carry several triggers, but the list shows one: SupaCloud prefers an enabled trigger and, among equals, the oldest. Note what this means for the Scheduled view — a workflow whose only trigger is a schedule still reads as Scheduled even after you disable that schedule, because there is no other trigger to prefer over it. Scheduled describes how a workflow is wired, not whether it is currently armed.

Open a workflow

Clicking a row does not navigate away. It opens a wide peek drawer holding the complete builder — palette, canvas and properties panel — over the list, with a sub-line reading N nodes · N edges · N triggers. Press Esc or click the sliver of list still visible to close it and stay where you were in the table.

When you want the immersive canvas instead, click Open fullscreen in the drawer’s header. That navigates to /build/workflows/<id>, the shareable deep-link for a single workflow. Both surfaces are the same editor over the same data — the drawer is for a look, the fullscreen route is for a session.

Trigger a run by hand

1. Open the workflow (drawer or fullscreen).

2. Click Run workflow in the builder header. The run starts immediately and the canvas begins showing it — node states, durations, and the path the run took.

A manual start works whatever triggers the workflow carries. You do not need a Manual trigger on the canvas to press the button; the trigger lane governs what fires the workflow without you, not what you may start yourself. The one place that behaves differently is the Start run launch dialog, which offers a workflow only when its trigger is Manual or absent — a deliberately narrow list, not a limit on the workflow itself.

From the web terminal the same thing is one line:

workflows              # list every workflow across projects
workflow <id>          # its details
workflow trigger <id>  # start a run now

Two ways a manual start can be refused

Starting a run by hand is an entitlement (triggers.manual) and is also checked against your workspace’s remaining run capacity. On a plan without manual triggers, or with the budget exhausted, the start is refused rather than queued — see Track usage and budget.

Start from a template

SupaCloud ships a set of ready-made workflow templates. A template is not a live object you subscribe to: choosing one clones its graph into your project as an ordinary, fully editable workflow, and drops you in the builder on the copy. Nothing links back to the original afterwards.

There are two doors to the same set:

• From template in the action row beside the tabs opens a picker modal.
• The caret next to it opens an overflow menu whose first entry, Start from a template, is the full-page gallery at /build/workflows/templates — the same templates as tiles, with a project chooser of its own.

Every template ships as an autodev variant — plain autodev, the pull-request flow, the Linear and Notion tracker flows, the git-issue flow, and the gated and concept-first versions. Each tile names the trigger kind it provisions, and the description says what the graph does.

A cloned git trigger arrives switched off

The autodev templates provision their git trigger disabled on purpose, so a half-configured clone cannot start firing on real repository events. Paste the receiver URL into your Forgejo webhook settings first, then enable the trigger in the builder’s trigger properties.

For what these graphs are actually for, see Choose the autodev mode and Automations.

Move a workflow with YAML

Every workflow round-trips through a server-authoritative YAML document. This is how you copy one between projects, review a change in a pull request, or keep an off-platform copy.

1. Open the workflow and switch the header toggle from Canvas to YAML.

2. Click Export from server to load the currently saved graph into the editor — not your unsaved canvas edits. Use Copy to put it on the clipboard.

3. To bring a document back in, paste it into the same panel and click Import as new workflow.

Import always forks — it never saves back

Import as new workflow creates a new workflow in the same project and navigates you to it. It does not write your edits back into the workflow you were looking at, however much the panel looks like an editor for it. To change the open workflow, edit it on the canvas and press Save. To move a workflow to a different project, export it there and import it here.

The exported document opens with a # yaml-language-server: $schema=… line pointing at SupaCloud’s published workflow JSON Schema, so an editor that understands that comment validates and completes the file as you type. The full node and edge vocabulary is in the Workflow YAML reference.

Importing from Windmill

The same overflow menu offers two Windmill paths, and they are not equally available:

• Import from Windmill converts a single exported flow’s JSON into a SupaCloud workflow. Any workspace member can use it.
• Import from repo walks a whole Windmill sync repository — flows, apps and scripts at once. It is an admin-grade operation and the server refuses it for anyone else, even though the menu entry is visible to everyone. See Import a Windmill repository.

Imported database bindings are read-only until you say otherwise. A step that received a Postgres resource as a resource("f/…") parameter is imported as a code node with a resource binding — and the converter deliberately binds it read-only (pg.query works, pg.execute is denied). A step that writes — an INSERT, UPDATE, DELETE or MERGE — therefore fails at run time with resource 'pg' is bound read-only until an operator opts in. The import report names every such step. To enable the write: open the workflow in the builder, select the node, and in Properties → Resource bindings switch on Write access for that binding, then Save. The toggle is per binding and per node; an import never switches it on for you. The same section lets you add, rebind or remove a node’s bindings by hand.

Keeping a copy of a working version

SupaCloud does not keep a version history for workflows. There is no revisions tab, no diff between yesterday’s graph and today’s, and no restore button — a Save overwrites the stored graph. (Scripts do have revisions; workflows do not.)

So before a risky edit, export the YAML and keep it. That exported document is a complete, re-importable definition, which makes the YAML panel the practical answer to “can I get the old one back?” — and makes a workflows directory in your repository a reasonable habit.

Unrouted email

If you have wired a workflow to an email trigger, this is the page you will eventually need. Messages arriving at SupaCloud’s central trigger mailbox are routed to a workflow by the +suffix in the address they were sent to. Anything that cannot be matched is parked, rather than left to sit in the inbox forever, and lands at /build/workflows/email-unrouted.

The page is a plain table of the parked messages — From, Subject, Attempted address, Received — with two actions per row:

• Create alias mints a real email trigger on a workflow you pick, then moves the message back so the next poll fires that workflow with it. This is the “actually, that one was meant for this workflow” repair.
• Delete discards the message.

A message ends up here when the address carried no +suffix at all, when the suffix matches no workflow alias, when the alias points at a trigger that has since been deleted or disabled, or when the trigger’s own sender or subject filter rejected it. That last case is worth remembering: a filtered-out message is not silently dropped, it is parked.

Admins only, and not linked from anywhere

Reading, re-routing and deleting parked messages all require the workspace admin role; a member gets a permission error. The page also has no link into it from the navigation or the workflows list — reach it by typing or bookmarking /build/workflows/email-unrouted. If your instance has no central mailbox configured, the list is simply empty.

For the trigger style where you poll your own mailbox instead, see Set up an IMAP trigger.

Stop a workflow without deleting it

There is no on/off switch on a workflow itself. What you switch off is the thing that fires it:

1. Open the workflow and select its trigger on the trigger lane.

2. In the trigger properties panel, turn Enabled off.

3. Repeat for every trigger the workflow carries — the list’s Trigger column only ever shows one of them.

A workflow with every trigger disabled keeps its graph, its name and its whole run history, stops reacting to events, and can still be started with Run workflow. That combination is exactly what you want while you are repairing one.

Two related throttles:

• If the workflow is fired by a schedule, pausing that schedule is the cleaner stop — see Set up a schedule.
• The gear in the builder header sets a Concurrent runs limit for this workflow. Leave it blank for no limit; excess runs queue and start as slots open up, rather than being dropped.

Delete a workflow

The trash icon at the right end of a desktop row deletes that workflow, behind a Delete workflow confirmation. (The phone card has no delete button — tapping it opens the builder instead.) Any workspace member may delete a workflow; no admin role is required, and a run still in flight does not block the deletion — that run is removed along with everything else.

Deleting a workflow deletes its run history too

The delete cascades in the database: the graph’s nodes and edges, every trigger, the email aliases derived from those triggers, any schedule that fires this workflow, and every run of it — with the runs of its individual nodes — are removed with it. Until recently the confirmation dialog said the opposite (“past runs are kept”); it now names what actually goes.

Before you delete anything you may want to account for later: export the YAML (above), and read whatever you need from the run history first. If you only want it to stop firing, disable its triggers instead — that keeps everything.

Where the runs go

The list tells you about runs; it is not where you read them. Every execution — started by hand, by a schedule, by a webhook or by an incoming mail — is a run under Runs, with the workflow run as the parent and each node’s execution as a child run beneath it. Open a run there for the full event log, the per-node timings and any approval it is waiting on.

See also

• Build your first workflow — the canvas, the palette and the trigger lane.
• Runs and tasks — why a definition and an execution are separate things.
• Web terminal commands — workflows, workflow <id>, workflow trigger <id>.
• Set up a schedule — the time-driven way to fire one.