> ## 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.

# Workflow Execution Control

> Understand how Overcut manages workflow execution through triggers, resource locking, priority queuing, and event deduplication.

Overcut's workflow execution system ensures predictable, efficient automation by controlling when and how workflows run. This system prevents race conditions, reduces redundant executions, and allows you to prioritize critical workflows.

<CardGroup cols={2}>
  <Card title="Resource Locking" icon="lock">
    Prevents multiple workflows from running simultaneously on the same issue, or PR.
  </Card>

  <Card title="Priority Queuing" icon="list-ol">
    Controls execution order when multiple workflows are queued for the same resource.
  </Card>

  <Card title="Event Deduplication" icon="compress">
    Merges rapid-fire events into single workflow executions with the latest state.
  </Card>

  <Card title="Queue Processing" icon="clock">
    Queued workflows run by priority level, and workflows with the same priority run first-come, first-served.
  </Card>
</CardGroup>

## How Workflow Execution Works

When an event occurs (like opening an issue or creating a PR), Overcut follows this execution pipeline:

<Steps>
  <Step title="Event Received">
    A webhook from GitHub, GitLab, Jira, or manual trigger is received.
  </Step>

  <Step title="Trigger Matching">
    Overcut finds all workflows with matching triggers and conditions.
  </Step>

  <Step title="Resource Locking">
    Each matching workflow is queued for the specific resource (issue or PR) using a lock key.
  </Step>

  <Step title="Event Deduplication">
    If a workflow is already queued for the same resource, events are merged with the latest state.
  </Step>

  <Step title="Priority Ordering">
    Queued workflows are ordered by priority (1-100 scale), then by queue time (FIFO).
  </Step>

  <Step title="Sequential Execution">
    Only one workflow runs per resource at a time, preventing conflicts and race conditions.
  </Step>
</Steps>

## Resource Locking

### Lock Key Structure

Overcut uses **lock keys** to ensure only one workflow runs per resource at a time:

* **Issues**: `owner/repo:issue:123`
* **Pull Requests**: `owner/repo:pr:456`

### Scheduled Workflow

When using "Per-Repository" execution mode, Overcut starts an execution for each repository selected.

For [Scheduled Workflows](/docs/workflows/scheduled-workflows), Overcut automatically **skips a new run if the previous one is still in progress for the same lock key** (issue, PR, or repository). This guarantees that long-running maintenance jobs don’t pile up and overload your workers.

### Why Locking Matters

Without resource locking, multiple workflows could:

* Make conflicting changes to the same issue
* Create duplicate comments or labels
* Waste resources on redundant operations
* Cause race conditions and unpredictable behavior

### Example: Issue Workflow Locking

```
Issue #123 receives rapid events:
1. issue_opened
2. issue_labeled (bug)
3. issue_assigned
4. issue_labeled (urgent)

Lock Key: "myorg/myrepo:issue:123"
Result: All workflows for issue #123 queue behind the lock
Only one workflow runs at a time for this specific issue
```

## Priority Queuing

### Priority Scale (1-100)

Control workflow execution order using numeric priority:

* **1 = Highest Priority** (executes first)
* **5 = Default Priority** (normal workflows)
* **100 = Lowest Priority** (executes last)

<Note>
  Lower numbers execute first. Think of priority as "position in line" - priority 1 is first in line.
</Note>

### Priority Guidelines

* Use the full 1-100 range for fine-grained control
* Create your own prioritization scheme, for example:
  * **1-20**: Critical security scans, system failures
  * **21-40**: Code reviews, bug fixes, urgent issues
  * **41-60**: Normal automation, standard workflows
  * **61-80**: Documentation updates, metrics collection
  * **81-100**: Background analytics, cleanup tasks

### Setting Priority in UI

<Steps>
  <Step title="Open Workflow Builder">
    Navigate to your workflow and click the settings/metadata section.
  </Step>

  <Step title="Set Execution Priority">
    Enter a number between 1-100 in the Priority field. Lower numbers execute first.
  </Step>
</Steps>

### Priority in Action

```
Queue for issue #123 (same lock key):
1. "Update Metrics" (priority: 8) - queued at 10:00:00
2. "Security Scan" (priority: 2) - queued at 10:00:15  
3. "Auto-assign" (priority: 5) - queued at 10:00:30

Execution Order:
1. Security Scan (priority 2) ← Executes first
2. Auto-assign (priority 5) ← Executes second  
3. Update Metrics (priority 8) ← Executes last
```

## Event Deduplication

### How Deduplication Works

When multiple events occur rapidly for the same resource and workflow:

1. **First Event**: Creates queue entry
2. **Subsequent Events**: Merge with existing queue entry
3. **Final State**: Workflow executes with the latest merged state

### Benefits

* **Efficiency**: Reduces redundant executions by 60-80%
* **Accuracy**: Workflows see the final state, not intermediate changes
* **Resource Savings**: Less compute, storage, and API usage
* **Better UX**: Fewer duplicate comments or actions

## Trigger Delays and Execution Control

### How Delays Interact with Queuing

[Trigger delays](/docs/workflows/triggers#trigger-delays) work with the execution control system:

1. **Delay Applied**: When trigger first fires, workflow queues with future `readyAt` time
2. **Event Merging**: Additional events during delay window merge with queued workflow
3. **Priority Respected**: When delay expires, workflow processes according to priority
4. **Lock Acquired**: Workflow executes when it reaches front of priority queue

## Workspace-level Concurrency Limits

Overcut enforces a per-workspace limit on **concurrent workflow executions** based on your subscription plan. This ensures that high demand in one workspace does not impact the rest of your organization.

<Tip>
  Your workspace's concurrent execution limit is determined by your subscription plan. Check your billing settings to see the exact concurrent run count for your workspace.
</Tip>

Use this guidance to manage capacity:

* **Monitor your usage**: Track running workflows in the workspace overview to understand current utilization.
* **Consider workflow duration**: Long-running workflows consume execution slots longer, reducing availability for other triggers.
* **Plan for peak times**: Distribute high-priority workflows across time or adjust trigger frequency when approaching your limit.

## On Hold Release Cycle

When a workspace reaches its concurrency limit, new workflow runs enter an **On Hold** state until capacity becomes available.

### What you will see

* The run timeline shows an On Hold entry with a message indicating that workspace capacity has been reached.
* Your workflow's trigger payload is preserved, so nothing is lost and no manual re-triggering is needed.

### How release works

* When a running execution completes, the oldest On Hold run is automatically released (first-in, first-out within the workspace).
* Released runs resume automatically and progress through normal execution without any user interaction required.

## Related Documentation

* **[Triggers](/docs/workflows/triggers)**: Understanding when workflows start
* **[Advanced Trigger Execution](/docs/reference/trigger-execution)**: Deep dive into multiple triggers, event merging, and priority behavior
* **[Workflow Metadata](/docs/how-to/workflow-builder)**: Configure timeout, priority, default model, and status update settings
* **[Building Blocks](/docs/building-blocks)**: Core workflow components
* **[Import & Export](/docs/workflows/workflow-import-export)**: Managing workflow definitions
* **[Overcut Playbooks](/docs/quick-starts/playbooks)**: Ready-to-use workflow templates with priority settings