Triggers

The on: section uses standard GitHub Actions syntax to define workflow triggers. For example:

on:
  issues:
    types: [opened]

Trigger Types

GitHub Agentic Workflows supports all standard GitHub Actions triggers plus additional enhancements for reactions, cost control, and advanced filtering.

Dispatch Triggers (workflow_dispatch:)

Run workflows manually from the GitHub UI, API, or via gh aw run/gh aw trial. Full syntax reference.

Basic trigger:

on:
  workflow_dispatch:

With input parameters:

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
      deploy_env:
        description: 'Target environment'
        required: false
        type: environment
        default: staging

Accessing Inputs in Markdown

Use ${{ github.event.inputs.INPUT_NAME }} expressions to access workflow_dispatch inputs in your markdown content:

---
on:
  workflow_dispatch:
    inputs:
      topic:
        description: 'Research topic'
        required: true
        type: string
permissions:
  contents: read
safe-outputs:
  create-discussion:
---

# Research Assistant

Research the following topic: "${{ github.event.inputs.topic }}"

Provide a comprehensive summary with key findings and recommendations.

Supported input types:

• string - Free-form text input
• boolean - True/false checkbox
• choice - Dropdown selection with predefined options
• environment - Dropdown selection of GitHub environments configured in the repository

The environment input type automatically populates a dropdown with environments configured in repository Settings → Environments. It returns the environment name as a string and supports a default value. Unlike the manual-approval: field, using an environment input does not enforce environment protection rules—it only provides the environment name as a string value for use in your workflow logic.

Scheduled Triggers (schedule:)

Run workflows on a recurring schedule using human-friendly expressions or cron syntax.

Fuzzy Scheduling (Recommended):

Use fuzzy schedules to automatically scatter execution times and avoid load spikes:

on:
  schedule: daily  # Compiler assigns a unique scattered time per workflow

Use the around constraint for a preferred time with flexibility:

on:
  schedule: daily around 14:00  # Scatters within ±1 hour (13:00-15:00)

For workflows that should only run during specific hours (like business hours), use the between constraint:

on:
  schedule: daily between 9:00 and 17:00  # Scatters within 9am-5pm range

The compiler assigns each workflow a unique, deterministic execution time based on the file path, ensuring load distribution and consistency across recompiles. UTC offsets are supported on any time expression (e.g., daily between 9am and 5pm utc-5).

For a fixed time, use standard cron syntax:

on:
  schedule:
    - cron: "30 6 * * 1"  # Monday at 06:30 UTC
    - cron: "0 9 15 * *"  # 15th of month at 09:00 UTC

Format	Example	Result	Notes
Hourly (Fuzzy)	hourly	58 */1 * * *	Compiler assigns scattered minute
Daily (Fuzzy)	daily	43 5 * * *	Compiler assigns scattered time
	daily around 14:00	20 14 * * *	Scattered within ±1 hour (13:00-15:00)
	daily between 9:00 and 17:00	37 13 * * *	Scattered within range (9:00-17:00)
	daily between 9am and 5pm utc-5	12 18 * * *	With UTC offset (9am-5pm EST → 2pm-10pm UTC)
	daily around 3pm utc-5	33 19 * * *	With UTC offset (3 PM EST → 8 PM UTC)
Weekly (Fuzzy)	weekly or weekly on monday	43 5 * * 1	Compiler assigns scattered time
	weekly on friday around 5pm	18 16 * * 5	Scattered within ±1 hour
Intervals	every 10 minutes	*/10 * * * *	Minimum 5 minutes
	every 2h	53 */2 * * *	Fuzzy: scattered minute offset
	0 */2 * * *	0 */2 * * *	Cron syntax for fixed times

Time formats: HH:MM (24-hour), midnight, noon, 1pm-12pm, 1am-12am UTC offsets: Add utc+N or utc-N to any time (e.g., daily around 14:00 utc-5)

Human-friendly formats are automatically converted to standard cron expressions, with the original format preserved as a comment in the generated workflow file.

Issue Triggers (issues:)

Trigger on issue events. Full event reference.

on:
  issues:
    types: [opened, edited, labeled]

Issue Locking (lock-for-agent:)

Prevent concurrent modifications to an issue during workflow execution by setting lock-for-agent: true:

on:
  issues:
    types: [opened, edited]
    lock-for-agent: true

When enabled, the issue is locked at workflow start and unlocked after completion (or before safe-output processing). The unlock step uses always() to ensure cleanup even on failure. Useful for workflows that make multiple sequential updates to an issue or need to prevent race conditions.

Requirements:

• Requires issues: write permission (automatically added to activation and conclusion jobs)
• Pull requests are silently skipped (they cannot be locked via the issues API)
• Already-locked issues are skipped without error

Example workflow:

---
on:
  issues:
    types: [opened]
    lock-for-agent: true
permissions:
  contents: read
  issues: write
safe-outputs:
  add-comment:
    max: 3
---

# Issue Processor with Locking

Process the issue and make multiple updates without interference
from concurrent modifications.

Context: "${{ needs.activation.outputs.text }}"

Pull Request Triggers (pull_request:)

Trigger on pull request events. Full event reference.

Code availability: When triggered by a pull request event, the coding agent has access to both the PR branch and the default branch.

on:
  pull_request:
    types: [opened, synchronize, labeled]
    names: [ready-for-review, needs-review]
  reaction: "rocket"

