Skip to content

Commit a550d72

Browse files
author
UncleBats
committed
restructure
1 parent d6accda commit a550d72

13 files changed

Lines changed: 2607 additions & 2478 deletions

‎AGENTS.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,17 @@ CopilotDevDays-AgenticWorkflows/
3939
├── README.md # Workshop overview
4040
├── gh-agentic-workflows-session.md # Event organizer materials
4141
├── facilitator-guide.md # Facilitator instructions
42-
├── participant-handout.md # Student reference guide
42+
├── participant-handout.md # Student reference guide (overview/index)
43+
├── participant-handout-setup.md # Setup guide (prerequisites, installation)
44+
├── participant-handout-exercise1.md # Exercise 1: Daily Standup Status
45+
├── participant-handout-exercise2.md # Exercise 2: CI Coach
46+
├── participant-handout-exercise3.md # Exercise 3: CI Doctor
47+
├── participant-handout-exercise4.md # Exercise 4: Continuous Test Updates
48+
├── participant-handout-exercise5.md # Exercise 5: Repository Agent
49+
├── participant-handout-exercise6.md # Exercise 6: Issue Triage
50+
├── participant-handout-exercise7.md # Exercise 7: Feature Planning
51+
├── participant-handout-exercise8.md # Exercise 8: Explore on Your Own
52+
├── participant-handout-resources.md # Commands, resources & next steps
4353
├── example-workflow-prompts.md # 28 tested workflow prompts
4454
├── slide-deck-outline.md # Presentation structure
4555
└── quick-reference-card.md # One-page cheat sheet

‎docs/workshop/README.md‎

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -29,13 +29,17 @@ This directory contains comprehensive materials for delivering the "From Code to
2929

3030
### For Participants
3131

32-
- **[participant-handout.md](participant-handout.md)** - Student reference guide containing:
33-
- All setup commands
34-
- Exercise instructions
35-
- Workflow creation patterns
36-
- Troubleshooting guide
37-
- Resource links
38-
- Quick command reference
32+
- **[participant-handout.md](participant-handout.md)** - Student reference guide (overview & navigation), split into individual pages:
33+
- [Setup Guide](participant-handout-setup.md) - Prerequisites, installation, repository setup
34+
- [Exercise 1: Daily Standup Status](participant-handout-exercise1.md) - Interactive CLI + Cloud Agent
35+
- [Exercise 2: CI Coach](participant-handout-exercise2.md) - Manual workflow creation
36+
- [Exercise 3: CI Doctor](participant-handout-exercise3.md) - CI failure diagnostician
37+
- [Exercise 4: Continuous Test Updates](participant-handout-exercise4.md) - Cloud Agent workflow
38+
- [Exercise 5: Repository Agent](participant-handout-exercise5.md) - VS Code Agent workflow
39+
- [Exercise 6: Issue Triage](participant-handout-exercise6.md) - Community workflow reuse
40+
- [Exercise 7: Feature Planning](participant-handout-exercise7.md) - `/plan` command
41+
- [Exercise 8: Explore on Your Own](participant-handout-exercise8.md) - Open challenges
42+
- [Commands, Resources & Next Steps](participant-handout-resources.md) - Reference & troubleshooting
3943

4044
### Resources
4145

‎docs/workshop/participant-handout-exercise1.md‎

