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

# Triggers

> Triggers define when a Workflow should start, based on events from GitHub, GitLab, Jira, ClickUp, or manual input.

Triggers are the starting point for every automation in Overcut.

Each trigger maps to a standardized event from an external provider, such as GitHub, GitLab, Jira, ClickUp, or Overcut's own API. When that event fires, Overcut evaluates your Workflow and starts the flow if all conditions are met.

## Supported Platforms

Overcut supports triggers from multiple platforms, with events normalized to a consistent format:

* **GitHub**: Pull requests, issues, and review activity
* **GitLab**: Merge requests, issues, and comments
* **Jira**: Issue lifecycle, comments, and status changes
* **Bitbucket**: Pull requests, issues, and comments
* **Azure DevOps**: Work items, pull requests, and comments
* **ClickUp**: Task creation, updates, status changes, and comments
* **Slack**: Registered channels, through mentions, slash commands, and (in Active mode) top-level channel messages. See [Slack integration](/docs/integrations/slack).
* **Custom Events**: Workspace-defined event types fired from any third-party system via a public webhook URL. Use for CI servers, monitoring tools, internal scripts, or anything without a native integration. See [Custom Events](/docs/integrations/custom-events).

<Note>
  All platforms use the same trigger types and conditions. Overcut automatically normalizes platform-specific events into standardized formats, so your workflows work consistently regardless of the source platform.
</Note>

## Trigger Categories

<CardGroup cols={2}>
  <Card title="Issue Events" icon="circle-dot" href="#issue-events">
    Kick off flows when issues are opened, labeled, edited, or commented on.
  </Card>

  <Card title="Pull Request Events" icon="code-merge" href="#pull-request-events">
    Start workflows for PR creation, merging, review activity, and more.
  </Card>

  <Card title="CI Workflow Events" icon="diagram-project" href="#ci-workflow-events">
    Trigger workflows when CI runs are queued, started, completed, failed, cancelled, or timed out.
  </Card>

  <Card title="Manual, Mentions & Slash Commands" icon="person" href="/docs/workflows/trigger-with-slash-command">
    Run workflows with a button click, by @mentioning Overcut, or via custom slash commands.
  </Card>

  <Card title="Scheduled" icon="calendar" href="/docs/workflows/scheduled-workflows">
    Run workflows on a cron-based schedule.
  </Card>

  <Card title="Custom Events" icon="webhook" href="/docs/integrations/custom-events">
    Fire workflows from any third-party system that can send an HTTP request: CI, monitoring, or your own scripts.
  </Card>
</CardGroup>

## Scheduled Triggers

[Scheduled Workflows](/docs/workflows/scheduled-workflows) let you run automations on a **cron-based schedule**: hourly, daily, weekly, or any custom interval. They are ideal for maintenance, reporting, and other recurring tasks that aren’t tied to an external event.

