Skip to content

Commit d85ccfa

Browse files
Ubuntuclaude
Ubuntu
and
claude
committed
feat: Add gh-aw-setup skill with Repo Guardian workflow templates
Adds a new `gh-aw-setup` skill that guides users through setting up GitHub Agentic Workflows (gh-aw) in any repository, focusing on the Repo Guardian workflow. ## What's Included **Skill** (`.claude/skills/gh-aw-setup/`): - `SKILL.md` — Setup guide with prerequisites, 3-step quick start, secrets configuration, branch protection, override mechanism, troubleshooting, and comparison to gh-aw-adoption skill - `repo-guardian.md` — gh-aw workflow template (AI agent prompt that reviews PRs for ephemeral content: meeting notes, temp scripts, point-in-time documents) - `repo-guardian-gate.yml` — Standard GitHub Actions workflow that enforces Repo Guardian findings as a blocking CI check ## What Repo Guardian Does AI-powered PR reviewer that detects and blocks: - Meeting notes, sprint retrospectives, status updates - Temporary/one-off scripts (fix-thing.sh, debug-auth.sh) - Point-in-time documents that will become stale - Files with date prefixes suggesting snapshots Uses gh-aw with GitHub Copilot CLI engine, safe-outputs (max 1 comment), read-only GitHub access, and an override mechanism for legitimate exceptions. Source: Adapted from cybergym repo's production repo-guardian workflow. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
1 parent 0b20072 commit d85ccfa

File tree

3 files changed

+411
-0
lines changed

3 files changed

+411
-0
lines changed

