Skip to content

Commit ceb9789

Browse files
aaronpowellaaronpowell
authored
Merge pull request #786 from brunoborges/agentic-workflows-staged
Support for Contributions of Agentic Workflows
2 parents 068a95f + dbaa8f6 commit ceb9789

11 files changed

Lines changed: 486 additions & 10 deletions

‎.github/pull_request_template.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
## Pull Request Checklist
22

33
- [ ] I have read and followed the [CONTRIBUTING.md](https://github.com/github/awesome-copilot/blob/main/CONTRIBUTING.md) guidelines.
4-
- [ ] My contribution adds a new instruction, prompt, agent, or skill file in the correct directory.
4+
- [ ] My contribution adds a new instruction, prompt, agent, skill, or workflow file in the correct directory.
55
- [ ] The file follows the required naming convention.
66
- [ ] The content is clearly structured and follows the example format.
7-
- [ ] I have tested my instructions, prompt, agent, or skill with GitHub Copilot.
7+
- [ ] I have tested my instructions, prompt, agent, skill, or workflow with GitHub Copilot.
88
- [ ] I have run `npm start` and verified that `README.md` is up to date.
99

1010
---
@@ -22,7 +22,8 @@
2222
- [ ] New agent file.
2323
- [ ] New plugin.
2424
- [ ] New skill file.
25-
- [ ] Update to existing instruction, prompt, agent, plugin, or skill.
25+
- [ ] New agentic workflow.
26+
- [ ] Update to existing instruction, prompt, agent, plugin, skill, or workflow.
2627
- [ ] Other (please specify):
2728

2829
---

‎.github/workflows/validate-agentic-workflows-pr.yml‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
name: Validate Agentic Workflow Contributions
2+
3+
on:
4+
pull_request:
5+
branches: [staged]
6+
types: [opened, synchronize, reopened]
7+
paths:
8+
- "workflows/**"
9+
10+
permissions:
11+
contents: read
12+
pull-requests: write
13+
14+
jobs:
15+
check-forbidden-files:
16+
name: Block forbidden files
17+
runs-on: ubuntu-latest
18+
steps:
19+
- name: Checkout code
20+
uses: actions/checkout@v4
21+
with:
22+
fetch-depth: 0
23+
24+
- name: Check for forbidden files
25+
id: check
26+
run: |
27+
# Check for YAML/lock files in workflows/ and any .github/ modifications
28+
forbidden=$(git diff --name-only --diff-filter=ACM origin/${{ github.base_ref }}...HEAD -- \
29+
'workflows/**/*.yml' \
30+
'workflows/**/*.yaml' \
31+
'workflows/**/*.lock.yml' \
32+
'.github/*' \
33+
'.github/**')
34+
35+
if [ -n "$forbidden" ]; then
36+
echo "❌ Forbidden files detected:"
37+
echo "$forbidden"
38+
echo "files<<EOF" >> "$GITHUB_OUTPUT"
39+
echo "$forbidden" >> "$GITHUB_OUTPUT"
40+
echo "EOF" >> "$GITHUB_OUTPUT"
41+
exit 1
42+
else
43+
echo "✅ No forbidden files found"
44+
fi
45+
46+
- name: Comment on PR
47+
if: failure()
48+
uses: marocchino/sticky-pull-request-comment@v2
49+
with:
50+
header: workflow-forbidden-files
51+
message: |
52+
## 🚫 Forbidden files in `workflows/`
53+
54+
Only `.md` markdown files are accepted in the `workflows/` directory. The following are **not allowed**:
55+
- Compiled workflow files (`.yml`, `.yaml`, `.lock.yml`) — could contain untrusted Actions code
56+
- `.github/` modifications — workflow contributions must not modify repository configuration
57+
58+
**Files that must be removed:**
59+
```
60+
${{ steps.check.outputs.files }}
61+
```
62+
63+
Contributors provide the workflow **source** (`.md`) only. Compilation happens downstream via `gh aw compile`.
64+
65+
Please remove these files and push again.
66+
67+
compile-workflows:
68+
name: Compile and validate
69+
needs: check-forbidden-files
70+
runs-on: ubuntu-latest
71+
steps:
72+
- name: Checkout code
73+
uses: actions/checkout@v4
74+
75+
- name: Install gh-aw CLI
76+
uses: github/gh-aw/actions/setup-cli@main
77+
78+
- name: Compile workflow files
79+
id: compile
80+
run: |
81+
exit_code=0
82+
found=0
83+
84+
# Find all .md files directly in workflows/
85+
for workflow_file in workflows/*.md; do
86+
[ -f "$workflow_file" ] || continue
87+
88+
found=$((found + 1))
89+
echo "::group::Compiling $workflow_file"
90+
if gh aw compile --validate "$workflow_file"; then
91+
echo "✅ $workflow_file compiled successfully"
92+
else
93+
echo "❌ $workflow_file failed to compile"
94+
exit_code=1
95+
fi
96+
echo "::endgroup::"
97+
done
98+
99+
if [ "$found" -eq 0 ]; then
100+
echo "No workflow .md files found to validate."
101+
else
102+
echo "Validated $found workflow file(s)."
103+
fi
104+
105+
echo "status=$( [ $exit_code -eq 0 ] && echo success || echo failure )" >> "$GITHUB_OUTPUT"
106+
exit $exit_code
107+
108+
- name: Comment on PR if compilation failed
109+
if: failure()
110+
uses: marocchino/sticky-pull-request-comment@v2
111+
with:
112+
header: workflow-validation
113+
message: |
114+
## ❌ Agentic Workflow compilation failed
115+
116+
One or more workflow files in `workflows/` failed to compile with `gh aw compile --validate`.
117+
118+
Please fix the errors and push again. You can test locally with:
119+
120+
```bash
121+
gh extension install github/gh-aw
122+
gh aw compile --validate <your-workflow-file>.md
123+
```
124+
125+
See the [Agentic Workflows documentation](https://github.github.com/gh-aw) for help.

‎.github/workflows/validate-readme.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ on:
99
- "prompts/**"
1010
- "agents/**"
1111
- "plugins/**"
12+
- "workflows/**"
1213
- "*.js"
1314
- "README.md"
1415
- "docs/**"

‎AGENTS.md‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ The Awesome GitHub Copilot repository is a community-driven collection of custom
99
- **Instructions** - Coding standards and best practices applied to specific file patterns
1010
- **Skills** - Self-contained folders with instructions and bundled resources for specialized tasks
1111
- **Hooks** - Automated workflows triggered by specific events during development
12+
- **Workflows** - [Agentic Workflows](https://github.github.com/gh-aw) for AI-powered repository automation in GitHub Actions
1213
- **Plugins** - Installable packages that group related agents, commands, and skills around specific themes
1314

1415
## Repository Structure
@@ -20,6 +21,7 @@ The Awesome GitHub Copilot repository is a community-driven collection of custom
2021
├── instructions/ # Coding standards and guidelines (.instructions.md files)
2122
├── skills/ # Agent Skills folders (each with SKILL.md and optional bundled assets)
2223
├── hooks/ # Automated workflow hooks (folders with README.md + hooks.json)
24+
├── workflows/ # Agentic Workflows (.md files for GitHub Actions automation)
2325
├── plugins/ # Installable plugin packages (folders with plugin.json)
2426
├── docs/ # Documentation for different resource types
2527
├── eng/ # Build and automation scripts
@@ -96,6 +98,17 @@ All agent files (`*.agent.md`), prompt files (`*.prompt.md`), and instruction fi
9698
- Follow the [GitHub Copilot hooks specification](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks)
9799
- Optionally includes `tags` field for categorization
98100

101+
#### Workflow Files (workflows/*.md)
102+
- Each workflow is a standalone `.md` file in the `workflows/` directory
103+
- Must have `name` field (human-readable name)
104+
- Must have `description` field (wrapped in single quotes, not empty)
105+
- Should have `triggers` field (array of trigger types, e.g., `['schedule', 'issues']`)
106+
- Contains agentic workflow frontmatter (`on`, `permissions`, `safe-outputs`) and natural language instructions
107+
- File names should be lower case with words separated by hyphens
108+
- Only `.md` files are accepted — `.yml`, `.yaml`, and `.lock.yml` files are blocked by CI
109+
- Optionally includes `tags` field for categorization
110+
- Follow the [GitHub Agentic Workflows specification](https://github.github.com/gh-aw)
111+
99112
#### Plugin Folders (plugins/*)
100113
- Each plugin is a folder containing a `.github/plugin/plugin.json` file with metadata
101114
- plugin.json must have `name` field (matching the folder name)
@@ -107,7 +120,7 @@ All agent files (`*.agent.md`), prompt files (`*.prompt.md`), and instruction fi
107120

108121
### Adding New Resources
109122

110-
When adding a new agent, prompt, instruction, skill, hook, or plugin:
123+
When adding a new agent, prompt, instruction, skill, hook, workflow, or plugin:
111124

112125
**For Agents, Prompts, and Instructions:**
113126
1. Create the file with proper front matter
@@ -125,6 +138,14 @@ When adding a new agent, prompt, instruction, skill, hook, or plugin:
125138
7. Verify the hook appears in the generated README
126139

127140

141+
**For Workflows:**
142+
1. Create a new `.md` file in `workflows/` with a descriptive name (e.g., `daily-issues-report.md`)
143+
2. Include frontmatter with `name`, `description`, `triggers`, plus agentic workflow fields (`on`, `permissions`, `safe-outputs`)
144+
3. Compile with `gh aw compile --validate` to verify it's valid
145+
4. Update the README.md by running: `npm run build`
146+
5. Verify the workflow appears in the generated README
147+
148+
128149
**For Skills:**
129150
1. Run `npm run skill:create` to scaffold a new skill folder
130151
2. Edit the generated SKILL.md file with your instructions
@@ -241,6 +262,18 @@ For hook folders (hooks/*/):
241262
- [ ] Follows [GitHub Copilot hooks specification](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks)
242263
- [ ] Optionally includes `tags` array field for categorization
243264

