Skip to main content
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.

Resource Locking

Prevents multiple workflows from running simultaneously on the same issue, or PR.

Priority Queuing

Controls execution order when multiple workflows are queued for the same resource.

Event Deduplication

Merges rapid-fire events into single workflow executions with the latest state.

Queue Processing

Queued workflows run by priority level, and workflows with the same priority run first-come, first-served.

​
How Workflow Execution Works

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

Event Received

A webhook from GitHub, GitLab, Jira, or manual trigger is received.
2

Trigger Matching

Overcut finds all workflows with matching triggers and conditions.
3

Resource Locking

Each matching workflow is queued for the specific resource (issue or PR) using a lock key.
4

Event Deduplication

If a workflow is already queued for the same resource, events are merged with the latest state.
5

Priority Ordering

Queued workflows are ordered by priority (1-100 scale), then by queue time (FIFO).
6

Sequential Execution

Only one workflow runs per resource at a time, preventing conflicts and race conditions.

​
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, 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)
Lower numbers execute first. Think of priority as “position in line” - priority 1 is first in line.

​
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

1

Open Workflow Builder

Navigate to your workflow and click the settings/metadata section.
2

Set Execution Priority

Enter a number between 1-100 in the Priority field. Lower numbers execute first.

​
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 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