‎.claude/skills/gh-aw-setup/SKILL.md‎

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
---
2+
name: gh-aw-setup
3+
version: 1.0.0
4+
description: Configure and set up GitHub Agentic Workflows (gh-aw) in a repository, including the Repo Guardian workflow that blocks PRs containing ephemeral content (meeting notes, temp scripts, point-in-time documents). Auto-activates for repo guardian setup, gh-aw configuration, or agentic workflow bootstrapping requests.
5+
source_urls:
6+
- https://github.com/github/gh-aw
7+
- https://github.com/github/gh-aw/blob/main/.github/aw/github-agentic-workflows.md
8+
auto_activates:
9+
- "set up repo guardian"
10+
- "configure gh-aw"
11+
- "add repo guardian"
12+
- "setup github agentic workflows"
13+
- "bootstrap gh-aw"
14+
- "install repo guardian"
15+
token_budget: 2000
16+
---
17+
18+
# GitHub Agentic Workflows Setup Skill
19+
20+
## Purpose
21+
22+
This skill guides you through setting up GitHub Agentic Workflows (gh-aw) in a
23+
repository, with a focus on the **Repo Guardian** workflow — a production-ready
24+
agentic workflow that reviews every PR for ephemeral content that doesn't belong
25+
in the repository.
26+
27+
## What Is Repo Guardian?
28+
29+
Repo Guardian is an AI-powered PR reviewer that automatically detects and flags:
30+
31+
- **Meeting notes** and sprint retrospectives committed to the repo
32+
- **Temporary scripts** (`fix-thing.sh`, `one-off-migration.py`)
33+
- **Point-in-time documents** that will become stale (status updates, diaries)
34+
- **Snapshot files** with date prefixes (`2024-01-15-deployment-notes.md`)
35+
36+
It posts a PR comment with findings and an override mechanism for legitimate exceptions.
37+
38+
### Two-Workflow Architecture
39+
40+
Repo Guardian uses two complementary workflows:
41+
42+
1. **`repo-guardian.md`** — The gh-aw agentic workflow (AI agent that reviews the PR)
43+
2. **`repo-guardian-gate.yml`** — A standard GitHub Actions workflow that enforces
44+
the agent's findings as a blocking CI check
45+
46+
## Prerequisites
47+
48+
```bash
49+
# 1. Install gh CLI
50+
gh --version
51+
52+
# 2. Install gh-aw extension
53+
gh extension install github/gh-aw
54+
gh aw --version
55+
56+
# 3. Verify repository access
57+
gh auth status
58+
```
59+
60+
## Quick Setup (3 Steps)
61+
62+
### Step 1: Copy Workflow Files
63+
64+
Copy the template files from this skill into your repository:
65+
66+
```bash
67+
# From the skill directory, copy templates:
68+
mkdir -p .github/workflows
69+
70+
# Copy the agentic workflow prompt
71+
cp repo-guardian.md .github/workflows/repo-guardian.md
72+
73+
# Copy the enforcement gate
74+
cp repo-guardian-gate.yml .github/workflows/repo-guardian-gate.yml
75+
```
76+
77+
> **Or use the templates in this skill directory** — see `repo-guardian.md` and
78+
> `repo-guardian-gate.yml` alongside this file.
79+
80+
### Step 2: Compile the Agentic Workflow
81+
82+
The `.md` file must be compiled to a `.lock.yml` before GitHub Actions can run it:
83+
84+
```bash
85+
cd .github/workflows
86+
gh aw compile repo-guardian
87+
88+
# Verify the lock file was created
89+
ls repo-guardian.lock.yml
90+
```
91+
92+
### Step 3: Configure Required Secrets
93+
94+
The gh-aw agent requires a GitHub Copilot token:
95+
96+
1. Go to **Repository Settings → Secrets and variables → Actions**
97+
2. Add secret: `COPILOT_GITHUB_TOKEN`
98+
- Value: A GitHub personal access token with Copilot access
99+
- Required scopes: `read:org`, `repo`
100+
101+
```bash
102+
# Or via CLI:
103+
gh secret set COPILOT_GITHUB_TOKEN --body "<your-token>"
104+
```
105+
106+
## Commit and Push
107+
108+
```bash
109+
git add .github/workflows/repo-guardian.md \
110+
.github/workflows/repo-guardian.lock.yml \
111+
.github/workflows/repo-guardian-gate.yml
112+
113+
git commit -m "feat: Add Repo Guardian agentic workflow
114+
115+
Adds AI-powered PR review that detects and blocks ephemeral content:
116+
- Meeting notes, sprint retrospectives, status updates
117+
- Temporary/one-off scripts
118+
- Point-in-time documents that will become stale
119+
120+
Uses gh-aw (GitHub Agentic Workflows) with GitHub Copilot CLI engine.
121+
Requires COPILOT_GITHUB_TOKEN secret to be configured.
122+
123+
Two-workflow setup:
124+
- repo-guardian.md: AI agent prompt (compiled to repo-guardian.lock.yml)
125+
- repo-guardian-gate.yml: CI enforcement gate
126+
127+
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>"
128+
129+
git push
130+
```
131+
132+
## Optional: Branch Protection
133+
134+
For maximum enforcement, require the Repo Guardian Gate check to pass:
135+
136+
1. Go to **Repository Settings → Branches → Branch protection rules**
137+
2. Edit the rule for `main` (or your default branch)
138+
3. Under **Require status checks to pass before merging**, add:
139+
- `Repo Guardian Gate`
140+
4. Save the rule
141+
142+
## Override Mechanism
143+
144+
When a legitimate file gets flagged, any collaborator can add a PR comment:
145+
146+
```
147+
repo-guardian:override This is a durable ADR, not a meeting note
148+
```
149+
150+
The reason after `override` is **required** for auditability. The gate will then
151+
pass, and the agent will post an acknowledgment comment.
152+
153+
## Optional: Custom Configuration
154+
155+
Create `repo-guardian.config.json` in the repo root to customize behavior:
156+
157+
```json
158+
{
159+
"allowlist": [
160+
"docs/decisions/**",
161+
"CHANGELOG.md"
162+
],
163+
"extraRules": "Also flag files in the /scratch directory unconditionally."
164+
}
165+
```
166+
167+
> The config file itself is explicitly excluded from Repo Guardian's checks.
168+
169+
## How It Works
170+
171+
### Trigger
172+
173+
Both workflows trigger on `pull_request` events (opened, synchronize, reopened).
174+
175+
### Agentic Workflow Flow
176+
177+
```
178+
PR opened
179+
→ repo-guardian.lock.yml activates
180+
→ gh-aw spawns Copilot agent in sandboxed container
181+
→ Agent reads changed files via GitHub MCP server (read-only)
182+
→ Agent analyzes each file for ephemeral content
183+
→ Agent posts ONE comment: "Repo Guardian - Passed" or "Repo Guardian - Action Required"
184+
→ safe-outputs enforces max 1 comment
185+
```
186+
187+
### Gate Flow
188+
189+
```
190+
PR opened / comment posted
191+
→ repo-guardian-gate.yml activates
192+
→ Waits 60s for agent comment (on PR events)
193+
→ Reads all PR comments
194+
→ If "Action Required" exists AND no override → fails CI
195+
→ If "Passed" or override present → passes CI
196+
```
197+
198+
### Security Model
199+
200+
- Agent has **read-only** GitHub access (no write permissions in the agent job)
201+
- All mutations (comments) go through **safe-outputs** with a max of 1
202+
- Override requires a **non-empty reason** (prevents trivial bypasses)
203+
- Gate enforces findings **independently** from the agent (defense in depth)
204+
205+
## Troubleshooting
206+
207+
**Agent not triggering:**
208+
209+
- Verify `COPILOT_GITHUB_TOKEN` secret exists
210+
- Check that `repo-guardian.lock.yml` was committed (not just the `.md`)
211+
- Ensure the PR is from the same repository (fork PRs are excluded for security)
212+
213+
**Gate passing even with violations:**
214+
215+
- Check that `repo-guardian-gate.yml` is on the default branch
216+
- Verify the gate is required in branch protection rules
217+
218+
**False positives:**
219+
220+
- Add an override comment: `repo-guardian:override <reason>`
221+
- Or add the path to `repo-guardian.config.json` allowlist
222+
223+
**Recompiling after edits:**
224+
225+
```bash
226+
cd .github/workflows
227+
gh aw compile repo-guardian
228+
git add repo-guardian.lock.yml
229+
git commit -m "chore: Recompile repo-guardian workflow"
230+
```
231+
232+
## Relationship to gh-aw-adoption Skill
233+
234+
This skill is **focused setup** for a specific, high-value workflow (Repo
235+
Guardian). For **full gh-aw adoption** across an entire repository (15-20
236+
workflows covering security, automation, quality), use the `gh-aw-adoption`
237+
skill instead.
238+
239+
| Skill | Use When |
240+
|-------|----------|
241+
| `gh-aw-setup` | You want Repo Guardian specifically, or are bootstrapping gh-aw |
242+
| `gh-aw-adoption` | You want comprehensive workflow automation (15-20 workflows) |