265+
For workflow files (workflows/*.md):
266+
- [ ] File has markdown front matter
267+
- [ ] Has `name` field with human-readable name
268+
- [ ] Has non-empty `description` field wrapped in single quotes
269+
- [ ] Has `triggers` array field listing workflow trigger types
270+
- [ ] File name is lower case with hyphens
271+
- [ ] Contains `on` and `permissions` in frontmatter
272+
- [ ] Workflow uses least-privilege permissions and safe outputs
273+
- [ ] No `.yml`, `.yaml`, or `.lock.yml` files included
274+
- [ ] Follows [GitHub Agentic Workflows specification](https://github.github.com/gh-aw)
275+
- [ ] Optionally includes `tags` array field for categorization
276+
244277
For plugins (plugins/*/):
245278
- [ ] Directory contains a `.github/plugin/plugin.json` file
246279
- [ ] Directory contains a `README.md` file

‎CONTRIBUTING.md‎

Lines changed: 52 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -161,11 +161,61 @@ plugins/my-plugin-id/
161161
- **Clear purpose**: The plugin should solve a specific problem or workflow
162162
- **Validate before submitting**: Run `npm run plugin:validate` to ensure your plugin is valid
163163

164+
### Adding Agentic Workflows
165+
166+
[Agentic Workflows](https://github.github.com/gh-aw) are AI-powered repository automations that run coding agents in GitHub Actions. Defined in markdown with natural language instructions, they enable scheduled and event-triggered automation with built-in guardrails.
167+
168+
1. **Create your workflow file**: Add a new `.md` file in the `workflows/` directory (e.g., `daily-issues-report.md`)
169+
2. **Include frontmatter**: Add `name`, `description`, `triggers`, and optionally `tags` at the top, followed by agentic workflow frontmatter (`on`, `permissions`, `safe-outputs`) and natural language instructions
170+
3. **Test locally**: Compile with `gh aw compile --validate` to verify it's valid
171+
4. **Update the README**: Run `npm run build` to update the generated README tables
172+
173+
> **Note:** Only `.md` files are accepted — do not include compiled `.lock.yml` or `.yml` files. CI will block them.
174+
175+
#### Workflow file example
176+
177+
```markdown
178+
---
179+
name: 'Daily Issues Report'
180+
description: 'Generates a daily summary of open issues and recent activity as a GitHub issue'
181+
triggers: ['schedule']
182+
tags: ['reporting', 'issues', 'automation']
183+
on:
184+
schedule: daily on weekdays
185+
permissions:
186+
contents: read
187+
issues: read
188+
safe-outputs:
189+
create-issue:
190+
title-prefix: "[daily-report] "
191+
labels: [report]
192+
---
193+
194+
## Daily Issues Report
195+
196+
Create a daily summary of open issues for the team.
197+
198+
## What to Include
199+
200+
- New issues opened in the last 24 hours
201+
- Issues closed or resolved
202+
- Stale issues that need attention
203+
```
204+
205+
#### Workflow Guidelines
206+
207+
- **Security first**: Use least-privilege permissions and safe outputs instead of direct write access
208+
- **Clear instructions**: Write clear natural language instructions in the workflow body
209+
- **Descriptive names**: Use lowercase filenames with hyphens (e.g., `daily-issues-report.md`)
210+
- **Test locally**: Use `gh aw compile --validate` to verify your workflow compiles
211+
- **No compiled files**: Only submit the `.md` source — `.lock.yml` and `.yml` files are not accepted
212+
- Learn more at the [Agentic Workflows documentation](https://github.github.com/gh-aw)
213+
164214
## Submitting Your Contribution
165215

166216
1. **Fork this repository**
167217
2. **Create a new branch** for your contribution
168-
3. **Add your instruction, prompt file, chatmode, or plugin** following the guidelines above
218+
3. **Add your instruction, prompt file, chatmode, workflow, or plugin** following the guidelines above
169219
4. **Run the update script**: `npm start` to update the README with your new file (make sure you run `npm install` first if you haven't already)
170220
- A GitHub Actions workflow will verify that this step was performed correctly
171221
- If the README.md would be modified by running the script, the PR check will fail with a comment showing the required changes
@@ -234,6 +284,7 @@ We welcome many kinds of contributions, including the custom categories below:
234284
| **Prompts** | Reusable or one-off prompts for GitHub Copilot | ⌨️ |
235285
| **Agents** | Defined GitHub Copilot roles or personalities | 🎭 |
236286
| **Skills** | Specialized knowledge of a task for GitHub Copilot | 🧰 |
287+
| **Workflows** | Agentic Workflows for AI-powered repository automation | ⚡ |
237288
| **Plugins** | Installable packages of related prompts, agents, or skills | 🎁 |
238289

239290
In addition, all standard contribution types supported by [All Contributors](https://allcontributors.org/emoji-key/) are recognized.

‎README.md‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ This repository provides a comprehensive toolkit for enhancing GitHub Copilot wi
1212
- **👉 [Awesome Prompts](docs/README.prompts.md)** - Focused, task-specific prompts for generating code, documentation, and solving specific problems
1313
- **👉 [Awesome Instructions](docs/README.instructions.md)** - Comprehensive coding standards and best practices that apply to specific file patterns or entire projects
1414
- **👉 [Awesome Hooks](docs/README.hooks.md)** - Automated workflows triggered by specific events during development, testing, and deployment
15+
- **👉 [Awesome Agentic Workflows](docs/README.workflows.md)** - AI-powered repository automations that run coding agents in GitHub Actions with natural language instructions
1516
- **👉 [Awesome Skills](docs/README.skills.md)** - Self-contained folders with instructions and bundled resources that enhance AI capabilities for specialized tasks
1617
- **👉 [Awesome Plugins](docs/README.plugins.md)** - Curated plugins of related prompts, agents, and skills organized around specific themes and workflows
1718
- **👉 [Awesome Cookbook Recipes](cookbook/README.md)** - Practical, copy-paste-ready code snippets and real-world examples for working with GitHub Copilot tools and features
@@ -101,6 +102,10 @@ Instructions automatically apply to files based on their patterns and provide co
101102

102103
Hooks enable automated workflows triggered by specific events during GitHub Copilot coding agent sessions (like sessionStart, sessionEnd, userPromptSubmitted). They can automate tasks like logging, auto-committing changes, or integrating with external services.
103104

105+
### ⚡ Agentic Workflows
106+
107+
[Agentic Workflows](https://github.github.com/gh-aw) 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 — from issue triage to daily reports.
108+
104109
## 🎯 Why Use Awesome GitHub Copilot?
105110

106111
- **Productivity**: Pre-built agents, prompts and instructions save time and provide consistent results.
@@ -112,7 +117,7 @@ Hooks enable automated workflows triggered by specific events during GitHub Copi
112117

113118
We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on how to:
114119

115-
- Add new prompts, instructions, hooks, agents, or skills
120+
- Add new prompts, instructions, hooks, workflows, agents, or skills
116121
- Improve existing content
117122
- Report issues or suggest enhancements
118123

@@ -131,6 +136,8 @@ For AI coding agents working with this project, refer to [AGENTS.md](AGENTS.md)
131136
├── prompts/ # Task-specific prompts (.prompt.md)
132137
├── instructions/ # Coding standards and best practices (.instructions.md)
133138
├── agents/ # AI personas and specialized modes (.agent.md)
139+
├── hooks/ # Automated hooks for Copilot coding agent sessions
140+
├── workflows/ # Agentic Workflows for GitHub Actions automation
134141
├── plugins/ # Installable plugins bundling related items
135142
├── scripts/ # Utility scripts for maintenance
136143
└── skills/ # AI capabilities for specialized tasks
@@ -152,7 +159,7 @@ The customizations in this repository are sourced from and created by third-part
152159

153160
---
154161

155-
**Ready to supercharge your coding experience?** Start exploring our [prompts](docs/README.prompts.md), [instructions](docs/README.instructions.md), [hooks](docs/README.hooks.md), and [custom agents](docs/README.agents.md)!
162+
**Ready to supercharge your coding experience?** Start exploring our [prompts](docs/README.prompts.md), [instructions](docs/README.instructions.md), [hooks](docs/README.hooks.md), [agentic workflows](docs/README.workflows.md), and [custom agents](docs/README.agents.md)!
156163

157164
## Contributors ✨
158165

‎docs/README.workflows.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# ⚡ Agentic Workflows
2+
3+
[Agentic Workflows](https://github.github.com/gh-aw) 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.
4+
5+
### How to Use Agentic Workflows
6+
7+
**What's Included:**
8+
- Each workflow is a single `.md` file with YAML frontmatter and natural language instructions
9+
- Workflows are compiled to `.lock.yml` GitHub Actions files via `gh aw compile`
10+
- Workflows follow the [GitHub Agentic Workflows specification](https://github.github.com/gh-aw)
11+
12+
**To Install:**
13+
- Install the `gh aw` CLI extension: `gh extension install github/gh-aw`
14+
- Copy the workflow `.md` file to your repository's `.github/workflows/` directory
15+
- Compile with `gh aw compile` to generate the `.lock.yml` file
16+
- Commit both the `.md` and `.lock.yml` files
17+
18+
**To Activate/Use:**
19+
- Workflows run automatically based on their configured triggers (schedules, events, slash commands)
20+
- Use `gh aw run <workflow>` to trigger a manual run
21+
- Monitor runs with `gh aw status` and `gh aw logs`
22+
23+
**When to Use:**
24+
- Automate issue triage and labeling
25+
- Generate daily status reports
26+
- Maintain documentation automatically
27+
- Run scheduled code quality checks
28+
- Respond to slash commands in issues and PRs
29+
- Orchestrate multi-step repository automation
30+
31+
_No entries found yet._

0 commit comments

Comments
 (0)