Triggers & Scheduling

Triggers define when your agents run. An agent can have one or multiple triggers, allowing you to run the same logic on different events—like reviewing PRs when they’re opened and auditing documentation on a daily schedule. This guide covers all trigger types, configuration options, and strategies for effective agent scheduling.

Trigger Types Overview

Agents support four trigger types:

pull_request - Respond to pull request events (opened, updated, merged)
scheduled - Run on a recurring schedule using cron expressions
event - React to data stack events (schema changes, test failures, drift detection)
manual - Execute on demand from the web interface or API

You can combine multiple triggers on a single agent. For example, run code reviews on every PR and perform weekly audits via schedule.

Reference

Pull Request Triggers

type

"pull_request"

required

Activates the agent when pull request events occur.

events

array

Specific PR events that trigger the agent. If not specified, the agent runs on all PR events.Available events:

opened - When a new PR is created
synchronize - When new commits are pushed to the PR
reopened - When a closed PR is reopened
closed - When a PR is closed or merged
labeled - When labels are added to the PR
unlabeled - When labels are removed from the PR

triggers:
  - type: pull_request
    events:
      - opened
      - synchronize

Most agents use opened and synchronize to review new code and updates.

paths

object

Filter triggers based on which files changed in the PR.

Show Paths

include

array

List of glob patterns for files that trigger the agent. Only runs if at least one changed file matches.Example: ["models/**/*.sql", "models/**/*.yml"]

exclude

array

List of glob patterns for files to ignore. Takes precedence over include.Example: ["models/staging/temp_*", "**/*.md"]

on_changed_files

string

Simplified path filter using a single glob pattern. Equivalent to setting paths.include with one pattern.

triggers:
  - type: pull_request
    on_changed_files: "models/**/*.sql"

branches

array

Only trigger when the PR targets these branches. Supports glob patterns.

triggers:
  - type: pull_request
    branches:
      - main
      - staging
      - "release/**"

Use this to run different checks for different deployment environments.

conditions

array

Additional filtering conditions that must be satisfied for the trigger to activate.

Show Conditions

type

"pr_labels" | "pr_size" | "author" | "has_conflicts"

The type of condition to evaluate.pr_labels - Filter by PR labels:

conditions:
  - type: pr_labels
    any_of: ["needs-review", "ready"]
    none_of: ["wip", "draft"]

pr_size - Filter by PR size:

conditions:
  - type: pr_size
    max_files_changed: 50
    max_lines_changed: 1000

author - Filter by PR author:

conditions:
  - type: author
    include: ["@data-team"]
    exclude: ["dependabot[bot]"]

has_conflicts - Filter based on merge conflicts:

conditions:
  - type: has_conflicts
    value: false  # Only run if no conflicts

Scheduled Triggers

type

"scheduled"

required

Runs the agent on a recurring schedule defined by a cron expression.

cron

string

required

Cron expression defining when the agent runs. Uses standard 5-field cron syntax.Format: minute hour day month weekdayCommon patterns:

0 * * * * - Every hour at minute 0
*/15 * * * * - Every 15 minutes
0 9 * * * - Daily at 9 AM
0 9 * * 1 - Every Monday at 9 AM
0 0 1 * * - First day of each month at midnight
0 9 * * 1-5 - Weekdays at 9 AM

Use crontab.guru to build and validate cron expressions.

timezone

string

IANA timezone name for schedule interpretation. Defaults to UTC if not specified.Example: "America/New_York", "Europe/London", "Asia/Tokyo"

triggers:
  - type: scheduled
    cron: "0 9 * * *"
    timezone: "America/New_York"

only_on_weekdays

boolean

When true, skips execution on weekends (Saturday and Sunday). Defaults to false.

triggers:
  - type: scheduled
    cron: "0 9 * * *"
    timezone: "America/New_York"
    only_on_weekdays: true

Use this for daily reports or audits that should only run during business days.

context

object

Custom data passed to the agent, accessible in the prompt via template variables.

triggers:
  - type: scheduled
    cron: "0 9 * * *"
    context:
      check_type: daily_audit
      lookback_days: 7
      alert_threshold: 0.15

Reference in prompt: {{ trigger.context.check_type }}

Event Triggers

type

"event"

required

Activates the agent when specific events occur in your data stack.

event_name

string

required

The specific event to listen for.Available events:

schema_change_detected - Source table schema modifications
dbt_test_failed - dbt test failures
dbt_run_failed - dbt model build failures
data_drift_detected - Statistical anomalies in data distributions
data_quality_failure - Custom data quality check failures
freshness_check_failed - Source freshness check failures

Event types depend on your data stack integrations. Configure webhooks in Fivetran, Airbyte, dbt Cloud, or other tools to emit events to Buster.

source

string

required

The system or integration that emits the event.Common sources:

