Build your first workflow

By the end of this tutorial you will have a working multi-node workflow: an agent node that does some work, a gate node that branches on the result, a human node that waits for your approval, and a wired-up manual trigger to start it all. You will then run it and export its YAML. Allow about twenty minutes.

What you need

• A SupaCloud workspace with at least one project.
• The workspace role admin or member (viewers cannot create workflows).

1. Open the workflow builder

1. Open Build → Workflows.

2. Press New workflow. The builder opens in a new full-screen canvas — the header shows the workflow name field, a Canvas / YAML toggle, and the Run button.

3. Click the name field and type a name, for example review-and-approve.

The canvas opens with an empty flow. The left panel is the node palette — six accordion groups (Flow Control, Agent & AI, Code, Data, Notify, Mail) plus trigger sections. Use Ctrl+K to focus the palette search bar at any time.

2. Add a trigger

A workflow does not start until at least one trigger is configured. For this tutorial you will use the simplest option: Manual.

1. In the palette, open the Manual & Time trigger group.

2. Click the Manual tile (dashed border). A trigger node labelled manual appears on the trigger lane at the top of the canvas, and the toolbar shows a trigger badge.

Tip

Triggers are workflow-level configuration, not canvas nodes you wire between other steps. The trigger lane sits above the main flow area and is visually separated.

3. Add an Agent node

1. In the palette, open the Agent & AI group and click Agent. An agent node drops onto the canvas.

2. Click the node to select it. The Properties panel opens on the right.

3. Set a Node key — a short identifier used in templating, for example review. Node keys must be unique inside the workflow.

4. Choose an Agent type from the dropdown (for example claude).

5. Write a prompt in the Prompt field, for example:

   Review the latest commit in ${{ trigger.repository }} and summarise findings.

   The ${{ trigger.* }} namespace lets you reference the trigger payload; ${{ steps.<key>.<field> }} references an upstream node’s result (the agent step’s branch, summary, pr_url, or cost).

6. Click Save in the toolbar (or press the button) to persist the change.

4. Add a Gate node

A gate evaluates a boolean condition over upstream output and branches the run down a true or false path — no LLM call, no task, evaluated inline by the engine.

1. In the palette, open the Flow Control group and click Gate. A diamond-shaped gate node appears.

2. Select it to open its properties panel.

3. Set its Node key to check.

4. Build the condition using the Condition builder — for example:

   • Left: nodes.review.task_status
   • Operator: eq
   • Right: completed

   This fires the true handle when the agent node has completed successfully.

5. Connect the nodes: hover over the out handle at the bottom of the review agent node until it glows, then drag to the top (input) handle of the check gate node. Release to create the edge.

The gate card shows a TRUE label on the bottom-left handle and a FALSE label on the bottom-right handle. In a run view the fired branch is highlighted.

5. Add a Human node

The human node pauses the run and waits for a person to approve or reject before either branch continues. It is reachable from the web UI and from Telegram.

1. In the palette, open the Flow Control group and click Human. A human node appears.

2. Select it and set its Node key to approve.

3. Fill in the Approval title field: Ready to merge?

4. Optionally fill in the Instructions field with context for the approver.

5. Connect the true handle of the check gate node to the input handle of the approve human node.

6. For the false path, add an End node from the palette, set its key to skip, and connect the false handle of check to it. This terminates the run cleanly when the condition is not met.

Approved and Rejected handles

The human node exposes two output handles: approved (bottom-left) and rejected (bottom-right). Wire each to the appropriate next step. A run sits in waiting state until you (or a teammate) post a decision from the run detail page or via the Telegram bot.

6. Wire the remaining paths and tidy the canvas

1. Add one more End node (key: done) and connect the approved handle of approve to it.

2. Add a final End node (key: rejected) and connect the rejected handle of approve to it.

3. Click Tidy in the toolbar to auto-layout the graph into a clean top-to-bottom flow.

4. Click Save.

Your canvas now has: [Manual trigger] → review → check → (true) approve → approved/rejected ends; (false) skip end.

7. Run the workflow

1. Click the Run button (play icon) in the top-right of the toolbar. The run starts immediately with the manual trigger.

2. You land on the run detail page — each node shows its current state (pending, running, completed, skipped, waiting).

3. When the run reaches the approve human node it enters waiting state and the node pulses on the canvas. Open the run detail page and use the Approve or Reject button to resolve it.

Tip

You can also resolve a human node from the Telegram bot: the bot posts an inline-button message with Approve / Reject when the run enters waiting.

8. Export the YAML

The workflow’s full typed-node graph round-trips through a server-authoritative YAML format — useful for version control, sharing, or importing into another workspace.

1. In the toolbar, click the YAML toggle (next to Canvas).

2. Click Export to load the current saved graph into the editor panel.

3. Click Copy to copy it to the clipboard, or edit it directly and click Import as new to create a fresh workflow from the modified YAML.

The YAML encodes every node (kind, key, config) and every edge (source_handle), preserving the branching logic exactly.

What you learned

• The node palette organises all node types into collapsible groups; Ctrl+K focuses the search.
• Triggers live on a dedicated trigger lane — add them from the palette’s trigger sections.
• Agent nodes run a task; Gate nodes branch on a condition (true / false handles); Human nodes pause for a decision (approved / rejected handles); End nodes terminate a branch.
• Connect nodes by dragging from a source handle to a target handle.
• Tidy auto-layouts the canvas; Save persists; Run starts a manual run.
• The YAML panel exports the full typed-node graph for version control or import.

Next steps

• Web terminal command reference — trigger a workflow from the CLI with workflow trigger <id>.
• Your first agent run — understand how agent tasks work inside a workflow.
• Workspaces and Organizations