Skip to main content

​
Agentic Workflows Overview

Agentic Workflows are AI-powered repository automations that run coding agents in GitHub Actions. Defined in markdown with natural language instructions, they enable event-triggered and scheduled automation with built-in guardrails and security-first design.

​
What Are Agentic Workflows?

Agentic Workflows combine the power of AI coding agents with GitHub Actions to automate repository tasks. Unlike traditional GitHub Actions workflows written in YAML, Agentic Workflows use natural language instructions and compile to secure, locked GitHub Actions files.

Natural Language

Write workflows in markdown with plain English instructions

AI-Powered

GitHub Copilot agents execute tasks autonomously

Security-First

Built-in guardrails and least-privilege permissions

Event-Driven

Trigger on schedules, GitHub events, or slash commands

​
How They Work

1

Write Instructions

Create a .md file with YAML frontmatter and natural language instructions describing what the workflow should do.
2

Compile to Actions

Use gh aw compile to generate a secure .lock.yml GitHub Actions file.
3

Commit & Deploy

Commit both the .md source and .lock.yml file to .github/workflows/.
4

Automated Execution

The workflow runs automatically based on configured triggers.

​
Workflow Structure

An Agentic Workflow consists of markdown frontmatter and natural language instructions:
daily-report.md
---
name: "Daily Issues Report"
description: "Generates a daily summary of open issues and recent activity"
on:
  schedule: daily on weekdays
permissions:
  contents: read
  issues: read
safe-outputs:
  create-issue:
    title-prefix: "[daily-report] "
    labels: [report]
---

## Daily Issues Report

Create a daily summary of open issues for the team.

## What to Include

- New issues opened in the last 24 hours
- Issues closed or resolved
- Stale issues that need attention

​
Frontmatter Fields

Human-readable name for the workflow.
name: "Daily Issues Report"
Brief description of what the workflow does.
description: "Generates a daily summary of open issues"
Triggers that start the workflow. Supports schedules, GitHub events, slash commands, and manual dispatch.
# Schedule trigger
on:
  schedule: daily on weekdays

# Event trigger
on:
  issues:
    types: [opened, labeled]

# Slash command trigger
on:
  slash_command:
    name: relevance-check
  roles: [admin, maintainer, write]

# Manual trigger with inputs
on:
  workflow_dispatch:
    inputs:
      organization:
        description: "GitHub organization to analyze"
        required: false
        type: string
GitHub token permissions required by the workflow. Use least-privilege principle.
permissions:
  contents: read
  issues: read
  pull-requests: read
AI engine to use. Defaults to copilot.
engine: copilot
Tools available to the AI agent.
tools:
  github:
    toolsets: [default]
  bash: true
Maximum workflow execution time.
timeout-minutes: 60
Tags for categorizing the workflow.
labels: ['ospo', 'reporting', 'contributors']

​
Trigger Types

Agentic Workflows support multiple trigger types:

​
Schedule Triggers

Run workflows on a schedule using natural language: 
on:
  schedule: daily on weekdays
Or use cron syntax: 
on:
  schedule:
    - cron: "0 9 * * 1-5"  # 9 AM weekdays

​
GitHub Event Triggers

Run workflows when specific GitHub events occur: 
on:
  issues:
    types: [opened, labeled]
  pull_request:
    types: [opened, synchronize]

​
Slash Command Triggers

Run workflows via slash commands in issues or PRs: 
on:
  slash_command:
    name: relevance-check
  roles: [admin, maintainer, write]
Users can trigger with: /relevance-check

​
Manual Dispatch

Run workflows manually with optional inputs: 
on:
  workflow_dispatch:
    inputs:
      organization:
        description: "GitHub organization to analyze"
        required: false
        type: string
      start_date:
        description: "Start date (YYYY-MM-DD)"
        required: false
        type: string

​
Safe Outputs

Safe outputs are guardrails that constrain AI agent actions to prevent unintended consequences: 
safe-outputs:
  create-issue:
    max: 1                    # Maximum 1 issue
    title-prefix: "[report] " # Required title prefix
    labels: [automated]       # Required labels

​
Installation & Usage

1

Install gh aw CLI

Install the GitHub CLI extension for Agentic Workflows:
gh extension install github/gh-aw
2

Copy Workflow File

Copy the workflow .md file to your repository’s .github/workflows/ directory:
cp workflows/daily-issues-report.md .github/workflows/
3

Compile Workflow

Generate the .lock.yml GitHub Actions file:
gh aw compile
Or compile with validation:
gh aw compile --validate
4

Commit Both Files

Commit both the source .md and compiled .lock.yml files:
git add .github/workflows/daily-issues-report.md
git add .github/workflows/daily-issues-report.lock.yml
git commit -m "Add daily issues report workflow"
git push

​
Managing Workflows

​
Trigger Manual Run

gh aw run daily-issues-report

​
Check Workflow Status

gh aw status

​
View Workflow Logs

gh aw logs daily-issues-report

​
List All Workflows

gh aw list

​
Best Practices

Least Privilege

Only request the minimum permissions needed

Use Safe Outputs

Always constrain AI agent actions with safe-outputs

Clear Instructions

Write specific, step-by-step instructions for the agent

Test Thoroughly

Use workflow_dispatch to test before deploying

​
Security Guidelines

Never commit .yml or .yaml files directly — always use .md source files and compile to .lock.yml.
  • Read-only by default: Start with read permissions only
  • Validate inputs: Sanitize user inputs from slash commands
  • Limit outputs: Use max constraints in safe-outputs
  • Review compiled output: Check .lock.yml before committing
  • Use title-prefix: Clearly mark automated issues/PRs

​
When to Use Agentic Workflows

Agentic Workflows are ideal for:
  • Issue triage and labeling based on content
  • Daily/weekly status reports from repository data
  • Automated documentation maintenance and updates
  • Scheduled code quality checks and reports
  • Slash command tools for maintainers
  • Multi-step repository automation with AI decision-making
For session-based automation during Copilot coding sessions, see Hooks.

​
Next Steps

Browse Workflow Catalog

Explore available workflows and examples

GitHub Agentic Workflows Spec

Read the official specification and documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us