FAI Agentic Workflows
GitHub Agentic Workflows in Public Preview — Markdown automation compiled into guarded GitHub Actions.
What Are Agentic Workflows?
GitHub Agentic Workflows (gh-aw) are Markdown files with YAML frontmatter that run supported coding agents inside GitHub Actions. They augment deterministic CI with natural-language automation and are currently in Public Preview. Write operations are requested through bounded safe-outputs and applied by separate permission-controlled jobs.
Each source file lives in .github/workflows/*.md. Running gh aw compile generates a sibling *.lock.yml file, which is the workflow GitHub Actions executes. Commit both files and edit only the Markdown source.
The patterns below are 12 teaching examples, not a generated inventory of FrootAI's .github/workflows directory. The repository also contains conventional YAML workflows; do not treat every GitHub Actions file as an agentic workflow.
Workflow Frontmatter Schema
Every agentic workflow begins with YAML frontmatter that declares metadata, triggers, and output constraints:
| Field | Required | Type | Purpose |
|---|---|---|---|
| on | Yes | object | Actions events plus agentic approval and role controls |
| permissions | Recommended | object | Read permissions available to the agentic job |
| safe-outputs | For writes | object | Validated operations applied outside the read-only agent job |
| engine | No | string/object | Coding-agent engine; defaults to Copilot when omitted |
| tools | No | object | Allowlisted GitHub, shell, browser, and MCP capabilities |
| network | No | object | Outbound ecosystem and domain allowlists |
| max-ai-credits | No | number | Per-run AI Credits budget guardrail |
Complete Workflow Example
Below is a full agentic workflow file. The agent reads the steps, executes them in order, and produces outputs that respect the declared limits:
---description: Validate all primitives against schema and naming conventionson: schedule: - cron: "0 6 * * 1" workflow_dispatch:permissions: contents: readsafe-outputs: create-issue: max: 1 title-prefix: "[primitive-quality] " labels: [quality-report] close-older-issues: truemax-ai-credits: 500---
## Steps
1. Run `node scripts/validate-primitives.js --verbose` and capture output2. Parse results — count errors, warnings, and passing primitives3. If errors > 0: create a single GitHub issue titled "Primitive Validation: {errorCount} errors found on {date}"4. Add a comment with the full error details (truncate to 64KB)5. If a previous validation issue exists and is now resolved, close it with a comment: "All primitives passing ✅"6. If no action is needed, call the noop tool with a concise reason
Do not modify repository files or expose secret values.Safe-Outputs Constraint Reference
Safe-outputs are the guardrail mechanism that prevents agent runaway. Every write action the agent can take must be declared and bounded. If the agent attempts an action not listed or exceeds the limit, the action is blocked.
| Constraint | Values | Default | Behavior |
|---|---|---|---|
| create-issue | { max: N } | max: 0 | Limits new issues created per run |
| add-comment | { max: N } | max: 0 | Limits comments on issues or PRs |
| close-older-issues | true / false | false | Auto-close stale issues from prior runs |
| create-pr | { max: N } | max: 0 | Limits pull requests created per run |
| add-labels | { max: N, allowed: [] } | max: 3 | Restricts label additions by count and allowlist |
| create-pull-request | { max: N, protected-files: policy } | max: 1 | Creates reviewable changes through a bounded downstream job |
4 Trigger Types
Each workflow declares one or more triggers that determine when it runs:
Schedule (cron)
Runs on a cron schedule. Best for periodic checks like weekly quality audits or nightly staleness scans. Uses standard 5-field POSIX cron syntax. All times are UTC.
Manual (workflow_dispatch)
Triggered manually from the GitHub Actions UI or via API. Include optional inputs for parameters like target branch, scope, or verbosity level.
PR Event
Fires on pull request events — opened, synchronize, labeled. Used for PR quality checks, compliance validation, and automated reviews.
Slash Command
Triggered by a comment like /play-relevance on an issue or PR. The agent reads the issue context and responds inline. Great for on-demand analysis.
12 Reference Patterns by Category
Quality (4 workflows)
Validates all agents, instructions, skills, hooks against schemas. Creates a single issue if errors found, closes it when resolved.
Runs on every PR that modifies primitives. Checks naming conventions, frontmatter, and WAF alignment. Adds review comments inline.
Compares current primitives against schema definitions weekly. Detects field additions or removals that break validation.
Cross-checks README counts, marketplace.json, website-data, and package.json for consistency. Reports mismatches.
Compliance (2 workflows)
Scans all solution plays for WAF pillar coverage. Flags plays missing security, reliability, or responsible AI alignment.
Validates that all new dependencies have compatible licenses. Blocks PRs that introduce GPL or unlicensed packages.
Staleness (3 workflows)
Finds solution plays not updated in 90+ days. Creates issues prompting maintainers to review or deprecate.
Checks npm, Python, and Bicep dependencies for outdated versions. Suggests pinned version bumps via issue comment.
Tracks Azure OpenAI model version deprecation dates. Alerts when a play references a model nearing end-of-life.
Reporting (3 workflows)
Generates weekly counts: agents, instructions, skills, hooks, plugins, plays. Posts summary to a pinned issue.
Triggered by /play-relevance on an issue. Analyzes the issue description and suggests matching solution plays.
Reads merged PRs since last release tag. Generates a categorized changelog grouped by primitives, plays, and infra.
Workflow Lifecycle
Every agentic workflow follows a 5-phase lifecycle from trigger to completion:
Scheduling & Cron Patterns
Schedule-triggered workflows use standard POSIX cron. All times are UTC. Common patterns:
# Weekly Monday 6am UTC — quality auditscron: "0 6 * * 1"
# Daily midnight — staleness scanscron: "0 0 * * *"
# Every 6 hours — ecosystem scorecardcron: "0 */6 * * *"
# First of month — compliance reportscron: "0 9 1 * *"Combine schedule with workflow_dispatch: true so workflows can also be triggered manually for debugging or on-demand runs.
Permissions Model
Workflows follow the principle of least privilege. Each workflow declares only the GitHub token scopes it needs:
permissions: contents: read # Read repo files issues: write # Create/close issues pull-requests: read # Read PR metadata # Never granted: admin, packages, actionsIf a workflow does not declare permissions, it defaults to contents: read only. Workflows that need write access must explicitly declare it — this is enforced by the FAI PR quality gate.
GitHub Integration
Agentic workflows integrate deeply with the GitHub ecosystem:
Status Badges
Each workflow generates a status badge that can be embedded in README files. Shows last run status: passing, failing, or skipped.
Issue Templates
Workflows that create issues use standardized templates with labels, assignees, and milestone references pre-configured.
Branch Protection
PR-triggered workflows can be set as required status checks. No merge until the quality gate passes.
Environments
Workflows can reference GitHub Environments for secrets and deployment protection rules. Production workflows require manual approval.