Text of github.github.com › gh-aw › reference › triggers as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Triggers | GitHub Agentic Workflows

Skip to main content Triggers The on: section uses standard GitHub Actions syntax to define workflow triggers. For example: on : issues : types : [ opened ] Trigger Types Section titled “Trigger Types” GitHub Agentic Workflows supports all standard GitHub Actions triggers plus additional enhancements for reactions, cost control, and advanced filtering. Admission steps inside activation and conclusion are omitted by default.

Set "admission": true in .github/workflows/aw.json to enable them repository-wide, or on.admission: true for a single workflow when no repository override is set. This setting controls code generation, not job permissions, and is not a GitHub Actions event. Recompile after changing it. See Centralized Activation Admission for the runtime variables and job-wide OIDC implications. Experimental hosted CAO triggers: on.gateway-dispatch and all its nested triggers are experimental.

GitHub issue, pull-request, discussion, comment, and review/thread notifications are filtered by the server. projects-items requires project_id ; paired status-transitions adds delivered Status predicates. Separate code-scanning-alert and dependabot-alerts triggers select their own events with independent types , severity , and filters ; there is no bundled security event. Shared repos and wildcard orgs restrict independently approved GitHub sources without granting access; non-GitHub families ignore them.

Named secret scanning is unsupported. Compilation requires {"gateway-dispatch":true} in .github/workflows/aw.json and generates a mandatory gateway_provenance job for approved CAO App identity, not generic repository-write authority. Configure central Actions secrets GH_AW_GATEWAY_APP_ID and GH_AW_GATEWAY_APP_BOT_ID (existing variables remain a fallback); every other job requires successful provenance. Integrations must remain nonactivating until the receiver token flow and approved destination revision enforce the App-token contract .

No other trigger may coexist with gateway-dispatch . Supported non-trigger settings such as roles and bots remain outside its mapping, and the compiler emits only its workflow-specific restricted repository_dispatch route. See Webhook Triggers for syntax, payload filters, and integration requirements. External issue integrations: Azure DevOps, Jira, and Linear use shared connector declarations . Their former native gateway aliases are removed.

Select imported triggers under on.gateway-dispatch.<id> to use the protected gateway route. Receiver deployment and authenticated source enrollment remain external prerequisites; use workflow_dispatch until that integration is approved. See Provider Issue Triggers for migration guidance. All gateway families forward only canonical resource URLs, event type arrays, and declared matching filter literals, never native resource bodies or unselected values.

Workflows resolve any additional data with provider-authenticated clients so the provider enforces access. See the Webhook Gateway Specification for the closed payload contract. Dispatch Triggers ( workflow_dispatch: ) Section titled “Dispatch Triggers (workflow_dispatch:)” Run workflows manually from the GitHub UI, API, or via gh aw run / gh aw trial . Full syntax reference . gh aw run <workflow> --ref <branch> runs that branch’s compiled workflow content, but GitHub requires the workflow file to be registered on the default branch first.

See Run from a feature branch for inert registration and the limits of testing pull_request_target through manual dispatch. 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 Section titled “Accessing Inputs in Markdown” Access inputs in your markdown content with ${{ github.event.inputs.INPUT_NAME }} : Research the following topic: "${{ github.event.inputs.topic }}" Supported input types: string (free-form text), boolean (checkbox), choice (dropdown with predefined options), and environment (dropdown populated from repository Settings → Environments).

The environment input returns the environment name as a string and supports a default value. Unlike manual-approval: , it does not enforce environment protection rules — it only provides the environment name for use in your workflow logic. Scheduled Triggers ( schedule: ) Section titled “Scheduled Triggers (schedule:)” Run workflows on a recurring schedule using human-friendly expressions or cron syntax . Fuzzy Scheduling: Fuzzy schedules scatter execution times to avoid load spikes.

Use around <time> for a preferred time with ±1 hour flexibility, or between <a> and <b> to scatter within a window (such as business hours): on : schedule : daily # Compiler picks a scattered time # schedule: daily around 14:00 # ±1 hour around 2pm # schedule: daily between 9:00 and 17:00 # Scatters within 9am-5pm 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. Add an optional timezone field to interpret the cron in a specific IANA timezone instead of UTC: on : schedule : - cron : " 30 6 * * 1 " # Monday at 06:30 UTC - cron : " 0 9 15 * * " # 15th of month at 09:00 UTC - cron : " 30 9 * * 1-5 " timezone : " America/New_York " # 9:30 AM EST/EDT Mon-Fri 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.

Cooldown ( cooldown: ) Section titled “Cooldown (cooldown:)” Set on.cooldown to skip agent execution until a duration has elapsed since the latest completed run that started the agent job. This is useful when a workflow runs more frequently than you want the agent to act, such as checking hourly but allowing an agent run every four hours: on: schedule: hourly cooldown: 4h The duration uses Go duration syntax, such as 5m , 1h , or 1h30m , and must be at least five minutes.

GitHub Actions expressions are not supported. The cooldown starts when the previous workflow run finishes, provided the agent job started, regardless of whether that job succeeded or failed. Runs where the agent job was skipped do not restart the cooldown. The compiler adds actions: read to the pre-activation job so it can inspect completed runs. If run history cannot be queried, the cooldown check fails open and allows the agent to run.

Issue Triggers ( issues: ) Section titled “Issue Triggers (issues:)” Trigger on issue events. Full event reference . on : issues : types : [ opened , edited , labeled ] types also accepts status_changed for

The rest of this page is on the live site.