Feature 7: Workflows #

Overview #

Semaphore currently treats each task template as an independent unit — there is no built-in way to chain multiple templates into a multi-step execution pipeline. Users who need to run playbook A, then provision infrastructure with Terraform, then run playbook B must either combine everything into a single monolithic template, or script API calls externally. This feature introduces Workflows — directed acyclic graphs (DAGs) of task templates that execute with conditional branching, variable passing between steps, and optional human approval gates. The design draws from AWX Workflow Job Templates, Rundeck job workflows, and Jenkins/GitLab CI pipeline concepts.

Motivation #

• Task chaining is the most requested missing feature — multiple GitHub issues (#3182, #2334, #1383, #836, #2281, #3088) request the ability to link task templates into sequential or conditional chains.
• Users work around the limitation today by calling the Semaphore API from shell scripts, abusing cron dependencies, or merging unrelated automation into a single oversized playbook — all of which lose per-step visibility and error isolation.
• AWX Workflow Job Templates are a primary reason users choose AWX over Semaphore. AWX workflows support DAG-based execution, conditional paths (on_success / on_failure / always), approval nodes, inventory overrides per node, and artifact passing between jobs. Bringing similar capabilities to Semaphore closes a major competitive gap.
• Rundeck solves the same problem with linear job workflows that support per-step error handlers and multiple execution strategies (node-first, sequential, parallel).
• Jenkins and GitLab CI/CD pipelines demonstrate that conditional branching, parallel execution, manual approval gates, and artifact passing between stages are table-stakes features for any automation platform.

Detailed Specification #

Community #

7.1 Workflow Templates #

Goal: Introduce a new top-level entity — the Workflow Template — that defines a DAG of task template nodes with conditional edges.

Requirements:

• A Workflow Template belongs to a project and has a name, description, and an ordered list of nodes.
• Each node references an existing task template within the same project.
• Nodes are connected by directed edges with a condition: on_success, on_failure, or always.
• The workflow is validated as a DAG on save — cycles are rejected.
• A workflow must have exactly one root node (the entry point).
• Nodes with no outgoing edges are leaf nodes — the workflow completes when all active leaf nodes finish.
• Workflow Templates appear in a dedicated “Workflows” section in the project sidebar.

Related issues: #3182, #2334, #1383, #836

7.2 Workflow Execution Engine #

Goal: Execute workflow nodes in the correct order, respecting edge conditions and parallelism.

Requirements:

• When a workflow is launched, the engine starts the root node as a normal task.
• When a node completes, the engine evaluates all outgoing edges:
  • on_success edges fire only if the node succeeded.
  • on_failure edges fire only if the node failed.
  • always edges fire regardless of the node’s outcome.
• If a node has multiple outgoing edges that match, the downstream nodes execute in parallel.
• Convergence behavior: if a node has multiple incoming edges, it waits for all parent nodes to complete before executing (ALL-convergence). A future enhancement may add ANY-convergence.
• If no outgoing edges match (e.g., a node fails and only on_success edges exist), that branch stops and the workflow marks the branch as terminated.
• The overall workflow status is determined by the final status of all leaf nodes: success (all succeeded), failed (any failed), or partially failed (mixed).

Related issues: #2281, #3088

7.3 Workflow Run Dashboard #

Goal: Provide a unified view of a workflow execution with per-node status, logs, and timing.

Requirements:

• A workflow run page shows:
  • The DAG graph with each node colored by status (pending, running, succeeded, failed, skipped).
  • Click on any node to expand its task log inline.
  • Overall workflow duration and per-node duration.
  • A summary bar showing counts of succeeded/failed/skipped/pending nodes.
• Workflow runs appear in the project’s task history with a distinct icon/badge to differentiate them from single-task runs.
• API: GET /api/project/{id}/workflows/{workflow_id}/runs with pagination.

7.4 Variable Passing Between Nodes #

Goal: Allow the output of one node to be used as input to downstream nodes, enabling data flow through the workflow.

Requirements:

• Task templates can emit output variables by writing key-value pairs to a well-known file (e.g., $SEMAPHORE_OUTPUT_VARS or via Ansible set_stats).
• Output variables from a completed node are automatically injected as extra variables into downstream nodes.
• If multiple parent nodes emit the same variable name, the last-completed parent’s value wins (with a warning logged).
• Output variables are displayed in the workflow run UI alongside each node.

Related issues: #3182

7.5 Workflow Scheduling and API Triggers #

Goal: Allow workflows to be scheduled on a cron basis or triggered via API/webhook.

Requirements:

• Workflows can be scheduled using the same cron scheduler that individual task templates use.
• API endpoint: POST /api/project/{id}/workflows/{workflow_id}/run to trigger a workflow run.
• Webhook trigger: workflows can be triggered by incoming webhooks, similar to existing task template webhooks.
• Survey variables can be defined at the workflow level and passed to the root node (or distributed to specific nodes).

Related issues: #3088

Pro #

7.6 Visual Workflow Editor #

Goal: Provide a drag-and-drop graphical editor for designing workflows in the UI.

Requirements:

• Canvas-based editor where users can:
  • Add nodes by selecting from existing task templates.
  • Draw edges between nodes with a condition selector (on_success / on_failure / always).
  • Rearrange node positions for readability.
  • Delete nodes and edges.
• Real-time DAG validation — highlight cycles or disconnected nodes as the user builds.
• The editor generates the workflow definition JSON, which is stored on save.
• Community users can create workflows via a simpler list/form-based UI or directly through the API.

7.7 Per-Node Overrides #

Goal: Allow overriding template settings (inventory, credentials, environment) at the workflow node level.

Requirements:

• Each workflow node can optionally override the referenced template’s:
  • Inventory (select a different inventory for this step).
  • Credentials (use different SSH keys or vault passwords).
  • Variable Group / Environment (attach additional or alternative variable groups).
  • Extra CLI arguments.
• Overrides are stored on the workflow node, not on the template — the original template remains unchanged.
• Use case: reuse the same “deploy” template across staging and production by overriding the inventory at the workflow level.

7.8 Approval Gates #

Goal: Pause workflow execution at designated points to wait for human approval before proceeding.

Requirements:

• A workflow node can be marked as an “approval gate” instead of referencing a task template.
• When the workflow reaches an approval gate, execution pauses and a notification is sent to designated approvers.
• Approvers can approve or reject the gate from the workflow run UI or via API.
• Configurable timeout: if no decision is made within the timeout period, the gate auto-rejects (default: 24 hours).
• Rejection stops the downstream branch; approval continues execution.
• Approval decisions are logged with the approver’s identity and timestamp.

Enterprise #

7.9 Workflow RBAC #

Goal: Control who can create, edit, execute, and approve workflows based on roles and permissions.

Requirements:

• New permissions: workflow.create, workflow.edit, workflow.execute, workflow.approve.
• Project admins can assign workflow permissions to team members.
• Approval gates can specify which roles or users are authorized to approve.
• Workflow execution history is included in the audit log.

7.10 Cross-Project Workflows #

Goal: Allow workflows to reference task templates from other projects, enabling organization-wide automation pipelines.

Requirements:

• Workflow nodes can reference templates in other projects (subject to permissions).
• Cross-project references use the target project’s inventories, credentials, and variable groups by default (with optional overrides).
• Use case: a deployment pipeline that spans infrastructure (Project A), application (Project B), and monitoring (Project C).

7.11 Workflow Versioning and Rollback #

Goal: Maintain a version history of workflow definitions so changes can be reviewed and rolled back.

Requirements:

• Every save creates a new version of the workflow definition.
• Version history is viewable in the UI with a diff between versions.
• Any previous version can be restored as the current active version.
• Workflow runs record which version of the definition was used.

Database Schema Changes #

New tables:

• project__workflow_template — workflow definitions (project_id, name, description, definition JSON, created_at, updated_at)
• project__workflow_template_node — workflow nodes (workflow_template_id, task_template_id, node_type, position_x, position_y, overrides JSON)
• project__workflow_template_edge — edges between nodes (workflow_template_id, source_node_id, target_node_id, condition)
• project__workflow_run — workflow execution records (workflow_template_id, status, started_at, finished_at, triggered_by)
• project__workflow_run_node — per-node execution state (workflow_run_id, node_id, task_id, status, output_vars JSON, started_at, finished_at)

Enterprise-only tables:

• project__workflow_template_version — version history (workflow_template_id, version, definition JSON, created_by, created_at)
• project__workflow_approval — approval gate decisions (workflow_run_node_id, approved_by, decision, decided_at)

API Endpoints #

• GET/POST /api/project/{id}/workflow-templates — list/create workflow templates
• GET/PUT/DELETE /api/project/{id}/workflow-templates/{wf_id} — get/update/delete workflow template
• POST /api/project/{id}/workflow-templates/{wf_id}/run — trigger a workflow run
• GET /api/project/{id}/workflow-templates/{wf_id}/runs — list workflow runs
• GET /api/project/{id}/workflow-runs/{run_id} — get workflow run details with node statuses
• POST /api/project/{id}/workflow-runs/{run_id}/nodes/{node_id}/approve — approve/reject an approval gate (Pro)
• GET /api/project/{id}/workflow-templates/{wf_id}/versions — list workflow versions (Enterprise)
• POST /api/project/{id}/workflow-templates/{wf_id}/versions/{v}/restore — restore a workflow version (Enterprise)

Configuration #

New configuration options: