> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overcut.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows

> Understand how Workflows power automation in Overcut with triggers, actions, agents, and visual flow design.

Workflows are the heart of Overcut automation. They define end-to-end automations that automatically respond to events, execute complex multi-step processes, and coordinate AI agents to accomplish tasks. Think of them as visual programming for automation: you design the flow, and Overcut executes it reliably.

***

## What is a Workflow?

A **Workflow** is a complete automation that defines:

* **When** it should run (the trigger)
* **What** should happen (the steps and actions)
* **How** steps connect and flow (the execution graph)

Workflows are Overcut's automation pipelines: a visual, declarative way to build complex automation without writing code.

A Workflow is one executable automation. To coordinate the same work item across multiple workflows over time, use an [Orchestration](https://docs.overcut.ai/docs/orchestrations/overview.md) to manage the goal and the routing between runs.

> **Visual Design**
>
> Design workflows using a visual canvas with drag-and-drop blocks for triggers, actions, and agents.

> **Event-Driven**
>
> Automatically respond to GitHub events, Jira updates, mentions, slash commands, or scheduled triggers.

> **AI-Powered**
>
> Integrate AI agents that can make decisions, generate content, and collaborate with users.

> **Multi-Step**
>
> Build complex workflows with dependencies, parallel execution, and conditional logic.

***

## Core Components

Every Workflow consists of these fundamental building blocks:

### **Trigger**

The event that starts your workflow execution. Triggers can be:

* **GitHub events**: Pull requests opened, issues labeled, comments posted
* **Jira events**: Issues created, updated, or commented on
* **Interactive triggers**: `@overcut` mentions or slash commands like `/review`
* **[Scheduled Workflows](https://docs.overcut.ai/docs/workflows/scheduled-workflows.md)**: Time-based triggers for recurring tasks like nightly scans or weekly reports

> [!NOTE]
>
> Every Workflow must have exactly one trigger node. This is the entry point that determines when your automation runs.

### **Actions**

* **[`git.clone`](https://docs.overcut.ai/docs/workflows/git-clone)**: Clone repositories for code analysis
* **[`repo.identify`](https://docs.overcut.ai/docs/workflows/repo-identify)**: Automatically determine relevant repositories for tickets
* **[`script.run`](https://docs.overcut.ai/docs/workflows/run-script)**: Run deterministic bash scripts without invoking an AI agent or LLM
* **[`agent.run`](https://docs.overcut.ai/docs/workflows/agent-run)**: Single-agent execution for straightforward tasks
* **[`agent.session`](https://docs.overcut.ai/docs/workflows/agent-session)**: Multi-agent sessions with coordination and iteration

> [!TIP]
>
> To read about the differences between the two agent actions, see the [Agent Differences](https://docs.overcut.ai/docs/workflows/agent-differences.md) page.

### **Flow**

The connections between steps that define execution order and dependencies.

***

### **Event Processing Flow**

1. **Event Reception**: Webhooks from GitHub, Jira, or other providers are received
2. **Normalization**: Events are converted to standardized formats
3. **Trigger Matching**: Overcut evaluates which Workflows should run
4. **Execution Queuing**: Matching workflows are queued for execution
5. **Step Processing**: Each step runs according to the defined flow
6. **State Management**: Context and results are preserved between steps
7. **Completion**: Final results are published and cleanup occurs

***

## Creating a Workflow

Open **Workflows** in the relevant project, select **Add workflow**, then choose an option:

| Option | When to use it |
| - | - |
| **Build with chat** | When chat is enabled, start a new workflow-design chat that helps you design the workflow. |
| **Build from scratch** | Open a new workflow in the [Workflow Builder](https://docs.overcut.ai/docs/how-to/workflow-builder.md) for manual configuration. |
| **Add from playbook** | Open the [Playbook Catalog](https://docs.overcut.ai/docs/quick-starts/playbooks.md) to browse, preview, and install a public workflow template. |
| **Install from library** | Install a project-owned copy of a [Workspace Library](https://docs.overcut.ai/docs/reference/workspace-library.md) workflow template. Shown if you can view the Library. |
| **Import from file** | Start the [file import flow](https://docs.overcut.ai/docs/workflows/workflow-import-export.md) for an exported workflow file. |

### **Step 1: Define the Problem**

Start by understanding what you want to automate:

* What event should trigger the workflow?
* What should happen when it runs?
* What are the expected outcomes?

### **Step 2: Design the Flow**

Break your automation into logical steps:

* **Preparation**: Clone repos, gather context, validate inputs
* **Processing**: Run AI agents, perform analysis, make decisions
* **Action**: Update tickets, create branches, send notifications
* **Cleanup**: Archive results, update status, close sessions

### **Step 3: Configure Components**

For each step, configure:

* **Parameters**: Static values or dynamic variables from previous steps
* **Instructions**: Specific guidance for AI agents
* **Timeouts**: Maximum execution time, on steps that support it such as [Run Script](https://docs.overcut.ai/docs/workflows/run-script.md)

### **Step 4: Connect the Flow**

Overcut workflows run their steps in a single sequence, one after another. Each workflow is one clear path from trigger to outcome, which keeps it:

* **Predictable**: each agent step gets one focused task and only the context that task needs, so its results stay consistent from run to run.
* **Traceable**: every run follows the same path, step by step.
* **Debuggable**: when a run fails, you know which step to look at.
* **Reusable**: one workflow can serve several triggers and orchestrations.
* **Interchangeable**: you can replace one workflow with another without rewiring the rest.
* **Composable**: focused workflows combine into larger processes.

Branching and repetition happen one level up. An [orchestration](https://docs.overcut.ai/docs/orchestrations/overview.md) routes a work item between workflows based on each run's result, and runs a workflow again until the goal is met or a limit is reached. Concurrency happens inside a step: in a [Multi-Agent Session](https://docs.overcut.ai/docs/workflows/agent-session.md), the coordinator agent splits the work across specialized agents and merges the results.

***

## Advanced Features

### **Template Variables**

Use dynamic values throughout your workflow:

* **`{{trigger.issue.title}}`**: Access trigger event data
* **`{{outputs.git-clone.repositoryPath}}`**: Reference previous step outputs
* **`{{params.base_branch}}`**: Reference a [context parameter](https://docs.overcut.ai/docs/reference/context-parameters.md), a value that each project, repository, workflow, orchestration, or agent can set for itself

For [Run Script](https://docs.overcut.ai/docs/workflows/run-script.md) steps, pass dynamic workflow data through **Environment Variables** instead of template-interpolating the **Bash Script** body. This keeps trigger text and previous step output as data that the script can read from environment variables.

> [!TIP]
>
> See the complete [Event Context Reference](https://docs.overcut.ai/docs/reference/event-context.md) for all available trigger properties and practical examples.

### **Inspect Run Context**

Open a workflow run's details and select **Context** to open the **Run Context** panel. The panel shows the actual `trigger` data, step `outputs`, and resolved context parameters under `params` available to that run's steps and templates.

Use **Run Context** to confirm values used by template expressions such as `{{trigger.issue.title}}`, `{{outputs.<stepId>.<field>}}`, and `{{params.<key>}}`. The JSON is read-only, and step outputs update while the run executes so you can troubleshoot variables and verify what each completed step produced.

### **Monitoring**

Overcut provides visibility into workflow and agent behavior through:

* **Workflow status**: Track workflow progress (Running, Completed, Failed, Timeout)
* **Agent status**: Monitor agent sessions (Running, InSession, WaitingForReply, Terminating, Completed, Failed)
* **Execution logs**: Detailed logs for each step and agent with the full tool calls and context available to the agent

### **Agent Engine Indicators**

Agent engine indicators help you confirm which engine powers each workflow and step.

* **Workflow catalog**: Each workflow card shows the engine logo so you can compare workflows at a glance.
* **Run details**: Step lists include the engine logo for each step, helping you verify engine usage during execution.

> [!TIP]
>
> Use engine indicators to validate that workflows and steps align with your team’s preferred agent engines before you share or reuse them.

### **State Management**

Context is preserved throughout execution:

* **Workflow Context**: Global variables accessible to all steps
* **Step Outputs**: Results from each step available to subsequent steps

***

## Next Steps

Now that you understand Workflows, explore these topics:

* **[Workflow Builder](https://docs.overcut.ai/docs/how-to/workflow-builder.md)**: Configure and connect the steps in your workflow
* **[Triggers](https://docs.overcut.ai/docs/workflows/triggers.md)**: Learn about different trigger types and configuration
* **[Playbook Catalog](https://docs.overcut.ai/docs/quick-starts/playbooks.md)**: Browse, preview, and install public workflow templates
* **[Workspace Library](https://docs.overcut.ai/docs/reference/workspace-library.md)**: Manage reusable workflow templates for your workspace
* **[Import & Export Workflows](https://docs.overcut.ai/docs/workflows/workflow-import-export.md)**: Move workflows between projects and workspaces
* **[Actions and Agents](https://docs.overcut.ai/docs/workflows/agent-differences.md)**: Understand the differences between agent.run and agent.session
* **[Building Blocks](https://docs.overcut.ai/docs/building-blocks.md)**: Deep dive into the core components
* **[Quick Starts](https://docs.overcut.ai/docs/quick-starts.md)**: Step-by-step guides for common workflows
* **[Repository Management](https://docs.overcut.ai/docs/repositories/repository-mapping.md)**: Understand how workflows interact with code

Ready to build your first Workflow? Start with a simple workflow and gradually add complexity as you become familiar with the platform.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.