Triggers and Events — Making Agents React

Until now, every workflow we've discussed is manually invoked — you type a command and the agent runs. That's powerful, but it's only half the picture. The real shift happens when agents react to events without you asking.

This lesson covers the on: frontmatter section — the declarative syntax that tells a workflow when to activate. If you've used GitHub Actions, this will feel familiar. The difference: instead of triggering a CI pipeline, you're triggering an AI agent.

The on: Section

Every agentic workflow file has YAML frontmatter at the top. The on: key declares the trigger — what event or condition causes the workflow to fire:

---
on:
  issues:
    types: [opened]

safe-outputs:
  add-comment:
---

# Auto-Triage New Issues

Read the issue title and body. Assign appropriate labels based on content.
Add a comment acknowledging receipt and estimated triage time.

This workflow fires every time a new issue is opened. No human invocation needed. The agent reads, labels, and responds — all from a single trigger declaration.

Four Types of Triggers

Triggers fall into four categories. Most workflows use one; complex workflows combine several.

Event Triggers in Detail

Event triggers use standard GitHub webhook event names with optional types: filtering:

# React to new and edited issues
on:
  issues:
    types: [opened, edited, labeled]

# React to PR creation and new commits
on:
  pull_request:
    types: [opened, synchronize]

# React to comments (ChatOps pattern)
on:
  issue_comment:
    types: [created]

# React to new discussions
on:
  discussion:
    types: [created]

The types: array lets you be precise. Without it, the workflow fires on every event type — which is usually too broad. Always specify types.

Schedule Triggers

Schedule triggers support two syntaxes: human-friendly fuzzy expressions and standard cron.

Fuzzy Syntax (Recommended)

Fuzzy schedules are easier to read and automatically scatter execution times to avoid load spikes:

# Simple intervals
on:
  schedule: daily
  schedule: weekly on monday
  schedule: hourly
  schedule: every 30 minutes

# With time preferences
on:
  schedule: daily around 14:00              # ±1 hour around 2pm UTC
  schedule: daily between 9:00 and 17:00    # Scattered within business hours
  schedule: weekly on friday around 5pm

# With timezone offsets
on:
  schedule: daily between 9am and 5pm utc-5  # Eastern time business hours

The compiler converts these to deterministic cron expressions based on the workflow's file path — so the same workflow always runs at the same time, but different workflows scatter naturally.

Standard Cron

For exact timing, use cron directly:

on:
  schedule:
    - cron: "0 9 * * 1-5"      # 9:00 UTC weekdays
    - cron: "30 6 * * 1"       # Monday at 06:30 UTC
    - cron: "0 9 15 * *"       # 15th of month at 09:00 UTC
      timezone: "America/New_York"  # IANA timezone override

Manual Triggers (workflow_dispatch)

Manual triggers let you define input parameters the user provides when invoking the workflow:

on:
  workflow_dispatch:
    inputs:
      topic:
        description: 'Research topic'
        required: true
        type: string
      priority:
        description: 'Task priority'
        required: false
        type: choice
        options:
          - low
          - medium
          - high
        default: medium

Access inputs in your prompt with template syntax: ${{ github.event.inputs.topic }}

This is the bridge between "fully manual" and "fully automatic." You decide when to run it, but the workflow handles the how.

Command Triggers (slash_command)

Command triggers turn issue comments into agent invocations:

on:
  slash_command:
    name: investigate
    events: [issues, issue_comment]

Now, when anyone types /investigate in an issue comment, the workflow fires with the full issue context. This is the ChatOps pattern — your team interacts with the agent through normal GitHub conversations.

Use cases:

• /investigate — Deep-dive into a reported bug
• /deploy staging — Trigger a deployment
• /summarize — Generate a summary of a long thread
• /comply — Run compliance checks on demand

Combining Triggers

A single workflow can respond to multiple triggers. This is common — you want something to run both automatically and on-demand:

on:
  # Fire automatically on new issues
  issues:
    types: [opened]
  # Also allow manual invocation for testing
  workflow_dispatch:
  # And fire on a schedule for catch-up
  schedule: daily around 9:00

The workflow runs identically regardless of which trigger fired. This makes testing easy — use workflow_dispatch during development, then let the event triggers handle production.

Common Trigger Patterns

Practical Example: Auto-Triage New Issues

Let's build a complete auto-triage workflow. This is one of the most impactful first automations — it gives every issue reporter instant acknowledgment and applies initial labels:

---
on:
  issues:
    types: [opened]
  reaction: "eyes"

safe-outputs:
  add-comment:
  add-labels:

permissions:
  issues: write
---

# Auto-Triage New Issues

You are a triage agent for this repository.

## Context

Read the issue: "${{ github.event.issue.title }}"

Body:
${{ github.event.issue.body }}

## Task

1. Analyze the issue content and determine:
   - Is this a bug report, feature request, question, or documentation issue?
   - What area of the codebase does it relate to?
   - What priority level seems appropriate (critical, high, medium, low)?

2. Apply labels:
   - One type label: `bug`, `enhancement`, `question`, or `documentation`
   - One area label if identifiable: `area/api`, `area/ui`, `area/infra`, etc.
   - One priority label: `priority/critical`, `priority/high`, `priority/medium`, `priority/low`

3. Add a comment:
   - Acknowledge the issue
   - Summarize your understanding
   - Note any missing information needed for triage
   - Be friendly and concise

This workflow activates the moment an issue is created. The reaction: "eyes" immediately adds an 👀 emoji so the reporter knows something is happening. Within seconds, the issue has labels and a helpful comment.

Connection to Your Work

Think about your existing /comply workflow. Right now, it's Layer 2 — a manually invoked command. You type it, it runs. But what if it fired automatically?

---
on:
  workflow_dispatch:
---

# Compliance Check
Run compliance checks...

---
on:
  pull_request:
    types: [opened, synchronize]
  workflow_dispatch:
---

# Compliance Check
Run compliance checks...

One line changes the trigger from "when I ask" to "when any PR is opened or updated." The workflow body stays identical. The agent's behavior doesn't change — only when it activates. This is the power of declarative triggers: you graduate workflows from manual to automatic by editing frontmatter, not rewriting logic.

Trigger Shorthands

For common patterns, the gh-aw compiler accepts natural-language shorthand instead of full YAML:

# These are equivalent:
on: issue opened
on:
  issues:
    types: [opened]

# More shorthand examples:
on: pull_request opened
on: issue labeled bug
on: manual
on: manual with input version
on: comment created
on: "deployment failed"

Shorthands are useful for simple, single-trigger workflows. Use full YAML when combining triggers or adding filtering options.

Check Your Understanding

What's Next

You now understand the four trigger types and how to declare them. The next lesson covers safe outputs — controlling what an event-triggered agent is allowed to do. Because once an agent activates autonomously, the guardrails matter more than ever.