ben.carrasco/prowler
1
0
Fork 0
mirror of https://github.com/prowler-cloud/prowler.git synced 2026-07-16 09:01:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(skills): Github Agentic Workflow

Browse Source
This commit is contained in:
Pepe Fagoaga
2026-02-14 21:44:18 +01:00
parent da5328985a
commit 77fd7e7526
3 changed files with 253 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+6 -6
View File
@@ -45,7 +45,7 @@ Use these skills for detailed patterns on-demand:
| `prowler-pr` | Pull request conventions | [SKILL.md](skills/prowler-pr/SKILL.md) |
| `prowler-docs` | Documentation style guide | [SKILL.md](skills/prowler-docs/SKILL.md) |
| `prowler-attack-paths-query` | Create Attack Paths openCypher queries | [SKILL.md](skills/prowler-attack-paths-query/SKILL.md) |
| `prowler-gh-aw` | GitHub Agentic Workflows (gh-aw) | [SKILL.md](skills/prowler-gh-aw/SKILL.md) |
| `gh-aw` | GitHub Agentic Workflows (gh-aw) | [SKILL.md](skills/gh-aw/SKILL.md) |
| `skill-creator` | Create new AI agent skills | [SKILL.md](skills/skill-creator/SKILL.md) |
### Auto-invoke Skills
@@ -63,12 +63,12 @@ When performing these actions, ALWAYS invoke the corresponding skill FIRST:
| App Router / Server Actions | `nextjs-15` |
| Building AI chat features | `ai-sdk-5` |
| Committing changes | `prowler-commit` |
| Configuring MCP servers in agentic workflows | `prowler-gh-aw` |
| Configuring MCP servers in agentic workflows | `gh-aw` |
| Create PR that requires changelog entry | `prowler-changelog` |
| Create a PR with gh pr create | `prowler-pr` |
| Creating API endpoints | `jsonapi` |
| Creating Attack Paths queries | `prowler-attack-paths-query` |
| Creating GitHub Agentic Workflows | `prowler-gh-aw` |
| Creating GitHub Agentic Workflows | `gh-aw` |
| Creating ViewSets, serializers, or filters in api/ | `django-drf` |
| Creating Zod schemas | `zod-4` |
| Creating a git commit | `prowler-commit` |
@@ -78,17 +78,17 @@ When performing these actions, ALWAYS invoke the corresponding skill FIRST:
| Creating/modifying models, views, serializers | `prowler-api` |
| Creating/updating compliance frameworks | `prowler-compliance` |
| Debug why a GitHub Actions job is failing | `prowler-ci` |
| Debugging gh-aw compilation errors | `prowler-gh-aw` |
| Debugging gh-aw compilation errors | `gh-aw` |
| Fill .github/pull_request_template.md (Context/Description/Steps to review/Checklist) | `prowler-pr` |
| General Prowler development questions | `prowler` |
| Implementing JSON:API endpoints | `django-drf` |
| Importing Copilot Custom Agents into workflows | `prowler-gh-aw` |
| Importing Copilot Custom Agents into workflows | `gh-aw` |
| Inspect PR CI checks and gates (.github/workflows/*) | `prowler-ci` |
| Inspect PR CI workflows (.github/workflows/*): conventional-commit, pr-check-changelog, pr-conflict-checker, labeler | `prowler-pr` |
| Mapping checks to compliance controls | `prowler-compliance` |
| Mocking AWS with moto in tests | `prowler-test-sdk` |
| Modifying API responses | `jsonapi` |
| Modifying gh-aw workflow frontmatter or safe-outputs | `prowler-gh-aw` |
| Modifying gh-aw workflow frontmatter or safe-outputs | `gh-aw` |
| Regenerate AGENTS.md Auto-invoke tables (sync.sh) | `skill-sync` |
| Review PR requirements: template, title conventions, changelog gate | `prowler-pr` |
| Review changelog format and conventions | `prowler-changelog` |
skills/gh-aw/SKILL.md
+223
View File
@@ -0,0 +1,223 @@
---
name: gh-aw
description: >
Create and maintain GitHub Agentic Workflows (gh-aw) for Prowler.
Trigger: When creating agentic workflows, modifying gh-aw frontmatter, configuring safe-outputs,
setting up MCP servers in workflows, importing Copilot Custom Agents, or debugging gh-aw compilation.
license: Apache-2.0
metadata:
author: prowler-cloud
version: "1.0"
scope: [root]
auto_invoke:
- "Creating GitHub Agentic Workflows"
- "Modifying gh-aw workflow frontmatter or safe-outputs"
- "Configuring MCP servers in agentic workflows"
- "Importing Copilot Custom Agents into workflows"
- "Debugging gh-aw compilation errors"
allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch
---
## When to Use
- Creating new `.github/workflows/*.md` agentic workflows
- Modifying frontmatter (triggers, permissions, safe-outputs, tools, MCP servers)
- Creating or importing `.github/agents/*.md` Copilot Custom Agents
- Debugging `gh aw compile` errors or warnings
- Configuring network access, rate limits, or footer templates
---
## File Layout
```
.github/
├── workflows/
│ ├── {name}.md # Frontmatter + thin context dispatcher
│ └── {name}.lock.yml # Auto-generated — NEVER edit manually
├── agents/
│ └── {name}.md # Full agent persona (reusable)
└── aw/
└── actions-lock.json # Action SHA pinning — commit this
```
See [references/](references/) for existing workflow and agent examples in this repo.
---
## Critical Patterns
### Two-File Architecture
Workflow file = **config + context only**. Agent file = **all reasoning logic**.
The workflow imports the agent via `imports:` and passes sanitized runtime context. The agent contains the persona, rules, steps, and output format. This separation makes agents reusable across workflows.
### Import Path Resolution
Paths resolve **relative to the importing file**, NOT from repo root:
```yaml
# From .github/workflows/my-workflow.md:
imports:
- ../agents/my-agent.md # CORRECT
- .github/agents/my-agent.md # WRONG — resolves to .github/workflows/.github/agents/
```
### Sanitized Context (Security)
NEVER pass raw `github.event.issue.body` to the agent:
```markdown
${{ needs.activation.outputs.text }}
```
### Read-Only Permissions + Safe Outputs
Workflows run read-only. Writes go through `safe-outputs`:
```yaml
# GOOD
permissions:
issues: read
safe-outputs:
add-comment:
hide-older-comments: true
# BAD — never give the agent write access
permissions:
issues: write
```
### Strict Mode
`strict: true` (default) enforces: no write permissions, explicit network config, no wildcard domains, ecosystem identifiers required. Set `strict: false` only during development.
### Footer Control
Prevent double footers with `messages.footer`:
```yaml
safe-outputs:
messages:
footer: "> 🤖 Generated by [{workflow_name}]({run_url}) [Experimental]"
```
Variables: `{workflow_name}`, `{run_url}`, `{triggering_number}`, `{event_type}`, `{status}`.
### MCP Servers
Always use `allowed` to restrict tools. Add domains to `network.allowed`:
```yaml
network:
allowed:
- "mcp.prowler.com"
mcp-servers:
prowler:
url: "https://mcp.prowler.com/mcp"
allowed:
- prowler_hub_get_check_details
- prowler_hub_get_check_code
- prowler_docs_search
```
---
## Trigger Patterns
| Pattern | Trigger | Use Case |
|---------|---------|----------|
| LabelOps | `issues.types: [labeled]` + `names: [label]` | Triage, review |
| ChatOps | `issue_comment` + command parsing | Bot commands |
| DailyOps | `schedule: daily` | Reports, maintenance |
| IssueOps | `issues.types: [opened]` | Auto-triage on creation |
Dual-label gate (require trigger label + existing label):
```yaml
on:
issues:
types: [labeled]
names: [ai-review]
if: contains(toJson(github.event.issue.labels), 'status/needs-triage')
```
---
## Safe Outputs Quick Reference
| Type | What | Key options |
|------|------|-------------|
| `add-comment` | Post comment | `hide-older-comments`, `target` |
| `create-issue` | Create issue | `title-prefix`, `labels`, `close-older-issues`, `expires` |
| `add-labels` | Add labels | `allowed` (restrict to list) |
| `remove-labels` | Remove labels | `allowed` (restrict to list) |
| `create-pull-request` | Create PR | `max`, `target-repo` |
| `close-issue` | Close issue | `target`, `required-labels` |
| `update-issue` | Update fields | `status`, `title`, `body` |
| `dispatch-workflow` | Trigger workflow | `workflows` (list) |
---
## AI Engines
| Engine | Value | Notes |
|--------|-------|-------|
| GitHub Copilot | `copilot` | Default, supports Custom Agents |
| Claude | `claude` | Anthropic |
| OpenAI Codex | `codex` | OpenAI |
---
## Commands
```bash
# Compile workflows (regenerates lock files)
gh aw compile
# Compile with strict validation
gh aw compile --strict
# Check workflow status
gh aw status
# Add a community workflow
gh aw add owner/repo/workflow.md
# Trigger manually
gh aw run workflow-name
# View logs
gh aw logs workflow-name
```
---
## Compilation Checklist
After modifying any `.github/workflows/*.md`:
- [ ] Run `gh aw compile` — check for errors
- [ ] Stage the `.lock.yml` alongside the `.md`
- [ ] Stage `.github/aw/actions-lock.json` if changed
- [ ] Verify `network.allowed` includes all MCP server domains
- [ ] Verify permissions are read-only (use safe-outputs for writes)
---
## .gitattributes
Add to repo root so lock files auto-resolve on merge:
```
.github/workflows/*.lock.yml linguist-generated=true merge=ours
```
---
## Resources
- **Examples**: See [references/](references/) for existing workflow and agent files in this repo
- **Documentation**: See [references/](references/) for links to gh-aw official docs
skills/gh-aw/references/docs.md
+24
View File
@@ -0,0 +1,24 @@
# GitHub Agentic Workflows Documentation
## Local Examples
Working workflow and agent files in this repo:
- `.github/workflows/issue-triage.md` - Workflow frontmatter + context dispatcher (LabelOps pattern)
- `.github/agents/issue-triage.md` - Full triage agent persona with output format
- `.github/workflows/issue-triage.lock.yml` - Compiled lock file (auto-generated)
- `.github/aw/actions-lock.json` - Action SHA pinning
- `.gitattributes` - Lock file merge strategy
## Official Documentation
- gh-aw docs: https://github.github.com/gh-aw/
- Frontmatter reference: https://github.github.com/gh-aw/reference/frontmatter/
- Safe outputs: https://github.github.com/gh-aw/reference/safe-outputs/
- Triggers: https://github.github.com/gh-aw/reference/triggers/
- Tools: https://github.github.com/gh-aw/reference/tools/
- MCP servers: https://github.github.com/gh-aw/guides/mcps/
- Imports: https://github.github.com/gh-aw/reference/imports/
- Network access: https://github.github.com/gh-aw/reference/network/
- Design patterns: https://github.github.com/gh-aw/patterns/
- Copilot Custom Agents: https://github.github.com/gh-aw/reference/copilot-custom-agents/