Fork Filtering (forks:)

Pull request workflows block forks by default for security. Use the forks: field to allow specific fork patterns:

on:
  pull_request:
    types: [opened, synchronize]
    forks: ["trusted-org/*"]  # Allow forks from trusted-org

Available patterns:

• ["*"] - Allow all forks (use with caution)
• ["owner/*"] - Allow forks from specific organization or user
• ["owner/repo"] - Allow specific repository
• Omit forks field - Default behavior (same-repository PRs only)

The compiler uses repository ID comparison for reliable fork detection that is not affected by repository renames.

Comment Triggers

Note: issue_comment events also fire for comments on pull requests (GitHub models PR comments as issue comments). When a comment is on a pull request, the coding agent has access to both the PR branch and the default branch.

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  discussion_comment:
    types: [created]
  reaction: "eyes"

Comment Locking (lock-for-agent:)

For issue_comment events, you can lock the parent issue during workflow execution:

on:
  issue_comment:
    types: [created, edited]
    lock-for-agent: true

This prevents concurrent modifications to the issue while processing the comment. The locking behavior is identical to the issues: trigger (see Issue Locking above for full details).

Note: Pull request comments are silently skipped as pull requests cannot be locked via the issues API.

Workflow Run Triggers (workflow_run:)

Trigger workflows after another workflow completes. Full event reference.

on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]
    branches:
      - main
      - develop

Workflows with workflow_run triggers include automatic security protections:

• Repository/fork validation: The compiler injects repository ID and fork checks, rejecting cross-repository or fork-triggered runs.
• Branch restrictions required: Include branches to limit triggering branches; without them the compiler warns (or errors in strict mode).

See the Security Architecture for details.

Command Triggers (slash_command:)

The slash_command: trigger creates workflows that respond to /command-name mentions in issues, pull requests, and comments. See Command Triggers for complete documentation including event filtering, context text, reactions, and examples.

Label Filtering (names:)

Filter issue and pull request triggers by label names using the names: field:

on:
  issues:
    types: [labeled, unlabeled]
    names: [bug, critical, security]

Use convenient shorthand for label-based triggers:

on: issue labeled bug
on: issue labeled bug, enhancement, priority-high  # Multiple labels
on: pull_request labeled needs-review, ready-to-merge

All shorthand formats compile to standard GitHub Actions syntax and automatically include the workflow_dispatch trigger. Supported for issue, pull_request, and discussion events. See LabelOps workflows for automation examples.

Reactions (reaction:)

Enable emoji reactions on triggering items (issues, PRs, comments, discussions) to provide visual workflow status feedback:

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

The reaction is added to the triggering item. For issues/PRs, a comment with the workflow run link is created. For comment events in command workflows, the comment is edited to include the run link.

Available reactions: +1 , -1 , laugh , confused , heart , hooray , rocket , eyes

Stop After Configuration (stop-after:)

Automatically disable workflow triggering after a deadline to control costs.

on: weekly on monday
  stop-after: "+25h"  # 25 hours from compilation time

Accepts absolute dates (YYYY-MM-DD, MM/DD/YYYY, DD/MM/YYYY, January 2 2006, 1st June 2025, ISO 8601) or relative deltas (+7d, +25h, +1d12h30m) calculated from compilation time. The minimum granularity is hours - minute-only units (e.g., +30m) are not allowed. Recompiling the workflow resets the stop time.

Manual Approval Gates (manual-approval:)

Require manual approval before workflow execution using GitHub environment protection rules:

on:
  workflow_dispatch:
  manual-approval: production

Sets the environment on the activation job for human-in-the-loop approval before execution. The value must match a configured environment in repository Settings → Environments (approval rules, required reviewers, wait timers). See GitHub’s environment documentation for configuration details.

Skip-If-Match Condition (skip-if-match:)

Conditionally skip workflow execution when a GitHub search query has matches. Useful for preventing duplicate scheduled runs or waiting for prerequisites.

on: daily
  skip-if-match: 'is:issue is:open in:title "[daily-report]"'  # Skip if any match

on: weekly on monday
  skip-if-match:
    query: "is:pr is:open label:urgent"
    max: 3  # Skip if 3 or more PRs match

A pre-activation check runs the search query against the current repository. If matches reach or exceed the threshold (default max: 1), the workflow is skipped. The query is automatically scoped to the current repository and supports all standard GitHub search qualifiers (is:, label:, in:title, author:, etc.).

Skip-If-No-Match Condition (skip-if-no-match:)

Conditionally skip workflow execution when a GitHub search query has no matches (or fewer than the minimum required). This is the opposite of skip-if-match.

on: weekly on monday
  skip-if-no-match: 'is:pr is:open label:ready-to-deploy'  # Skip if no matches

on:
  workflow_dispatch:
  skip-if-no-match:
    query: "is:issue is:open label:urgent"
    min: 3  # Only run if 3 or more issues match

A pre-activation check runs the search query against the current repository. If matches are below the threshold (default min: 1), the workflow is skipped. Can be combined with skip-if-match for complex conditions.

Related Documentation

• Schedule Syntax - Complete schedule format reference
• Command Triggers - Special @mention triggers and context text
• Frontmatter - Complete frontmatter configuration
• LabelOps - Label-based automation workflows
• Workflow Structure - Directory layout and organization