<Tip>
  Scheduled triggers are evaluated in your workspace time-zone and support **Single** and **Per-Repository** execution modes (see [Scheduled Workflows → Execution Modes](/docs/workflows/scheduled-workflows#execution-modes)).
</Tip>

## Trigger Delays

You can configure an optional delay before workflow execution to allow related updates to complete. This is particularly useful for:

* **Issue creation**: Wait for fields to be filled out and labels to be added
* **PR updates**: Allow time for description edits and initial comments
* **Field changes**: Let users complete their input before processing begins

<Note>
  **Interactive triggers** (slash commands and mentions) always ignore delay settings and execute immediately for responsive user experience.
</Note>

**When to use delays:**

* **1-2 minutes**: For issue/PR creation to allow the user to complete the initial setup
* **No delay**: For immediate response needs or when context is already complete

**Delay behavior:**

* Delays are applied when the trigger is first detected
* If additional related events occur during the delay window, the timer resets
* This ensures the workflow waits for activity to settle before executing
* During delays, events automatically merge through [event deduplication](/docs/workflows/workflow-execution-control#event-deduplication)

## Multi-trigger orchestration (OR logic)

You can configure multiple triggers for a single workflow. When an event occurs, all triggers are evaluated in random order. If any trigger matches the event, the workflow is triggered using that matching trigger's configuration: its delay, filters, and execution mode remain intact. Evaluation stops as soon as one trigger matches.

<Steps>
  <Step title="Single trigger setup">
    Use one trigger when the workflow should start from exactly one event source (for example, <code>issue\_opened</code>). The trigger simply relays that event to the first downstream step.
  </Step>

  <Step title="Multi-trigger setup">
    Add multiple triggers (for example, <code>issue\_labeled</code> or <code>pull\_request\_merged</code>) when the workflow should start if **any** of those events occur. The dispatcher evaluates triggers in random order and starts the workflow as soon as one trigger matches; all other triggers are skipped for that event.
  </Step>
</Steps>

<Callout title="Validation guardrails" type="warning">
  You can mix scheduled, event, and manual triggers in a single workflow, but there are some limitations:

  * Only one scheduled trigger is allowed per workflow; use cron expressions within that trigger if you need multiple execution times.
  * Each type of trigger requires a different configuration:
    * Scheduled triggers require a cron expression.
    * Event triggers require a set of filters.
    * Manual triggers require a slash command.
</Callout>

## Editing triggers in the Properties panel

Selecting any trigger highlights it inside the **Properties panel** on the right. The form reconfigures itself to show only the fields that apply to the selected trigger, so you are never editing irrelevant inputs. Live previews for manual slash commands update as you type, and any schema validation issues are surfaced inline before you can publish.

<Tabs>
  <Tab title="Event triggers">
    <ul>
      <li>Use the **conditions builder** to stack repository, project, label, or author filters. Each row maps directly to the trigger schema, so what you configure visually is what the dispatcher enforces.</li>
      <li>Event-specific fields (such as issue metadata versus pull-request metadata) appear automatically, keeping the available filters in sync with the selected event.</li>
      <li>CI workflow triggers surface filters for run status, conclusion, branch, commit SHA, run ID, workflow name or URL, pull request association or ID, and job count.</li>
      <li>Inline warnings appear beside any incomplete filter rows: for example, if you add a label condition but leave the value empty, the panel flags it before allowing you to save.</li>
      <li>The **delay** setting is available for all event triggers. It allows you to delay the workflow execution by a certain number of seconds.</li>
    </ul>
  </Tab>

  <Tab title="Scheduled triggers">
    <ul>
      <li>Enter a **cron expression**; inline validation confirms the format before the schedule is saved.</li>
      <li>Select an **execution mode** (Single vs. Per-Repository) so the dispatcher knows whether to run once or per resource.</li>
    </ul>
  </Tab>

  <Tab title="Manual triggers">
    <ul>
      <li>Define the required **slash command** (for example, <code>/review</code>) and whether an <code>@overcut</code> mention is required. The panel blocks saves until the command field is populated.</li>
      <li>Use the built-in **slash command preview** to confirm the exact syntax builders will type before sharing instructions with your team.</li>
      <li>Create multiple manual triggers to allow different slash commands to trigger the same workflow.</li>
    </ul>
  </Tab>
</Tabs>

***

## Issue Events

Issue triggers include lifecycle actions (opened and closed), content updates, and status transitions. Use **State Change** when an issue moves between workflow states without being created or closed.

<ul>
  <li>issue\_opened : Issue was created.</li>
  <li>issue\_closed : Issue was closed.</li>
  <li>issue\_edited : Title or body changed.</li>
  <li>issue\_assigned : Assignee added.</li>
  <li>issue\_unassigned : Assignee removed.</li>
  <li>issue\_labeled : Label was added.</li>
  <li>issue\_unlabeled : Label was removed.</li>
  <li>issue\_commented : New comment was posted on an issue.</li>
</ul>

<Note>
  **State Change** is an **Issue Action** option in the trigger filters. It applies to status transitions that do **not** create or close the issue (for example, Backlog → In Progress). Use **opened** and **closed** when you want to react to creation or closure events, even if the status also changes at the same time.
</Note>

<Note>
  **Azure DevOps tags:** ADO does not emit `issue_labeled`/`issue_unlabeled`. A work-item tag change arrives as `issue_edited`. To trigger on an ADO tag, select **Issue edited** and add a condition like `context.trigger.labelsAdded contains "<tag>"`. The `labelsAdded`/`labelsRemoved` arrays are available on label changes across all providers. See [Event Context](/docs/reference/event-context#label-operations).
</Note>

## Pull Request Events

<ul>
  <li>pull\_request\_opened : Pull request was opened.</li>
  <li>pull\_request\_closed : Pull request was closed without merge.</li>
  <li>pull\_request\_merged : Pull request was merged into base.</li>
  <li>pull\_request\_edited : Title or description of PR was changed.</li>
  <li>pull\_request\_reviewed : A review was submitted (approve/request changes).</li>
  <li>pull\_request\_assigned : An assignee was added to the pull request.</li>
  <li>pull\_request\_unassigned : An assignee was removed from the pull request.</li>
  <li>pull\_request\_labeled : Label was added to the pull request.</li>
  <li>pull\_request\_unlabeled : Label was removed from the pull request.</li>
  <li>pull\_request\_commented : A general comment was posted on the pull request.</li>
  <li>pull\_request\_review\_commented : An inline code comment was posted during review.</li>
</ul>

## CI Workflow Events

CI workflow events fire when a pipeline run changes state in a connected CI provider (GitHub Actions, GitLab CI, Azure DevOps Pipelines, or Bitbucket Pipelines). When the run is associated with a pull request, `trigger.pullRequest.*` fields are also available, gated on `trigger.ciWorkflow.isPullRequest`.

<ul>
  <li>ci\_workflow\_queued : A CI run entered the queue. Use this to track pipeline wait times or alert on queuing delays.</li>
  <li>ci\_workflow\_started : A CI run started executing. Useful for notifying the team that a build is in progress.</li>
  <li>ci\_workflow\_completed : A CI run finished regardless of outcome. Check `trigger.ciWorkflow.status` for the result.</li>
  <li>ci\_workflow\_failed : A CI run ended with a failure. Trigger notifications, create follow-up issues, or post PR comments.</li>
  <li>ci\_workflow\_cancelled : A CI run was cancelled before completion.</li>
  <li>ci\_workflow\_timed\_out : A CI run stopped after exceeding its time limit.</li>
</ul>

<Tip>
  For the full list of `trigger.ciWorkflow.*` template variables available in CI events, see the [CI Workflow Event Properties](/docs/reference/event-context#ci-workflow-event-properties) section in the Event Context Reference.
</Tip>

## Manual, Mention & Slash Command

<ul>
  <li>manual : Manually triggered using a slash command on an issue, PR, comment, or registered Slack channel.</li>
  <li>mention : Overcut is @mentioned in an issue, PR, comment, or registered Slack channel. A plain `@overcut` mention in Slack fires this trigger, not <code>slash\_command</code>.</li>
  <li>slash\_command : A configured slash command is detected. In repository and ticket comments the command appears as you configured it (e.g. <code>/review</code>). In Slack, commands run as <code>/overcut \<command></code> (e.g. <code>/overcut review</code>); the token after the <code>/overcut</code> bot prefix is what matches your trigger's SlashCommand field.</li>
  <li>channel\_message : A top-level message is posted in a registered Slack channel set to **Watch all messages**. Use trigger conditions (sender, keywords) to filter.</li>
</ul>

<Note>
  A <code>slash\_command</code> trigger fires when Overcut detects the configured command string.

  * **Repository and ticket comments** (GitHub, GitLab, Bitbucket, Azure DevOps, Jira): the trigger matches the command as you configured it, for example <code>/review</code>. Enable <code>requireMention</code> to require an <code>@overcut</code> mention before the command.
  * **Registered Slack channels**: the user types <code>/overcut \<command></code>; the token after <code>/overcut</code> is matched against the SlashCommand field. A plain <code>@overcut</code> message in Slack does **not** match a slash-command trigger; configure a <code>mention</code> trigger for that.

  For setup instructions, see the [Slash Command Guide](/docs/workflows/trigger-with-slash-command). For Slack-specific setup, see [Slack integration](/docs/integrations/slack).
</Note>

## How Triggers Are Evaluated

Overcut matches incoming webhook payloads against the configured trigger type and optional filters, then manages execution through resource locking and priority queuing.

<Steps>
  <Step title="Event Received">
    A webhook from GitHub/GitLab/Jira or a manual call is received by Overcut.
  </Step>

  <Step title="Event Normalization">
    Platform-specific events are converted to standardized formats (e.g., Jira issue events become <code>issue\_opened</code>, <code>issue\_commented</code>).
  </Step>

  <Step title="Match Trigger Type">
    The normalized event is compared to the trigger identifier defined in your Workflow.
  </Step>

  <Step title="Check Conditions">
    Optional filters like repository name, project key, or label value are evaluated.
  </Step>

  <Step title="Queue for Execution">
    Matching workflows are queued for the specific resource (issue/PR/repo) with priority ordering and event deduplication.
  </Step>

  <Step title="Controlled Execution">
    Workflows execute in priority order with resource locking to prevent conflicts.
  </Step>
</Steps>

<Tip>
  For field-level payload details, see the [Trigger Execution reference](/docs/reference/trigger-execution).
</Tip>

<Note>
  Overcut uses [resource locking and priority queuing](/docs/workflows/workflow-execution-control) to ensure predictable execution order and prevent race conditions when multiple workflows target the same resource.
</Note>

## Using Triggers in a Workflow

When you create a new Workflow, Overcut inserts a Trigger block by default. You can customize its settings directly in the canvas UI.

<Steps>
  <Step title="Create a new Workflow">
    Go to the <code>Workflows</code> tab and click <code>Create Workflow</code>.
  </Step>

  <Step title="Manage trigger cards inside the container">
    Select the Trigger Container to open the Properties panel for the highlighted card. Use the canvas-level <code>Add trigger</code> button to insert new cards, drag the handle on each card to reorder them, and remove any unused cards from the inline menu.
  </Step>

  <Step title="Connect the container to downstream steps">
    Drag from the container’s right-hand handle into the first action, agent, or logic block. Once connected, continue chaining steps as usual; the container automatically routes whichever trigger matches into that first step.
  </Step>
</Steps>

<Note>
  For workflows that need to work with multiple repositories or automatically identify the most relevant repository for a ticket, consider adding a <code>repo.identify</code> step after your trigger. This step uses AI-powered analysis to determine which code repositories are most relevant to the ticket context. Learn more in our <a href="/docs/repositories/repository-mapping">Repository Mapping guide</a>.
</Note>

## Accessing Trigger Data

Once a trigger fires, all event data is available throughout your workflow via template variables. You can access properties like `{{trigger.issue.title}}`, `{{trigger.repository.fullName}}`, `{{trigger.pullRequest.headBranch}}`, and many more.

<CardGroup cols={2}>
  <Card title="Event Context Reference" icon="brackets-curly" href="/docs/reference/event-context">
    Complete reference of all available event properties, organized by event type with practical examples.
  </Card>

  <Card title="Advanced Trigger Execution" icon="gears" href="/docs/reference/trigger-execution">
    Deep dive into multiple triggers, event merging, priority queuing, and sequential execution mechanics.
  </Card>
</CardGroup>