‎.claude/skills/gh-aw-setup/repo-guardian-gate.yml‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
name: Repo Guardian Gate
2+
3+
# This workflow enforces Repo Guardian findings as a blocking check.
4+
# Repo Guardian itself is advisory (posts comments). This gate checks
5+
# whether unresolved "Action Required" findings exist without an override.
6+
7+
on:
8+
pull_request:
9+
types: [opened, synchronize, reopened]
10+
branches: [main, master]
11+
issue_comment:
12+
types: [created]
13+
14+
permissions:
15+
contents: read
16+
pull-requests: read
17+
18+
jobs:
19+
check-repo-guardian:
20+
name: Repo Guardian Gate
21+
runs-on: ubuntu-latest
22+
# For issue_comment events, only run if the comment is on a PR
23+
if: >
24+
github.event_name == 'pull_request' ||
25+
(github.event_name == 'issue_comment' && github.event.issue.pull_request)
26+
steps:
27+
- name: Wait for Repo Guardian to complete
28+
if: github.event_name == 'pull_request'
29+
run: |
30+
echo "Waiting 60s for Repo Guardian agent to post findings..."
31+
sleep 60
32+
33+
- name: Check for unresolved Repo Guardian violations
34+
uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
35+
with:
36+
script: |
37+
const prNumber = context.issue?.number || context.payload.pull_request?.number;
38+
if (!prNumber) {
39+
core.info('No PR number found, skipping');
40+
return;
41+
}
42+
43+
const { data: comments } = await github.rest.issues.listComments({
44+
owner: context.repo.owner,
45+
repo: context.repo.repo,
46+
issue_number: prNumber,
47+
per_page: 100
48+
});
49+
50+
// Find the latest Repo Guardian comment
51+
const guardianComment = comments
52+
.filter(c => c.body.includes('Repo Guardian'))
53+
.pop();
54+
55+
if (!guardianComment) {
56+
core.info('No Repo Guardian comment found yet — passing');
57+
return;
58+
}
59+
60+
const hasViolations = guardianComment.body.includes('Action Required');
61+
const hasOverride = comments.some(c =>
62+
!c.body.includes('Repo Guardian') &&
63+
c.body.includes('repo-guardian:override') &&
64+
c.body.match(/repo-guardian:override\s+\S/)
65+
);
66+
const hasPassedComment = comments.some(c =>
67+
c.body.includes('Repo Guardian - Passed') ||
68+
c.body.includes('Override Acknowledged')
69+
);
70+
71+
if (hasViolations && !hasOverride && !hasPassedComment) {
72+
core.setFailed(
73+
'Repo Guardian found violations that have not been resolved or overridden. ' +
74+
'Fix the flagged files or add a comment: repo-guardian:override <reason>'
75+
);
76+
} else if (hasOverride || hasPassedComment) {
77+
core.info('Repo Guardian: passed (override acknowledged or no violations)');
78+
} else {
79+
core.info('Repo Guardian: passed');
80+
}

0 commit comments

Comments
 (0)