fivetran - Fivetran connector events
airbyte - Airbyte sync events
dbt_cloud - dbt Cloud job events
custom - Custom events from your systems

triggers:
  - type: event
    event_name: schema_change_detected
    source: fivetran

filters

object

Additional event filtering criteria. Available filters depend on the event type.

Show Filters

connector

string

Filter by connector ID or name (for Fivetran/Airbyte events).Example: salesforce, postgres_prod

schema

string

Filter by schema name.Example: raw.salesforce, staging.analytics

table

string

Filter by table name. Supports glob patterns.Example: accounts, fact_*

change_type

array

Filter schema change events by change type.Values: column_added, column_removed, column_renamed, table_added, table_removed

test_severity

string

Filter test failures by severity level.Values: error, warn

model_path

string

Filter by model path pattern.Example: models/marts/**, models/staging/salesforce/**

Manual Triggers

type

"manual"

required

Allows running the agent on demand from the web interface or API.

description

string

Explanation of when and why to manually trigger this agent. Shows in the UI trigger menu.Example: "Run this agent to perform an ad-hoc compliance audit"

parameters

object

Define input parameters that users provide when manually triggering.

Show Parameters

name

string

required

Parameter name, accessible in prompt as {{ trigger.params.name }}

description

string

Explanation of what this parameter controls

type

"string" | "number" | "boolean" | "array"

Expected data type for validation

required

boolean

Whether this parameter must be provided. Defaults to false.

default

any

Default value if not provided

triggers:
  - type: manual
    description: "Analyze specific models on demand"
    parameters:
      - name: model_paths
        description: "Paths to models to analyze"
        type: array
        required: true
      - name: include_tests
        description: "Whether to run tests"
        type: boolean
        default: false

Examples

PR Code Review
Scheduled Daily Audit
Schema Change Event
Multiple Triggers

pr-review-trigger.yaml

name: pr-review
description: Reviews dbt code changes in pull requests

triggers:
  - type: pull_request
    events:
      - opened
      - synchronize
    paths:
      include:
        - "models/**/*.sql"
        - "models/**/*.yml"
        - "macros/**/*.sql"
      exclude:
        - "models/staging/temp_*"
    branches:
      - main
      - develop
    conditions:
      - type: pr_labels
        none_of: ["wip", "draft", "skip-review"]
      - type: pr_size
        max_files_changed: 75
      - type: author
        exclude: ["dependabot[bot]"]

prompt: |
  Review this PR for dbt best practices and potential issues.
  Focus on the SQL and YAML changes only.

Best Practices

Choosing Trigger Types

Use pull_request for validation and review

Pull request triggers are ideal for:

Code review and quality checks
Documentation validation
Breaking change detection
Test coverage verification

These run synchronously with development workflow and can block merges via status checks.

triggers:
  - type: pull_request
    events: [opened, synchronize]
    paths:
      include: ["models/**"]

Use scheduled for periodic maintenance

Scheduled triggers work well for:

Daily/weekly audits and reports
Batch documentation updates
Performance monitoring
Data drift detection

These don’t block workflows and can process accumulated changes efficiently.

triggers:
  - type: scheduled
    cron: "0 9 * * 1"  # Monday mornings
    timezone: "America/New_York"

Use event for reactive automation

Event triggers are perfect for:

Schema change adaptation
Test failure responses
Data quality alerts
Automated remediation

These provide immediate response to data stack events without manual intervention.

triggers:
  - type: event
    event_name: schema_change_detected
    source: fivetran

Use manual for ad-hoc operations

Manual triggers suit:

One-time investigations
Expensive operations run only when needed
Testing new agents
Operations requiring parameter input

These give you control over when and how agents execute.

triggers:
  - type: manual
    description: "Run compliance audit on demand"
    parameters:
      - name: scope
        type: string
        required: true

Path Filtering Strategies

Specific is better than broad. Use path filters to ensure agents only run when relevant files change.

Filter by model layer

Different model layers often need different checks:

# Staging model checks
triggers:
  - type: pull_request
    paths:
      include: ["models/staging/**"]

# Mart model checks (stricter)
triggers:
  - type: pull_request
    paths:
      include: ["models/marts/**"]

Combine include and exclude patterns

Use exclude to skip files you don’t want to trigger on:

triggers:
  - type: pull_request
    paths:
      include:
        - "models/**/*.sql"
        - "models/**/*.yml"
      exclude:
        - "models/**/temp_*"
        - "models/**/_*.sql"
        - "**/*.md"

Group related file types

Trigger on all files relevant to your agent’s purpose:

# Documentation agent should check both SQL and YAML
triggers:
  - type: pull_request
    paths:
      include:
        - "models/**/*.sql"
        - "models/**/*.yml"
        - "models/**/*.md"

Scheduling Strategies

Avoid overlapping schedules for expensive agents. Stagger execution times to prevent resource conflicts.

