README.md

Learning GitHub Agentic Workflows

A hands-on workshop that takes you from zero to a fully automated, AI-powered workflow — running on a schedule or on events in GitHub Actions.

Curriculum

#	File	Title	Status
0	00-welcome.md	Welcome — What We'll Build	✅
1	01-prerequisites.md	What You Need Before We Start	✅
2	Choose one: 02a-setup-codespace.md, 02b-setup-local.md, or 02c-setup-browser.md	Setup Adventure — A: Codespace, B: Local Terminal, or C: Browser (no terminal)	✅
4	04-github-actions-intro.md	What Are GitHub Actions?	✅
5	05-agentic-workflows-intro.md	What Are Agentic Workflows?	✅
5b	05b-agentic-workflows-security.md	How Agentic Workflows Stay Safe	✅
6	06-install-gh-aw.md	Install the gh-aw CLI Extension	✅
6a	06a-install-terminal.md	Codespace Terminal Path — Install gh-aw	✅
6b	06b-install-local.md	Local Terminal Path — Install gh-aw	✅
6c	06c-install-ui.md	GitHub UI Path — No Installation Needed	✅
7	07-your-first-workflow.md	Write Your First Agentic Workflow	✅
7a	07a-your-first-workflow-terminal.md	Terminal Path — Write Your First Agentic Workflow	✅
7a-part2	07a-part2-your-first-workflow-instructions.md	Terminal Path (Part 2) — Add Instructions and Finish Your First Workflow	✅
7c	07c-your-first-workflow-copilot.md	GitHub Copilot Path — Write Your First Agentic Workflow	✅
7d	07d-confirm-model-access.md	Confirm Model Access	✅
8	08-run-your-workflow.md	Run and Watch Your Workflow	✅
8b	08b-interpret-your-run.md	Interpret Your First Run	✅
9	09-agentic-editing.md	Refine Your Workflow with Agentic Editing	✅
12	12-test-and-iterate.md	Test and Improve Your Workflow	✅
14	14-next-steps.md	What's Next? Keep Exploring	✅
15	15-conditional-logic.md	Make Your Workflow Smarter with Conditional Logic	✅
16	16-connect-data-source.md	Connect a Live Data Source to Your Workflow	✅
17	17-add-mcp-tools.md	Give Your Agent More Tools with MCP	✅
18	18-share-and-reuse.md	Share and Reuse Your Agentic Workflows	✅
19	19-research-driven-training-node.md	Build a Research-Driven Next Training Node	✅
20	20-persistent-memory.md	Make Your Workflow Remember Across Runs	✅
21	21-inline-sub-agents.md	Split Complex Workflows with Inline Sub-Agents	✅
22	22-error-handling-and-resilience.md	Make Your Workflows Resilient to Failure	✅
23	23-ab-experiments.md	Test Your Prompt Ideas with A/B Experiments	✅
24	24-self-hosted-runners.md	Run Your Agentic Workflow on a Self-Hosted Runner	✅
25	25-audit-and-observability.md	Audit and Monitor Your Agentic Workflows	✅
26	26-manage-costs-and-budgets.md	Manage Costs and AI Credit Budgets	✅

Optional Side Quests