Lines changed: 278 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,278 @@
1+
# Exercise 1: Daily Standup Status
2+
3+
> 📖 **Navigation:** [← Setup Guide](participant-handout-setup.md) | [Back to Overview](participant-handout.md) | [Next: Exercise 2 →](participant-handout-exercise2.md)
4+
5+
---
6+
7+
## Introduction: Why Agentic Workflows?
8+
9+
**The Challenge:**
10+
11+
Imagine a team of 9 people working on a repository. Everyone is busy with their tasks, and while you generally know what your team is working on, you're never fully in touch with everything that's been completed or what's coming next. You've added daily standups and progress boards, but challenges remain:
12+
13+
- What happens when people have a day off?
14+
- What if someone forgets to mention critical progress during standup?
15+
- Who notices that PR sitting open for 2 days without a review?
16+
- How do you track the actual state of the repository between standups?
17+
18+
**The Solution:**
19+
20+
Instead of relying solely on humans to track and communicate everything, we'll create automated assistants that work continuously in the background. These agentic workflows will:
21+
22+
- Generate daily summaries of real repository activity
23+
- Monitor PRs and issues that need attention
24+
- Provide objective data for standups and planning
25+
- Work 24/7 without taking days off
26+
- Never forget to check or report on important changes
27+
28+
**What We're Building:**
29+
30+
Throughout these exercises, you'll progressively build an ecosystem of intelligent automations that transform your repository into a self-organizing, self-reporting system. Each workflow adds a new capability, and together they create comprehensive visibility into your project's health and progress.
31+
32+
**How We're Building:**
33+
34+
You'll experience three different approaches to creating workflows, each with increasing quality and sophistication:
35+
36+
1. **Interactive CLI** (`gh aw new`) - Quick and interactive, good for learning
37+
2. **Cloud Agent** (web browser agent tab) - Better quality by referencing documentation
38+
3. **Repository Agent** (VS Code Copilot Chat after `gh aw init`) - Best quality with repository context
39+
40+
Let's start with the most fundamental need: knowing what happened in your repository each day.
41+
42+
---
43+
44+
## Exercise 1: Daily Standup Status
45+
46+
**Goal:** Create a workflow that generates a daily summary of repository activity to support your standup meetings.
47+
48+
**Method:** We'll use the interactive CLI (`gh aw new`) to learn the fundamentals of workflow creation.
49+
50+
**Step 1: Create the workflow**
51+
52+
```bash
53+
gh aw new
54+
```
55+
56+
You'll be guided through several prompts:
57+
58+
**1. What should we call this workflow?**
59+
```
60+
daily-report
61+
```
62+
63+
**2. When should this workflow run?**
64+
- Choose: `Schedule (daily, scattered execution time)`
65+
66+
**3. Which AI engine should process this workflow?**
67+
- Choose: `copilot - GitHub Copilot CLI`
68+
69+
**4. Which tools should the AI have access to?**
70+
- Select:
71+
- `github` - GitHub API tools (issues, PRs, comments, repos)
72+
- Tools enabled:
73+
- `create-issue` - Create a new GitHub issue
74+
- `add-comment` - Add a comment to an issue, PR, or discussion
75+
- `close-issue` - Close a GitHub issue
76+
- `update-issue` - Update an existing GitHub issue
77+
78+
**5. Network Access Control**
79+
- Leave defaults (no external network access needed)
80+
81+
**6. What should this workflow do?** (Description)
82+
```
83+
Run daily at 9 AM and create an issue with a summary of repository activity from past 24 hours. Include commits, pull requests, issues, and CI/CD failures.
84+
```
85+
86+
**Step 2: Review the generated files**
87+
88+
The command creates **four files**:
89+
90+
1. **`daily-report.md`** - The editable source workflow in `.github/workflows/`
91+
2. **`daily-report.lock.yml`** - The compiled GitHub Actions workflow in `.github/workflows/`
92+
3. **`.gitattributes`** - Git configuration file in the repository root
93+
4. **`.github/aw/actions-lock.json`** - GitHub Actions version lock file
94+
95+
**Understanding the files:**
96+
97+
**`daily-report.md`** contains:
98+
- **Frontmatter** (YAML between `---` markers): Configuration defining triggers, permissions, and tools
99+
- **Natural language instructions**: Your description in markdown format
100+
101+
**`daily-report.lock.yml`** is the compiled workflow that:
102+
- Contains a simplified version of your prompt
103+
- Is what GitHub Actions actually executes
104+
- Gets regenerated when you change the `.md` file
105+
106+
**`.gitattributes`** contains:
107+
```
108+
.github/workflows/*.lock.yml linguist-generated=true merge=ours
109+
```
110+
This configuration:
111+
- Marks all `.lock.yml` files as generated (excluded from language statistics)
112+
- Sets merge strategy to `ours` (automatically resolves merge conflicts by keeping your version)
113+
114+
**`.github/aw/actions-lock.json`** locks GitHub Actions to specific versions and commit SHAs:
115+
```json
116+
{
117+
"entries": {
118+
"actions/checkout@v6.0.2": {
119+
"repo": "actions/checkout",
120+
"version": "v6.0.2",
121+
"sha": "de0fac2e4500dabe0009e67214ff5f5447ce83dd"
122+
},
123+
...
124+
}
125+
}
126+
```
127+
This file is a cache of resolved `action@version` → commit SHA mappings. During workflow compilation, the compiler tries to pin each action reference to an immutable commit SHA for security. The cache avoids problems when compiling with limited-permission tokens (like GitHub Copilot Coding Agent) that may not have access to resolve external repositories. Without this cache, compilation can be unstable—succeeding with a permissive token but failing when token access is restricted. Commit this file to version control so all contributors use consistent action references.
128+
129+
📚 **Learn more:** [What is the actions-lock.json file?](https://github.github.com/gh-aw/reference/faq/#what-is-the-actions-lockjson-file)
130+
131+
📚 **Learn more:** [How Agentic Workflows Work](https://github.github.com/gh-aw/introduction/how-they-work/)
132+
133+
**Step 3: Observe the limitation**
134+
135+
Open `.github/workflows/daily-report.md` and look at the prompt. It's very basic - just your description. This works, but we can achieve much better results.
136+
137+
**Why this matters:** The quality of the AI's output depends heavily on the quality and detail of the instructions. The simple interactive CLI creates a minimal prompt, which means the workflow might:
138+
- Miss important details
139+
- Not format output consistently
140+
- Lack error handling
141+
- Be less reliable
142+
143+
**What's next:** In the following exercises, we'll use more sophisticated approaches that generate better prompts and higher-quality workflows.
144+
145+
**Step 4: Commit and test**
146+
147+
```bash
148+
# Review the generated files or view in your code editor
149+
cat .github/workflows/daily-report.md
150+
cat .github/workflows/daily-report.lock.yml
151+
152+
# Commit all files
153+
git add .
154+
git commit -m "Add daily report workflow (basic version)"
155+
git push
156+
```
157+
158+
**Step 5: Manually trigger to test**
159+
160+
Since it's scheduled for daily execution, trigger it manually to see it work:
161+
162+
1. Go to your repository on GitHub
163+
2. Click **Actions** tab
164+
3. Select **daily-report** workflow
165+
4. Click **Run workflow** button
166+
5. Watch it execute
167+
168+
![Workflow execution progress](images/workflow-progress.png)
169+
170+
**Understanding the workflow execution:**
171+
172+
The workflow runs through **5 distinct phases**:
173+
174+
1. **activation** (✅ ~16s) - Sets up the workflow environment, checks out the repository code, and prepares the runtime
175+
2. **agent** (✅ ~2m) - The AI agent analyzes your repository, reads commits, PRs, and issues from the past 24 hours, and formulates a summary
176+
3. **detection** (🟡 ~45s) - Validates the agent's output to ensure it's properly formatted and safe to process
177+
4. **safe_outputs** (⚪ pending) - **This is the automation step** that interprets the JSON output from the agent and creates the actual issue in your repository
178+
5. **conclusion** (⚪ pending) - Finalizes the workflow and cleans up
179+
180+
**Important:** The agent itself doesn't directly create issues, PRs, or comments. Instead, it produces **structured JSON output** that describes what should be created. The `safe_outputs` step then interprets this JSON and performs the actual GitHub API calls to create the issue. This separation ensures security and allows for validation before any changes are made to your repository.
181+
182+
---
183+
184+
## Exercise 1b: Upgrade Daily Report with Cloud Agent
185+
186+
**Why: From Basic to Production-Quality**
187+
188+
In Exercise 1, you used the interactive CLI to create a daily-report workflow. It works, but the prompt is minimal—just your one-line description. The cloud agent produces significantly better workflows because it can **download and reference the official documentation** while generating the workflow. This means richer prompts, better error handling, and more consistent output formatting.
189+
190+
Think of it this way: the CLI is like writing a quick note from memory, while the cloud agent is like writing with the documentation open in front of you.
191+
192+
**What: A Smarter Daily Report**
193+
194+
By updating the existing workflow through the cloud agent, you'll get:
195+
- **Detailed, structured prompts** generated from documentation best practices
196+
- **Better formatting** for the daily summary issue
197+
- **More comprehensive coverage** of repository activity
198+
- **A Pull Request** with the changes, so you can compare before and after
199+
200+
**How: Update Using the Cloud Agent**
201+
202+
**Method:** We'll use the cloud agent (web browser) to upgrade the existing daily-report workflow.
203+
204+
**Step 1: Navigate to the cloud agent**
205+
206+
1. Go to your repository on GitHub.com in your web browser
207+
2. Click on the **Agent** tab (next to Code, Issues, Pull Requests, etc.)
208+
209+
**⚠️ First-time setup — Configure billing for cloud resources:**
210+
211+
If this is your first time using the cloud agent, you may see a **red banner** instructing you to configure billing for cloud resources and premium requests. To resolve this:
212+
213+
1. Click the link in the banner, or navigate manually:
214+
- Click your **profile icon** (top-right) → **Settings**
215+
- In the left sidebar: **Copilot** → **Features**
216+
2. Scroll down to the **Billing** section
217+
3. Under **"Usage billed to"**, click **"Select billing entity"**
218+
4. Select the **organization** where you receive your Copilot license from
219+
220+
![Copilot billing configuration](images/usage-billing.png)
221+
222+
Once configured, return to your repository and click the **Agent** tab again.
223+
224+
**Step 2: Provide the upgrade prompt**
225+
226+
In the cloud agent chat, provide this prompt:
227+
228+
```
229+
Update the existing daily-report workflow for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/create.md. Create a Pull Request when you're done.
230+
231+
The purpose of the workflow is to act as a daily report that helps team members keep up to date. It should:
232+
Run daily at 9 AM and create an issue with a summary of repository activity from past 24 hours. Include commits, pull requests, issues, and CI/CD failures.
233+
234+
Use the schedule trigger and create issues using safe-outputs.
235+
```
236+
237+
**Step 3: Review and merge the generated PR**
238+
239+
The cloud agent creates a **Pull Request** with the updated workflow files.
240+
241+
1. Go to your repository on GitHub → **Pull Requests** tab
242+
2. Review the PR created by the agent
243+
3. **Compare the changes:** Look at how the cloud agent improved the prompt in `.github/workflows/daily-report.md` compared to the basic version from Exercise 1
244+
4. Verify the workflow files:
245+
- `.github/workflows/daily-report.md` (updated source workflow)
246+
- `.github/workflows/daily-report.lock.yml` (recompiled workflow)
247+
5. **Merge the PR to main**
248+
249+
**Step 4: Pull the changes locally**
250+
251+
```bash
252+
git pull
253+
```
254+
255+
**Step 5: Compare the improvement**
256+
257+
Open `.github/workflows/daily-report.md` and notice how much richer the prompt is now. The cloud agent typically adds:
258+
- Structured output formatting instructions
259+
- Specific sections for commits, PRs, issues, and failures
260+
- Error handling guidance
261+
- Tone and style direction
262+
263+
**Step 6: Trigger the upgraded workflow**
264+
265+
Now let's run the improved version and compare the output:
266+
267+
1. Go to your repository → **Actions** tab
268+
2. Select **daily-report** workflow
269+
3. Click **Run workflow** button → Run workflow
270+
4. Watch it execute through the same 5 phases (activation → agent → detection → safe_outputs → conclusion)
271+
272+
The resulting issue should contain roughly the same information as before, but now the output is **better structured and formatted**. The cloud agent's richer prompt gives the AI clearer instructions on how to organize commits, PRs, issues, and failures—so the generated issue is more consistent and easier to read during standups.
273+
274+
**Key Insight:** The same workflow purpose, but dramatically better instructions. This is why we use the cloud agent for all subsequent exercises—it consistently produces higher-quality workflows by referencing the official documentation during generation.
275+
276+
---
277+
278+
> 📖 **Navigation:** [← Setup Guide](participant-handout-setup.md) | [Back to Overview](participant-handout.md) | [Next: Exercise 2 →](participant-handout-exercise2.md)

0 commit comments

Comments
 (0)