Batch operations during off-hours

Run resource-intensive agents when usage is low:

triggers:
  - type: scheduled
    cron: "0 2 * * *"  # 2 AM
    timezone: "America/New_York"

Weekday-only for business processes

Skip weekends for reports and non-urgent checks:

triggers:
  - type: scheduled
    cron: "0 9 * * *"
    timezone: "America/New_York"
    only_on_weekdays: true

Use context for time windows

Pass lookback periods via context for batch processing:

triggers:
  - type: scheduled
    cron: "0 8 * * *"
    context:
      lookback_hours: 24
      batch_mode: true

prompt: |
  Process all changes from the last {{ trigger.context.lookback_hours }} hours.
  Use gh CLI to get merged PRs: gh pr list --state merged --search "merged:>$(date -d '24 hours ago')"

Combining Multiple Triggers

Use PR triggers for immediate feedback

Give developers instant feedback during code review:

triggers:
  - type: pull_request
    paths:
      include: ["models/**/*.sql"]

Add scheduled triggers for comprehensive checks

Supplement with periodic deep analysis:

triggers:
  - type: pull_request
    paths:
      include: ["models/**/*.sql"]
  - type: scheduled
    cron: "0 9 * * 1"  # Weekly deep scan

Include manual triggers for flexibility

Allow on-demand execution when needed:

triggers:
  - type: pull_request
    paths:
      include: ["models/**/*.sql"]
  - type: scheduled
    cron: "0 9 * * 1"
  - type: manual
    description: "Run checks on demand"

Trigger Context Usage

Access trigger-specific information in your prompts:

prompt: |
  {% if trigger.type == 'pull_request' %}
    Reviewing PR #{{ trigger.pr_number }} by {{ trigger.pr_author }}
    Changed files: {{ trigger.files_changed }}
  {% elif trigger.type == 'scheduled' %}
    Running scheduled check at {{ trigger.timestamp }}
    Configuration: {{ trigger.context }}
  {% elif trigger.type == 'event' %}
    Responding to {{ trigger.event_name }} from {{ trigger.source }}
    Event data: {{ trigger.event_data }}
  {% endif %}

Common Patterns

Incremental Batch Processing

Process accumulated changes in scheduled batches instead of reacting to each event:

triggers:
  - type: scheduled
    cron: "0 9 * * *"
    context:
      lookback_hours: 24

prompt: |
  Get all PRs merged in the last {{ trigger.context.lookback_hours }} hours:
  
  gh pr list --state merged --limit 100 \
    --search "merged:>$(date -d '{{ trigger.context.lookback_hours }} hours ago' -Iseconds)"
  
  For each PR:
    - Extract changed models
    - Collect documentation updates needed
  
  Create a single PR with all documentation updates batched together.

Conditional Trigger Paths

Use conditions to create sophisticated trigger logic:

triggers:
  - type: pull_request
    conditions:
      # Only for large PRs from the team
      - type: pr_size
        min_files_changed: 10
      - type: author
        include: ["@data-team"]
      # Must have review label
      - type: pr_labels
        any_of: ["needs-review"]
      # Skip if marked as draft
      - type: pr_labels
        none_of: ["draft", "wip"]

Event Filtering for Precision

Narrow event triggers to specific scenarios:

triggers:
  - type: event
    event_name: schema_change_detected
    source: fivetran
    filters:
      # Only production Salesforce
      connector: salesforce_prod
      schema: raw.salesforce
      # Only additive changes
      change_type: [column_added]
      # Ignore specific tables
      table: "!tmp_*"

Introduction

Guides

Examples

Resources

Triggers & Scheduling

Trigger Types Overview

Reference

Pull Request Triggers

Scheduled Triggers

Event Triggers

Manual Triggers

Examples

Best Practices

Choosing Trigger Types

Path Filtering Strategies

Scheduling Strategies

Combining Multiple Triggers

Trigger Context Usage

Common Patterns

Incremental Batch Processing

Conditional Trigger Paths

Event Filtering for Precision

Introduction

Guides

Examples

Resources

​Trigger Types Overview

​Reference

​Pull Request Triggers

​Scheduled Triggers

​Event Triggers

​Manual Triggers

​Examples

​Best Practices

​Choosing Trigger Types

​Path Filtering Strategies

​Scheduling Strategies

​Combining Multiple Triggers

​Trigger Context Usage

​Common Patterns

​Incremental Batch Processing

​Conditional Trigger Paths

​Event Filtering for Precision

Trigger Types Overview

Reference

Pull Request Triggers

Scheduled Triggers

Event Triggers

Manual Triggers

Examples

Best Practices

Choosing Trigger Types

Path Filtering Strategies

Scheduling Strategies

Combining Multiple Triggers

Trigger Context Usage

Common Patterns

Incremental Batch Processing

Conditional Trigger Paths

Event Filtering for Precision