• Side Quest: Agentic Workflows for GitHub Actions Power Users — one-page cheat sheet for what changes vs what stays the same in agentic workflows; branches from Step 5.
• Side Quest: Agentic Workflows Deep Dive — classification exercises, example agent output, the two-file structure, and concept checks; branches from Step 5.
• Side Quest: Terminal Basics — optional primer that branches from Step 1.
• Side Quest: Environment Reference — glossary of workshop environments and tool terms with official docs links; branches from Step 1.
• Side Quest: Install gh-aw Troubleshooting — optional install troubleshooting reference that branches from Step 6.
• Side Quest: Using gh aw compile to Catch Errors Early — quick reference for gh aw compile, --validate, --watch, and common compile errors; branches from Step 7, Step 11a, or Step 13.
• Side Quest: Fix Codespaces actions:write Errors When Running gh aw run — troubleshooting guide for Codespaces workflow-trigger permission errors with a UI-first path and advanced recovery path; branches from Step 8.
• Side Quest: Diagnosing Common Agent Output Patterns — expanded troubleshooting guide for the five most common log patterns; branches from Step 9.
• Side Quest: Writing a Clear Agent Brief — five-step framework for designing any agentic workflow brief; branches from Step 10.
• Side Quest: Jailbreaking the Agent Brief — explains how adversarial instructions embedded in repository content attempt to override the agent's task brief, and how the compiled brief, minimal permissions:, safe-outputs, and network.allowed-domains contain any partial success; branches from Step 10.
• Side Quest: Frontmatter Deep Dive — Part A — walkthrough of the opening, trigger, and permissions sections of gh-aw frontmatter, with predict-and-try activities; branches from Step 11a.
• Side Quest: Frontmatter Deep Dive — Part B — walkthrough of the tools, safe-outputs, closing fence, and agent body sections, with predict-and-try activities; continues from Part A.
• Side Quest: Fuzzy Schedule Expressions — quick reference for choosing between daily, hourly, weekly, and other fuzzy schedule expressions; branches from Step 13.
• Side Quest: Evaluating and Iterating on Agent Output — structured rubric for judging output quality, a five-row problem-to-fix reference table, and a one-change-at-a-time iteration loop; branches from Step 12.
• Side Quest: GitHub Actions Expressions and Contexts — deep dive into ${{ }} syntax, available context objects, output references, and if: conditions; branches from Step 15.
• Side Quest: YAML Frontmatter Pitfalls — reference guide for the five most common YAML mistakes; branches from Step 11a.
• Side Quest: Write Better AI Task Briefs — five prompt-engineering techniques for getting clearer, more consistent AI output; branches from Step 11a.
• Side Quest: Explore and Adapt an Annotated Workflow — annotated daily-status.md walkthrough with hands-on edits to confirm each design decision; branches from Step 11a.
• Side Quest: Event-Driven Triggers in Agentic Workflows — primer on choosing between pull_request, push, issues, and schedule, and on matching safe-outputs to the trigger; branches from Step 11c.
• Side Quest: Passing Data Between Steps with $GITHUB_OUTPUT — deep-dive into how $GITHUB_OUTPUT works; branches from Step 16.
• Side Quest: How MCP Tool Servers Work — conceptual primer explaining what MCP is, how the agentic loop changes, and how to read tool calls in the Actions log; branches from Step 17.
• Side Quest: Storing Credentials with GitHub Secrets — guide to creating repository secrets, referencing them in workflow steps, using the built-in GITHUB_TOKEN, and scoping permissions; branches from Step 16 or Step 17.
• Side Quest: Token and Secret Exfiltration in Agentic Workflows — explains how crafted repository content can attempt to leak tokens or API keys, and how log masking, safe-outputs, network.allowed-domains, and minimal permissions: stop it; branches from Step 16.
• Side Quest: Deterministic vs Agentic Data Ops — decision guide for splitting fixed data operations from agentic interpretation in hybrid workflows; branches from Step 16.
• Side Quest: Long-Lived Credential Risks in Agentic Workflows — explains why personal access tokens create a larger attack surface than the ephemeral GITHUB_TOKEN and how permissions: minimization and network.allowed-domains contain the blast radius; branches from Step 16.
• Side Quest: Agentic Workflow Security Architecture (Explain Like You're 5) — visual, beginner-friendly explanation of sandbox boundaries, where the agent runs, and what safe outputs look like; branches from Step 17.
• Side Quest: Prompt Injection Attacks in Agentic Workflows — explains what prompt injection is, how gh-aw's task brief, permissions:, and safe-outputs limit the impact, and what you can do as a workflow author; branches from Step 17.
• Side Quest: Permission Escalation in Agentic Workflows — explains how over-scoped workflow authority lets a misdirected agent attempt changes the task never needed, and how minimal permissions:, safe-outputs, and protected-files enforce least privilege; branches from Step 17.
• Side Quest: Supply Chain Attacks via MCP Tool Servers — explains how a compromised or malicious MCP server can feed poisoned tool results to your agent, and how network.allowed-domains, the explicit tools: block, minimal permissions, and safe-outputs reduce that risk; branches from Step 17.
• Side Quest: Output Injection via Safe Outputs — explains how crafted repository content can embed misleading markdown into agent output to fool human reviewers, and how safe-outputs surface declarations and label scoping prevent it; branches from Step 17.
• Side Quest: Repository Poisoning via Agentic Write Access — explains how a misdirected agent granted contents: write could be tricked into committing backdoors or overwriting sensitive files, and how contents: read, protected-files, and safe-outputs: create-pull-request close that path entirely; branches from Step 17.
• Side Quest: Configure GitHub Copilot for Agentic Workflows — explains organization centralized billing and personal COPILOT_GITHUB_TOKEN billing; branches from Step 7d.
• Side Quest: Configure an Anthropic API Key — step-by-step guide to generating an Anthropic key, storing it as a repository secret, and switching your workflow to engine: claude; branches from Step 11a.
• Side Quest: Configure an OpenAI API Key — step-by-step guide to generating an OpenAI key, storing it as a repository secret, and switching your workflow to engine: codex; branches from Step 11a.
• Side Quest: Choosing Between Cache Memory and Repo Memory — decision guide, full field references, and example task briefs for both cache-memory and repo-memory; branches from Step 20.
• Side Quest: Sub-Agent Syntax Reference — name rules, block boundary rules, supported frontmatter fields, and model alias table for inline sub-agents; branches from Step 21.
• Side Quest: Agent Session Phases Explained — full phase reference table, activity feed tips, steering prompts, and advanced agent merge / --watch paths; branches from Step 11d2.
• Side Quest: Audit Reference — Artifacts, Firewall Logs, and Report Contents — detailed breakdown of gh aw audit report fields, agent artifact files, ⌖ AIC billing, firewall.md, and network.allow; branches from Step 25.
• Side Quest: Project Future AI Credit Costs with gh aw forecast — full walkthrough of gh aw forecast: reading P10/P50/P90 output, using --period week and --days 7, forecasting all workflows, and deriving a max-daily-ai-credits value from the P90 figure; branches from Step 26.

Getting Started

Start at Welcome — it shows you what you'll build and sets you up for success.