GitHub Agentic Workflows Workshop

Welcome to our Agent Factory Tour

By the end of this workshop, a real AI agent will create an issue with a summary of the activity in your repository over the latest 24h, every day, without you writing shell-script workflow code.

You'll build a GitHub Agentic Workflow:

A GitHub Action that uses AI to inspect your repository, decide what matters, and publish a useful status report on a schedule — practical enough to adapt for real teams.

Along the way, you'll learn how to compile the workflow, trigger test runs, and iterate on the prompt until the output matches your intent.

Excited to get started? Let's gooo! 🚀

Before we start

Before you dive in, confirm you have the accounts and tool access this workshop needs.

Confirm account access _#

Sign in at github.com. If you do not have an account yet, use the Sign up option there first.

Prepare your environment _#

This workshop runs in a GitHub Codespace — a cloud-hosted terminal with no local installs required. You will set one up in the next step.

Already comfortable managing Git and the GitHub CLI on your machine? You can take the optional Local Terminal Setup side quest, then rejoin the main workshop.

Verify AI engine access _#

Open github.com/settings/copilot and confirm both show:

• Copilot CLI is enabled
• Some Models are available

This workshop uses GitHub Copilot end-to-end, so you do not need to configure any external provider API keys.

Set Up a Codespace

📋 Before You Start _#

• You have a GitHub account with access to GitHub Codespaces
• Your account can create public repositories (free tier works)
• You want a browser-based terminal and do not need to install tools locally

🎯 What You'll Do _#

You'll launch a GitHub Codespace for this workshop, open the built-in terminal, and land in a ready-to-use environment for the next step.

Codespaces is the recommended environment for this workshop and the path used throughout the core steps.

Steps _#

These steps take about 5 minutes. If you get stuck on any command, Side Quest: Terminal Basics is a 2-minute read.

New repository _#

1. Create your own public repository at github.com/new:
   • Choose yourself as owner.
   • Visibility Private, it's good to learn on our own. We can make it public later if we want to share our work.
   • Name it my-agentic-workflows.
   • Check Add a README file.
   • Click Create repository.

Open the Codespace _#

1. In your new repository, click the green Code button.
2. Click the Codespaces tab.
   • Leave main selected as the branch.
   • Click Create codespace on main.
   • Wait 30–60 seconds for GitHub to prepare the container.
3. The Codespace opens in a new browser tab showing a VS Code-style editor. Leave this tab open for the rest of the workshop.

Codespaces auto-save your work. If you close the tab, open github.com/codespaces to resume where you left off.

Open the Codespace terminal _#

1. When the Codespace editor loads, open the built-in terminal with Ctrl+` (or Cmd+Option+` on Mac).
2. Wait for the terminal prompt to appear.
3. Keep this terminal open. It is already inside your practice repository.

Verify your Codespace is ready _#

The diagram below shows your Codespace connection to GitHub.

1. Run these commands in the Codespace terminal:

gh --version
gh auth status

1. Confirm gh --version shows gh version 2.40.0 or newer.
2. Confirm gh auth status shows you are logged in to github.com.

What success looks like:

gh version 2.40.0 (2024-01-01)
...
github.com
  ✓ Logged in to github.com as <your-username>

✅ Checkpoint _#

• You confirmed your GitHub plan includes Codespaces access (free tier includes 60 hours/month)
• The Codespace editor is open in your browser
• The built-in terminal is open in your Codespace
• gh --version returns version 2.40.0 or newer
• gh auth status confirms you are logged in to github.com
• The Codespace is attached to your my-agentic-workflows practice repository

GitHub Actions in 5 Minutes

🎯 What You'll Do _#

You'll do a fast refresher on the Actions primitives used in this workshop: triggers, jobs, steps, and workflow files. After this step, you'll be able to read any classic GitHub Actions workflow file.

📋 Before You Start _#

• Practice repository is set up from a previous step.
• No tools or credentials needed for this step.

Quick Refresher _#

A GitHub Actions workflow is a YAML file in .github/workflows/ that tells GitHub:

• when to run (on)
• what to run (jobs)
• how each job executes (steps)

.github/
  workflows/
    hello.yml   ← each workflow file lives here

Annotated example — each comment names the key term (this is a standard Actions workflow, not an agentic workflow):

# Standard GitHub Actions workflow — not an agentic workflow
name: Hello Workflow

on: workflow_dispatch         # trigger: the event that starts this workflow

jobs:
  hello:                      # job: a named group of steps on one machine
    runs-on: ubuntu-latest    # runner: the machine GitHub provisions for this job
    steps:
      - run: echo "Hello from GitHub Actions"   # step: a shell command on the runner

---
runs-on: ubuntu-latest   # also: windows-latest, macos-latest
---

Why This Matters for Agentic Workflows _#

Traditional workflows execute a fixed script path. Agentic workflows still use the same Actions foundation, but introduce AI-driven decision making inside that runtime.

Label a sample workflow _#

The diagram below shows how the five key parts fit together in every workflow file.

Before reading on, label each highlighted part of the workflow below with its type: trigger, job, runner, step, or action.

on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "All checks passed"

Write a label beside each line:

1. on: [push]
2. test: (the job name under jobs:)
3. runs-on: ubuntu-latest
4. uses: actions/checkout@v4
5. run: echo "All checks passed"

Try it: Explore a real workflow _#

Open a real workflow file and find the three core building blocks — no terminal or credentials required, just your browser.

1. Open any public repository on GitHub (for example, the gh-aw-workshop repository).
2. Click the Actions tab.
3. Click any workflow in the left sidebar.
4. Click View workflow file (top right of the run list).
5. In the YAML, find and note:
   • The on: trigger — what event starts this workflow?
   • One jobs: entry — what is the job named?
   • One steps item — what command does it run?

✅ Checkpoint _#

• You can identify on, jobs, and steps in a workflow file
• You labeled all five parts of the sample workflow above (trigger, job, runner, action, step)
• You know workflows live in .github/workflows/
• You explored a real workflow and found its trigger, a job name, and a step command
• You are ready to continue to Step 5, or skip ahead to Step 6 if you already know this material

What Are Agentic Workflows?

Already familiar with both GitHub Actions and AI agent execution environments?

Before skipping, confirm you already know both of these:

• You can describe what an Actions workflow trigger does
• You have worked with AI agent execution environments in a production or CI/CD context

If both apply, Skip to Install gh-aw.

📋 Before You Start _#

• You've read What Are GitHub Actions?

An Agentic Workflow is a plain-English task brief that an AI agent executes inside GitHub Actions. You write what you want — "summarize open issues and post a daily digest" — and the agent reads your repo, calls tools, and posts the output automatically.

Think of it like a scheduled digest: every morning it reads your inbox and sends you a summary — no keyboard required. The agent always runs in a sandbox and posts results through guardrailed safe outputs. You will explore security in How Agentic Workflows Stay Safe.

Three key terms _#

The diagram below shows how each term plays a role when the workflow runs.

For a full glossary, see Side Quest: Agentic Workflows Deep Dive.

The two-file structure _#

Before studying the diagram, write your prediction: what two files are involved, and which one does GitHub Actions actually run?

• .md source file — contains YAML frontmatter (trigger, permissions, runner) and your plain-English task brief. You author and edit this file.
• .lock.yml compiled file — gh aw compile generates it from the .md. GitHub Actions runs this file, not the .md. Never edit it by hand.

Activity 1 — identify the parts: Open any .lock.yml file in your repo and find the on: key. That is the compiled trigger that came from your frontmatter.

# Example: open .github/workflows/my-workflow.lock.yml
# Find the "on:" key — that is your compiled trigger.

Now check your prediction: did you name both files and identify which one Actions runs (.lock.yml)?

Activity 2 — agentic or standard? _#

The diagram below shows how the same schedule trigger leads to two very different outcomes — one driven by static YAML, the other by an AI agent with built-in safety guardrails.

Read each task and decide before revealing the answer.

Task A: Run lint and unit tests on every pull request, fail if any check exits non-zero.

Task B: Each morning, read all open issues, decide which look most urgent, and post a short triage summary.

Activity 3 — write a task brief _#

Write a one- or two-sentence task brief for this goal before revealing the example:

Post a daily issue digest that summarizes newly opened issues and flags anything urgent.

Write your brief here before revealing the example.

Check your brief against these three criteria:

• Does it include a time window (for example, "last 24 hours")?
• Does it specify the output format (single digest comment)?
• Does it define at least one priority signal (for example, blockers)?

If any answer is no, revise your brief before continuing.

✅ Checkpoint _#

• You can describe what an agentic workflow is in one sentence
• You can explain one difference between an agentic and a standard Actions workflow
• You know the three key terms: trigger, task brief, safe outputs
• You know that gh aw compile generates .lock.yml from the .md source
• You identified the on: key in a compiled .lock.yml file
• Your task brief includes a time window, output format, and priority signal

How Agentic Workflows Stay Safe

📋 Before You Start _#

• You've read What Are Agentic Workflows?

Letting an AI agent act on your repository on a schedule only works if it can't do damage. Agentic workflows enforce two trust boundaries so you can run agents in automation with confidence.

Safe by design: sandbox + guardrailed outputs _#

• A sandbox around the agent. The agent runs isolated inside the Agent Workflow Firewall, with read-only access to your repo and network egress limited to the domains you allow. Even if a prompt injection or a compromised tool tries to reach out or exfiltrate data, the firewall blocks anything outside the allowlist.
• A guardrailed safe-output system for writes. The agent never holds write permissions. Instead, it emits a structured request — "create this issue," "post this comment" — and a separate, permission-scoped job validates and executes it, applying per-operation limits (max counts, label and title constraints, allowed repos). That separation gives you least privilege, defense against prompt injection, and a full audit trail of every action.

The security jobs in the run log above map to these boundaries: activation checks the agent is authorized to run, the agent runs sandboxed behind the firewall, detection scans for malicious behavior, and safe-outputs applies changes within the guardrails.

The diagram below shows how the two layers work together in a single workflow run.

Try it: sandbox or safe-output? _#

For each scenario below, decide whether the sandbox or the safe-output system is the primary defence. Make your decision before revealing the answer.

Scenario A: A prompt injected into an issue comment instructs the agent to push to a protected branch.

• I've made my decision for Scenario A

Scenario B: A page the agent fetches during a run tries to send your repository secrets to an external server.

• I've made my decision for Scenario B

✅ Checkpoint _#

• I can describe what the sandbox does and why it matters for automation safety
• I can explain how the safe-output system prevents the agent from writing to the repo directly
• I can identify whether the sandbox or the safe-output system is the primary defence for a given scenario
• I can explain how the two-layer model makes agentic workflows safe to run on a schedule

Practice: Recognize Agentic Workflows

📋 Before You Start _#

• You've read What Are Agentic Workflows?

These exercises help you apply what you just learned — deciding when to use an agentic workflow and drafting your first task brief.

Try it: agentic or standard? _#

For each task below, decide whether it calls for an agentic workflow or a standard Actions workflow, then reveal the answer.

Task A: Run lint and unit tests on every pull request, fail if any check exits non-zero.

• I've made my decision for Task A

Task B: Each morning, read all open issues, decide which ones look most urgent, and post a short triage summary.

• I've made my decision for Task B

Try it: write a one-sentence task brief _#

Pick any routine task you do today that involves reading some data and writing a summary — a daily standup note, a weekly inbox digest, or a triage of support tickets. Write a one-sentence task brief for an agent to do it automatically.

Your brief should answer all three of these: what data should the agent read (data source), what should it post when it's done (output format), and when or how often should it run (cadence)?

Example:

Each Monday morning, read all pull requests opened in the past week,
identify the three with the most review comments, and post a summary
as an issue with the title "Weekly PR Digest".

• I've drafted a task brief for a real routine task
• My brief specifies what data the agent should read (data source)
• My brief specifies what the agent should post when done (output format)
• My brief specifies when or how often the agent should run (cadence)

✅ Checkpoint _#

• I can decide whether a task calls for an agentic or a standard Actions workflow
• I have drafted a task brief that covers all three criteria: data source, output format, and cadence
• I can describe the three parts of an agentic workflow: trigger → agent → safe output

Install the gh-aw CLI Extension

gh-aw is the CLI extension that compiles your agentic workflow Markdown files and triggers runs from your terminal.

🎯 What You'll Do _#

You'll verify the gh CLI is authenticated, install the gh-aw extension, and run one quick diagnostic to confirm your Codespace terminal is ready for agentic workflow setup.

📋 Before You Start _#

• You've completed What Are Agentic Workflows?
• You have a Codespace terminal open (from Set Up a Codespace)

Run this to confirm gh is authenticated before continuing:

gh auth status

Expected output: Logged in to github.com as <your-username>. If you see an error, return to Verify your Codespace is ready.

Install from terminal _#

Check whether gh-aw is already installed, then install or update accordingly:

gh aw --version

• Version shown? Update the extension: gh extension upgrade github/gh-aw
• Command not found? Install using the install script:

curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash
gh aw --version

You should see output like gh-aw version 0.81.6.

Need more help? See Side Quest: Install gh-aw Troubleshooting.

Run a quick diagnostic _#

gh aw doctor

This verifies your GitHub CLI authentication using the same setup checks gh-aw expects before later authoring and compile steps.

Expected result: a success message confirming GitHub CLI authentication. If it fails, use Side Quest: Install gh-aw Troubleshooting, then rerun gh aw doctor.

Initialize agentic workflow skills _#

Before you author your first workflow, initialize and push the generated skill files:

gh aw init
git add .
git commit -m "Initialize agentic workflow skills"
git push

This creates several files needed for agentic workflow authoring: .github/skills/agentic-workflows/SKILL.md, .github/skills/agentic-workflow-designer/SKILL.md, .github/agents/agentic-workflows.md, .github/mcp.json, .github/workflows/copilot-setup-steps.yml, and .vscode/settings.json.

🏃 Try It _#

Run gh aw --help and scan the list of sub-commands.

Which one sub-command do you expect to use in Step 7 when you create and run your first workflow?

Want to understand how Copilot authenticates with your workflow? ➡️ Side Quest: Configure GitHub Copilot for Agentic Workflows

Write Your First Agentic Workflow

Writing your first workflow is the moment theory becomes practice — let's make something real.

🎯 What You'll Do _#

You'll use Copilot to create .github/workflows/daily-report-status.md — a scheduled workflow that also supports manual dispatch. You'll configure it with permissions, safe-outputs, and a task brief, then compile it to produce daily-report-status.lock.yml, the file GitHub Actions runs.

📋 Before You Start _#

• Completed Install the gh-aw CLI Extension
• The gh aw command works in your terminal
• You already ran gh aw init and pushed .github/skills/agentic-workflows/

Verify Copilot access before you begin.

1. In the terminal that is already open in your Codespace, run:

gh copilot

1. In Copilot CLI, send this prompt:

/agentic-workflows what trigger does a scheduled workflow use?

Confirm you receive a reply. Any response means Copilot CLI and the agentic-workflows skill are accessible.

• I opened Copilot CLI in the terminal and received a reply to the test prompt

Create your first workflow _#

In your AI agent, run this prompt:

/agentic-workflows Create a daily-report-status workflow with:
- name: Daily Report Status
- triggers: daily schedule and workflow_dispatch
- permissions: contents read, issues read, copilot-requests write
- safe-outputs: create-issue
- task brief: "Generate an activity report in a new issue."
Compile it after creating it.

Review the agent's edit, then continue. Prefer this path over hand-editing each line.

What the agent created — the generated file should look roughly like this:

---
name: Daily Report Status
on:
  schedule: daily             # compiled to a daily GitHub Actions cron schedule
  workflow_dispatch: {}       # also allows manual runs
permissions:
  contents: read
  issues: read
  copilot-requests: write     # required to call the AI model
safe-outputs:
  create-issue:               # the only write action the agent may perform
---

Generate an activity report for this repository and post it as a new issue.

The frontmatter tells GitHub Actions when to run, what permissions the agent has, and which write action it may use (create-issue). The task brief below the second --- is what the AI agent reads and acts on.

If you hit a compile error, use Side Quest: Using gh aw compile to Catch Errors Early.

Validate, then commit and push _#

Run:

gh aw compile

Optional while editing: gh aw compile --watch.

Then commit and push:

git add .
git commit -m "Add daily-report-status agentic workflow"
git push

For follow-up edits, keep using an agent with the agentic-workflows skill and avoid manual workflow editing unless you are debugging a specific line-level issue.

✅ Checkpoint _#

• Copilot access was confirmed in Copilot CLI before starting (test prompt received a reply)
• .github/workflows/daily-report-status.md exists and contains an on: schedule: trigger in the frontmatter
• The file includes permissions with copilot-requests: write
• gh aw compile exits with no errors and produces daily-report-status.lock.yml
• Both daily-report-status.md and daily-report-status.lock.yml are committed and pushed to main
• The workflow appears in the Actions tab of your repository under "Daily Report Status"
• You are ready to choose the workflow's billing and authentication method

Confirm Model Access

📋 Before You Start _#

This step has two entry points:

• Arriving from step 07 (error recovery): Workflow files do not need to exist yet — fix model access first, then return to Write Your First Agentic Workflow.
• Arriving as the next step after step 07 (normal flow): daily-report-status.md and daily-report-status.lock.yml are committed to your practice repository.

🎯 What You'll Do _#

You'll run a one-sentence test prompt, confirm Copilot is reachable, choose your billing path, and configure the workflow before continuing to Step 8.

Verify model access _#

1. In the terminal already open in your Codespace, run:

gh copilot

1. Send this prompt:

/agentic-workflows what trigger does a scheduled workflow use?

1. Any reply confirms the model and skill are accessible. Continue to Choose a billing path.

If you arrived from the step 07 access check and the test prompt succeeded, return to Write Your First Agentic Workflow now.

Choose a billing path _#

Follow the full setup steps in Side Quest: Copilot Billing Paths, then return here once your workflow file and lock file are committed.

✅ Checkpoint _#

• I sent the test prompt in Copilot CLI and received a reply
• I confirmed no access errors appeared
• I chose a billing path and completed all configuration steps
• My source file and compiled lock file reflect the chosen method
• Both files are committed to main
• I am ready for Run and Watch Your Workflow

Run and Watch Your Workflow

Watching an agent work in real time makes the workflow feel concrete.

🎯 What You'll Do _#

You'll trigger the daily-report-status workflow from Step 7, watch it start in the Actions tab, and confirm it finishes successfully.

📋 Before You Start _#

• Completed Confirm Model Access
• daily-report-status.md and daily-report-status.lock.yml are committed to .github/workflows/ on main
• Your practice repository has at least one open issue (create one in the Issues tab if not)

Pre-flight check _#

A stale or missing lock file is the leading cause of model-access-not-configured failures at this step. Run these checks before triggering the workflow — each takes less than a minute.

Lock file is present and current. Open .github/workflows/ in your repository on GitHub and confirm both files are there:

• daily-report-status.md (source)
• daily-report-status.lock.yml (compiled lock file)

If either file is missing, return to Step 7 to complete the workflow creation steps. If the lock file is present but you are unsure it is current, recompile and push before continuing:

gh aw compile
git add .
git commit -m "chore: sync lock file" && git push

Billing configuration matches the lock file. Open daily-report-status.lock.yml (or daily-report-status.md) and confirm the permissions: block matches the billing path you chose in Step 7d:

Any mismatch means returning to Confirm Model Access to fix the configuration and recompile.

Run the workflow _#

Start from the Actions tab because it works for every learner, even if your terminal token does not have permission to trigger workflows.

If you prefer the terminal, you can use gh aw run daily-report-status as an advanced option. If that command fails in Codespaces, use the Actions tab instead or follow Side Quest: Fix Codespaces actions:write Errors.

Before you click Run _#

• I completed Confirm Model Access and my chosen billing method (organization centralized billing or COPILOT_GITHUB_TOKEN) is active
• Daily Report Status appears in the Actions sidebar
• I have at least one open issue in my practice repository

Trigger the workflow via GitHub Actions UI _#

Open your practice repository in GitHub and click Actions in the top navigation. In the left sidebar, select Daily Report Status.

Click Run workflow, keep the default branch selected, and click the green Run workflow button. If Daily Report Status is missing, refresh the page, confirm both workflow files are on main, and run gh aw compile in your prepared terminal to check for compile errors.

If the run fails immediately with a model-access or authentication error, return to Step 7d and confirm the selected billing method matches the workflow.

Watch the run start _#

The diagram below shows the full lifecycle of a workflow run, from the moment you click Run workflow through to the agent updating your repository.

After a few seconds, a new run appears with a yellow spinning icon. Click the run, then click the job name to open the live log.

You do not need to decode every line yet. For now, just confirm that the workflow is active and the log is updating as the agent plans and uses tools.

Confirm the run finished _#

Wait for the run to turn green with a ✅. Then open the Issues tab in your repository and confirm that the agent updated an issue or created a new one.

✅ Checkpoint _#

• The Daily Report Status workflow appears in the Actions tab
• I triggered a manual run from the GitHub UI
• I opened the live log while the run was active
• The run completed with a green ✅

Interpret Your First Run

Your first run is more useful when you can explain what the agent did and why.

🎯 What You'll Do _#

You'll read the live log from Step 8, find the workflow's output, and learn three quick checks for common run problems.

📋 Before You Start _#

• Completed Run and Watch Your Workflow
• Your Daily Report Status workflow has at least one completed run

Read the live log _#

Open the completed Daily Report Status run from the Actions tab and click the job name. The log usually moves through a simple pattern: the agent thinks, calls a tool, receives a result, and finishes.

🤔 Planning...  Searching for open issues with 👍 reactions
🔧 Tool call:   github.list_issues
📥 Result:      3 issues found
🤔 Thinking...  Issue #4 has the most 👍 reactions
🔧 Tool call:   github.add_comment
✅ Done

The important question is not "Can I read every line?" It is "Can I tell where the agent decided, where it acted, and whether it finished?" Find the first Tool call in your own run and fill in the template below:

First Tool call I saw:         [tool name, e.g. github.list_issues]
What it was trying to do:      [one sentence description]

Check the output _#

After the run finishes, scroll to the Summary section on the run page. This gives you the short version of what the agent believes it did, including the safe-output action it used.

Then verify the real output in your repository. For Daily Report Status, that usually means opening the issue the agent touched and confirming the comment or new issue is actually there. The GitHub change is the ground truth behind the safe-output record.

Check common error patterns first _#

If your run does not look right, work through these three checks in order before changing anything in the workflow.

• The workflow never appears in Actions — confirm the workflow file is committed on main, then refresh. If you use the terminal path, run gh aw compile to catch compile errors.
• The log shows lots of thinking but no useful action — your instructions may be too vague. Keep the run open, then refine the workflow body in a later step.
• The run finishes but nothing changed in GitHub — make sure your repository has an open issue and that the workflow had permission to write.

Knowing what a failed run looks like helps you spot permission issues at a glance, before you spend time re-reading the brief:

🤔 Planning...  Searching for open issues
🔧 Tool call:   github.list_issues
📥 Error:       403 Forbidden — insufficient permissions
❌ Failed

If these checks do not resolve the issue, the Side Quest: Diagnosing Common Agent Output Patterns covers additional cases.

Reflect _#

Before you mark the checkpoint, take two minutes to apply what you just read to your own run.

Practice prompt 1 — trace the decision: Find the first Tool call in your run log and answer: what question was the agent trying to answer at that moment, and what information did it get back?

Practice prompt 2 — judge the outcome: Compare the run summary to the actual GitHub change (the comment or issue). Did the agent do what you expected? Write one sentence saying what matched and, if anything, what was different.

Put your answers in a scratch file, your editor, or wherever you keep notes. You will refer back to this comparison when you refine the workflow in the next step.

✅ Checkpoint _#

• I opened the run summary and found the safe-output note
• I verified the real GitHub output that the workflow created
• I traced the first tool call and noted what the agent was trying to do
• I compared the run summary to the actual GitHub change and noted the result
• I know the first check to make if a run is missing, confused, or finished without writing anything
• I can identify whether a run failed due to a permission error, a vague brief, or a missing output

Refine, Test, and Improve Your Workflow

The fastest path to a better workflow is a tight loop: describe what you want, review the diff, test, and compare the result.

🎯 What You'll Do _#

You'll use the agentic-workflows Copilot skill — installed in your practice repository during Step 7 — to edit, debug, and optimize daily-report-status.md, then trigger a fresh run and compare the output against the previous one.

By the end of this step, your workflow will produce more useful output, and you'll have a repeatable iteration loop you can use any time the workflow output is vague, incorrect, or missing something important.

📋 Before You Start _#

• Completed Interpret Your First Run
• Your daily-report-status workflow has at least one completed run
• .github/skills/agentic-workflows/ exists in your practice repository (created during Step 7)

What is the agentic-workflows skill? _#

The agentic-workflows skill is a Copilot skill installed in your practice repository. It acts as a dispatcher: when you describe a workflow task in plain English and mention the skill by name, it routes your request to the right editing, debugging, or optimizing prompt and makes changes directly in your repository.

You invoke it in Copilot CLI in your Codespace terminal:

gh copilot

Then send:

/agentic-workflows [your request here]

The skill recognizes three core task types for day-to-day workflow maintenance:

If you are working locally or in a Codespace without a Copilot session, the terminal path in each section below shows the equivalent manual change.

Start With One Concrete Observation _#

Open the latest run in the Actions tab and look for one thing you want to improve.

Good examples:

• The summary is too generic.
• An important detail is missing.
• The tone feels too stiff.
• The formatting is inconsistent.

Pick only one problem for this round. Small, isolated changes make it much easier to tell what actually improved the result.

Edit: improve the workflow brief _#

After reviewing the run output, you may have noticed the agent's comment was generic. You'll now make the brief more specific so the agent explains why the most-reacted issue matters, not just which one it is.

In your Codespace terminal, run gh copilot and paste:

/agentic-workflows update .github/workflows/daily-report-status.md
so that the agent adds one sentence explaining why resolving the most-reacted issue
would benefit the team. Keep the existing [safe-output](https://github.github.com/gh-aw/reference/safe-outputs/) constraint (at most one comment).

The skill loads the update prompt, makes the targeted change to the Markdown body, recompiles the workflow, and shows you the diff. Review the updated Markdown body and confirm the new instruction is clear and specific before committing.

After identifying the most-reacted issue, write one sentence explaining why resolving it
would benefit the team, based on the issue title and description.

gh aw compile
git add .
git commit -m "feat: add team-benefit sentence to daily-report-status brief"
git push

Debug: investigate unexpected output _#

If your run from Step 8 finished but the output was empty, vague, or missing entirely, use the skill to diagnose the most likely cause and propose a fix.

In your Codespace terminal, run gh copilot, then paste this prompt, replacing the bracketed text with what you actually observed:

/agentic-workflows debug .github/workflows/daily-report-status.md.
The last run [describe the problem — for example: "posted a comment but left the
summary blank" or "finished without posting anything"].
Suggest the most likely cause and propose one change to the workflow brief to fix it.

The skill reads the workflow file, identifies likely causes — such as a vague brief, a missing fallback instruction, or an over-broad safe-output surface — and proposes a targeted, minimal fix.

If no open issues have 👍 reactions, post a comment on the most recently updated
open issue instead.

Optimize: reduce token usage _#

Once the workflow produces correct output, you can reduce how much AI Credit it uses per run. This matters especially for workflows that run on a schedule.

In your Codespace terminal, run gh copilot, then paste:

/agentic-workflows optimize .github/workflows/daily-report-status.md
to reduce token usage. Apply only changes that do not change the workflow's outcome.

The skill applies techniques such as removing redundant instructions, consolidating repeated constraints, and trimming unused safe-output declarations.

Commit Both Workflow Files _#

Commit both the source workflow and the recompiled lock file:

git add .
git commit -m "refine daily-report-status workflow output"
git push

If your workflow uses a different filename, stage that .md file and its matching .lock.yml file instead.

Trigger a Fresh Run and Compare _#

Use workflow_dispatch from the Actions tab to trigger a new run. Then compare the latest result with the previous one.

Ask yourself:

• Did the new run reflect the change you made?
• Is the output more useful than before?
• Did you improve the original problem without creating a new one?

If yes, keep the change. If not, revert the change and try a different adjustment.

If you want a stricter review loop, score each run for accuracy, completeness, and tone before you decide what to change next.

✅ Checkpoint _#

• I identified one specific problem from a real workflow run
• I used the /agentic-workflows skill (or made a manual edit) to address it
• The compiled lock file was updated and committed alongside the workflow source
• Both daily-report-status.md and daily-report-status.lock.yml are committed and pushed
• I compared the new run with the previous run and decided what to change next

What's Next? Keep Exploring

You've built a real, scheduled AI workflow — here's how to keep growing from here.

🎯 What You'll Do _#

Take stock of everything you've learned, then choose a direction for what to build or explore next. This node is a hub: it links to deeper dives, community resources, and ideas for your own projects.

📋 Before You Start _#

• You have a scheduled daily-status workflow running in GitHub Actions from Refine, Test, and Improve Your Workflow.

Steps _#

Celebrate what you've shipped _#

You've gone from zero to a fully automated, AI-powered workflow that:

• Runs on a schedule in GitHub Actions
• Uses gh-aw to call an AI model from a simple YAML file
• Posts a daily summary without any manual intervention

That is a real, production-capable workflow. Nicely done.

Reflect and Plan _#

Answer each question (in your notes or a new GitHub issue in your practice repository), then check the box:

• What was the hardest part of this workshop, and why?
• How would you change your daily-status workflow prompt to get better output?
• What is the next workflow you want to build, and what data source would it need?

Review what you've learned _#

Here's a quick recap of the concepts you've touched. The diagram below shows how all the pieces connect in the workflow you just built.

Go deeper _#

• ➡️ Make Your Workflow Smarter with Conditional Logic — add conditions so your workflow only runs when there is meaningful activity to report.
• ➡️ Connect a Live Data Source to Your Workflow — fetch live repository data and pass it into your AI prompt as workflow context.
• ➡️ Give Your Agent More Tools with MCP — connect the GitHub MCP server so your agent can read live repository data as it runs.
• ➡️ Share and Reuse Your Agentic Workflows — publish your workflow to a catalog so others can install it with one command.
• ➡️ Make Your Workflow Remember Across Runs — add cache-backed memory so your workflow skips items it has already reported on.
• ➡️ Split Complex Workflows with Inline Sub-Agents — use the planner-worker pattern to keep your main prompt lean and reduce token cost.
• ➡️ Make Your Workflows Resilient to Failure — add defensive briefs, timeouts, and fallback outputs so unattended runs stay reliable.
• ➡️ Test Your Prompt Ideas with A/B Experiments — compare prompt variants across runs and let data decide which one to keep.
• ➡️ Run Your Agentic Workflow on a Self-Hosted Runner — target your organisation's runner fleet instead of GitHub-hosted machines (enterprise teams).
• ➡️ Audit and Monitor Your Agentic Workflows — read run artifacts, understand token usage, and build an audit trail for enterprise compliance.
• ➡️ Manage Costs and AI Credit Budgets — measure AIC consumption, set spending limits, and keep your workflows within budget (enterprise teams).

✅ Checkpoint _#

• Your scheduled workflow has completed at least one successful automated run
• You can describe, in plain English, what agentic workflows are and why they're useful
• You have at least one idea for the next workflow you want to build
• You drafted a two-sentence brief for your next agentic workflow
• You know where to find the gh-aw docs when you need them

You've reached the end of the scheduled-workflow path — but there is one more step on the main track before you head into advanced territory. Come back to explore any of the deeper topics when you're ready.

Build a PR Reviewer with an Agent and Skill

Turn pull request review into a small team: an orchestrator, a focused reviewer, and reusable review guidance.

🎯 What You'll Do _#

You'll use your AI agent and the /agentic-workflows skill to create an event-driven PR reviewer. The workflow will define:

• an inline pr-reviewer agent that inspects one pull request
• an inline pr-review-standards skill that keeps findings evidence-based
• a parent brief that turns the reviewer's findings into one safe pull request review

By the end, you'll have a reviewer that runs when a draft becomes ready, can be rerun with /review, and keeps its review method separate from its orchestration.

📋 Before You Start _#

• You have a working workflow from Refine, Test, and Improve Your Workflow.
• You have pushed the files created by gh aw init, including .github/skills/agentic-workflows/.
• The gh aw command works in your Codespace terminal.

Understand the Agent and Skill Split _#

The parent workflow should coordinate the run, not contain every review rule. It delegates the diff analysis to a focused inline agent. That agent applies an inline skill containing the review method.

The diagram below shows how these three layers connect at runtime, with the safe output performing the only repository write.

The agent can change how it investigates a pull request without changing the stable standards in the skill. You can also improve the skill without making the parent brief longer. The same split makes it straightforward to extend the reviewer to apply labels based on which files changed (see Pattern: Auto-Label PRs by Content) or to post a structured summary that doubles as a release note draft (see Pattern: Generate a PR Summary Comment).

🤔 Predict: Which instruction belongs in the skill: “review pull request 42” or “cite a changed file and line for every finding”? The first is run-specific orchestration; the second is reusable review guidance.

Ask Your Agent to Create the Workflow _#

Open your AI agent in the practice repository and pass this prompt:

/agentic-workflows Create a PR reviewer workflow at .github/workflows/pr-reviewer.md with an inline pr-reviewer agent and pr-review-standards skill, triggering on pull_request ready_for_review and the /review slash command.

Review the agent's diff before accepting it. The source should contain one parent brief plus both inline blocks near the bottom of the file.

Inspect the Generated Structure _#

The workflow frontmatter should follow this shape:

---
on:
  pull_request:
    types: [ready_for_review]
  slash_command:
    strategy: centralized
    name: review
    events: [pull_request_comment, pull_request_review_comment]
permissions:
  contents: read
  pull-requests: read
  copilot-requests: write
tools:
  github:
    mode: gh-proxy
    toolsets: [pull_requests, repos]
safe-outputs:
  submit-pull-request-review:
    max: 1
    allowed-events: [COMMENT, REQUEST_CHANGES]
---

Notice that the agent job has no repository or pull request write permission. copilot-requests: write only authenticates Copilot. The submit-pull-request-review safe output performs the controlled repository write after the agent finishes. APPROVE is intentionally absent because the default GitHub Actions token cannot approve pull requests.

Near the bottom, look for the two reusable blocks:

## agent: `pr-reviewer`
---
description: Reviews one pull request for actionable problems
model: small
---

Inspect the pull request diff. Discover the relevant skill under the available
skills directories and apply its review guidance. Return prioritized findings
with evidence for the parent agent.

## skill: `pr-review-standards`
---
description: Produces evidence-based pull request review findings
---

Report only actionable problems introduced by the changed lines. For every
finding, cite the changed file and line, explain the impact, and suggest a
specific next step. Omit style-only and speculative feedback.

The exact wording may differ. Confirm that the responsibilities stay separated: the parent coordinates, the agent investigates, and the skill defines review quality. If your team works from a shared checklist rather than open-ended criteria, Pattern: PR Review Checklist shows how to restructure the skill around that format.

Compile and Push _#

In your Codespace terminal, run:

gh aw compile
git add .
git commit -m "feat: add agent and skill PR reviewer"
git push

Optional while your agent edits: run gh aw compile --watch in a separate terminal for immediate compiler feedback.

Test the Ready-for-Review Trigger _#

1. Create a branch with a small code change that has an obvious, non-security bug.
2. Open a draft pull request against your default branch.
3. Select Ready for review.
4. Open the Actions tab and inspect the PR Reviewer run.
5. Return to the pull request and inspect the submitted review.

In the run log, confirm that the parent calls pr-reviewer and that the reviewer loads the review skill before returning findings.

To test the manual path, add a /review comment to the pull request. After pushing another commit, use /review again instead of moving the pull request back to draft.

If the run completes but the review does not mention the pr-review-standards skill or does not cite changed files and lines, the reviewer likely could not find the skills directory. Use this checklist to recover:

1. Confirm .github/skills/agentic-workflows/ exists and was pushed. Run ls .github/skills/ in your terminal. If the directory is missing, run gh aw init, commit the generated files, and push.
2. If the directory exists but the skill was still not applied, ask the agent to reinforce the instruction:

/agentic-workflows Update .github/workflows/pr-reviewer.md so the pr-reviewer agent explicitly searches for and applies the pr-review-standards skill before returning findings.

1. Compile, commit, and re-trigger /review to confirm the skill is now applied.

Improve One Layer _#

Choose one change and send it through /agentic-workflows:

• Update the skill if the review standard needs to change across every review.
• Update the agent if its investigation or returned evidence needs to change.
• Update the parent brief if review submission or orchestration needs to change.

For example:

/agentic-workflows Update the pr-review-standards skill in .github/workflows/pr-reviewer.md to distinguish blocking findings from non-blocking observations.

Run /review again and compare the new result with the first review. Once you have run a few variations, use the Observe and Reduce Token Costs side quest to measure the AIC impact of each change and identify the highest-value optimizations.

✅ Checkpoint _#

• You created .github/workflows/pr-reviewer.md through your AI agent and /agentic-workflows
• The workflow contains a pr-reviewer inline agent and a pr-review-standards inline skill
• The parent brief calls the reviewer, and the reviewer applies the skill
• The agent job has read-only repository and pull request permissions
• The safe output allows one COMMENT or REQUEST_CHANGES review, but not APPROVE
• gh aw compile completed and both workflow files are committed and pushed
• Marking a draft ready or commenting /review triggered the workflow
• The submitted review cites evidence from the changed lines
• You changed one layer and compared the rerun with the first review

Make Your Workflow Smarter with Conditional Logic

A workflow that always runs is useful — a workflow that only runs when it matters is elegant.

🎯 What You'll Do _#

Add a conditional check to your daily-status workflow so it only posts a summary when there have been recent commits. You'll learn how to use shell commands to gather context, expose that context as step outputs, and wire it into an if: condition that short-circuits the agent job entirely on quiet days.

📋 Before You Start _#

• You have a working daily-status workflow from Build: Daily Repo Status Workflow.
• You understand how to edit and re-run a workflow from Refine, Test, and Improve Your Workflow.

Steps _#

Understand the problem _#

Your daily-status workflow currently runs every weekday regardless of repository activity, which means it can produce empty or near-empty summaries like "No activity to report" on quiet days. Over time these hollow reports erode confidence in the tool because readers learn to ignore them. Conditional logic solves this by inspecting repository state in a deterministic shell step before any AI processing begins, then skipping the agent job entirely when the precondition is not met.

The approach breaks into three parts:

1. Run a shell command to count commits from the last 24 hours and write the result to $GITHUB_OUTPUT.
2. Reference that output using the steps context expression ${{ steps.recent.outputs.commit_count }}.
3. Add a top-level if: key in the workflow frontmatter that skips the agent job when the count evaluates to zero.

Add a commit-count step _#

In your Copilot CLI session in the terminal, paste:

/agentic-workflows update .github/workflows/daily-status.md to add a shell step
that counts commits from the last 24 hours and writes the result to $GITHUB_OUTPUT
as `commit_count`, with step id `recent`.

The skill adds this step to the frontmatter steps: block and recompiles the lock file.

---
steps:
  - name: Count recent commits
    id: recent
    run: |
      COUNT=$(git log --oneline --since="24 hours ago" | wc -l | tr -d ' ')
      echo "commit_count=$COUNT" >> $GITHUB_OUTPUT
---

Here is the step structure the skill will add:

---
steps:
  - name: Count recent commits
    id: recent
    run: |
      COUNT=$(git log --oneline --since="24 hours ago" | wc -l | tr -d ' ')
      echo "commit_count=$COUNT" >> $GITHUB_OUTPUT
---

This shell command uses git log with a --since time filter to list only commits from the last 24 hours, pipes the output through wc -l to count the lines, strips surrounding whitespace with tr -d ' ', and writes the final integer to $GITHUB_OUTPUT — a special GitHub Actions file that shares values between steps using key=value notation. The id: recent field is essential: it creates a named slot in the steps context so the value can be referenced as steps.recent.outputs.commit_count in later steps or in the top-level if: condition.

Add a top-level condition in frontmatter _#

In the same frontmatter block, add a top-level if: key at the same indentation level as on: and steps::

---
if: steps.recent.outputs.commit_count != '0'
---

This condition is embedded into the generated lock file during compilation; at runtime, GitHub Actions evaluates it and skips the agent job entirely whenever commit_count evaluates to '0'. You can also reference the count inside your prompt text to give the model concrete context — for example: "Summarise the last ${{ steps.recent.outputs.commit_count }} commits" anchors the analysis to the actual number of changes rather than leaving the model to guess the scope.

Go further: chain conditions for a weekend skip _#

Now that the commit-count condition is in place, you can extend the workflow to also skip on weekends. This exercise reinforces how to combine multiple conditions in a single if: expression.

Commit and push your conditional logic _#

git add .
git commit -m "feat: skip summary on days with no commits"
git push

✅ Checkpoint _#

• Your workflow has a count recent commits step with id: recent
• Your workflow frontmatter includes if: steps.recent.outputs.commit_count != '0'
• Both .github/workflows/daily-status.md and .github/workflows/daily-status.lock.yml are compiled, committed, and pushed
• You triggered the workflow manually and confirmed the conditional behaviour in the run log
• The workflow still posts a summary on days with commits

Connect a Live Data Source to Your Workflow

Workflows become truly powerful when they act on real, up-to-the-minute data — not just canned prompts.

🎯 What You'll Do _#

You'll extend your daily-status workflow to fetch open issues from your repository using the GitHub CLI, then inject that data into your AI prompt. By the end, your summary will include an overview of outstanding issues alongside the commit activity.

📋 Before You Start _#

• You have installed the gh-aw extension in Install the gh-aw CLI Extension.
• You have a working daily-status workflow from Build: Daily Repo Status Workflow.
• You're comfortable running and iterating on workflows from Refine, Test, and Improve Your Workflow.

Steps _#

Understand the data-flow pattern _#

gh-aw workflows run inside GitHub Actions, so your workflow can fetch live repository data before the AI writes anything. In this step, use shell steps to collect data and a later prompt section to turn that data into a summary.

Think of it as a handoff. First, the workflow gathers facts in a predictable way. Then, the prompt reads those saved results and asks the AI to explain what matters.

Fetch commit history _#

In your Copilot CLI session in the terminal, paste:

/agentic-workflows update .github/workflows/daily-status.md to add two shell steps
that fetch (1) the recent commit log from the last 24 hours with step id `recent`
and (2) all open issues with step id `issues`, and update the AI prompt to inject
those step outputs into the summary.

The skill adds both steps and updates the task brief. Review the diff before committing.

Here is what the first step looks like — the skill will add this for you:

First, fetch the recent commit log:

- name: Fetch recent commits
  id: recent          # step ID — referenced as steps.recent.outputs.…
  run: |
    # Lists commits from the last 24 hours (max 10), format: "<hash> <subject>"
    COMMIT_LOG=$(git log --oneline --since="24 hours ago" --format="%h %s" | head -10)
    # <<EOF writes a multi-line value to $GITHUB_OUTPUT
    echo "commit_log<<EOF" >> $GITHUB_OUTPUT
    echo "$COMMIT_LOG" >> $GITHUB_OUTPUT
    echo "EOF" >> $GITHUB_OUTPUT

🤔 Pause and predict: What will the commit_log output contain if no commits were made in the last 24 hours? Form your prediction now and verify it after you trigger a run.

Fetch open issues _#

Next, add a step to fetch open issues:

- name: Fetch open issues
  id: issues          # step ID — referenced as steps.issues.outputs.…
  run: |
    # Fetch the 10 most recent open issues, formatted as "#42 Fix the bug"
    ISSUE_LIST=$(gh issue list --state open --limit 10 \
      --json number,title \
      --jq '.[] | "#\(.number) \(.title)"')
    # Count all open issues
    ISSUE_COUNT=$(gh issue list --state open --json number --jq 'length')
    echo "open_issues<<EOF" >> $GITHUB_OUTPUT
    echo "$ISSUE_LIST" >> $GITHUB_OUTPUT
    echo "EOF" >> $GITHUB_OUTPUT
    echo "open_issues_count=$ISSUE_COUNT" >> $GITHUB_OUTPUT
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # provided automatically — no setup needed

✏️ Try it: Run gh issue list --state open --json number --jq 'length' in your terminal and note the count. After you trigger a workflow run, check whether the workflow reports the same total.

🤔 Pause and predict: What will the AI receive if the issue list is empty? Will the prompt still produce a useful output?

Inject data into your AI prompt _#

The AI prompt lives in the Markdown body after the frontmatter. Update that section so it uses the step outputs:

---
# … your existing frontmatter with the two new steps …
---

Summarise recent activity in this repository.

Recent commits (last 24 hours):
${{ steps.recent.outputs.commit_log }}

Open issues (${{ steps.issues.outputs.open_issues_count }} total):
${{ steps.issues.outputs.open_issues }}

Write a concise, friendly update — two short paragraphs.
Highlight anything that looks urgent in the issue list.

GitHub resolves the step-output expressions before the AI sees the prompt, so the model receives plain text instead of workflow syntax.

🤔 Pause and predict: If the commit_log output is empty, does the prompt still make sense to the AI? What one-line change would make the instruction more robust?

✏️ Try it: Change "two short paragraphs" to "one bullet list per topic" and re-run. Notice how the output format shifts.

Compile, push, and test _#

The /agentic-workflows skill recompiles the lock file automatically. If you edited the workflow manually, run gh aw compile first, then push:

git add .
git commit -m "feat: inject open issues into daily summary prompt"
git push

Open the Actions tab and verify the new steps appear and the AI summary mentions both commits and issues.

Try other data sources _#

Once you're comfortable with this pattern, the same technique works for:

✅ Checkpoint _#

• Your workflow has a recent-commits step with id: recent
• Your workflow has an open-issues step with id: issues
• Your AI prompt uses both saved outputs
• Both .github/workflows/daily-status.md and .github/workflows/daily-status.lock.yml are compiled, committed, and pushed
• A manual run completes and the summary mentions both commits and open issues
• You can explain how the workflow passes fetched data into the prompt
• You can describe what happens if the recent commit output is empty and how your prompt handles it

Give Your Agent More Tools with MCP

MCP servers turn your agent from a text generator into an active participant that can read, fetch, and act.

🎯 What You'll Do _#

You'll add an MCP (Model Context Protocol) server to your workflow's frontmatter, giving the AI agent access to a new set of tools it can call at runtime. By the end, your daily-status workflow will be able to do more than just generate text — it can interact with live data sources using structured tool calls.

📋 Before You Start _#

• You have installed the gh-aw extension in Install the gh-aw CLI Extension.
• You have a working daily-status workflow from Build: Daily Repo Status Workflow.
• You're comfortable editing the YAML frontmatter section at the top of your workflow file.

Steps _#

Understand what MCP adds _#

MCP (Model Context Protocol) connects external tool servers to the agent so it can call structured operations — like listing issues or fetching commits — and weave the live results into its output. Without MCP, the agent only knows what you wrote in the brief; with MCP, it can go out and look things up itself.

Add an MCP server to your workflow _#

In the terminal that is already open in your Codespace, run:

gh copilot

In Copilot CLI, send this prompt:

/agentic-workflows update .github/workflows/daily-status.md to add a `tools:` block
with `github: mode: gh-proxy, toolsets: [default]` to the frontmatter, and update
the task brief to tell the agent to use GitHub tools to fetch the last 5 commits and
all open issues labelled `bug`, then write a daily summary and post it as a new issue.

The skill adds the tools: block and updates the brief. Review the diff before committing.

Here is the tools: block the skill will add:

---
name: Daily Status Report
on:
  workflow_dispatch: {}
  schedule: daily on weekdays
permissions:
  contents: read
tools:
  github:
    mode: gh-proxy
    toolsets: [default]
---

Reference the tools in your task brief _#

Below the frontmatter, update the task brief to tell the agent it can use the MCP tools:

You have access to GitHub tools via MCP. Use them to:
1. Fetch the last 5 commits on the default branch.
2. List all open issues labelled `bug`.
3. Write a concise daily summary combining both.
Post the summary as a new issue titled "Daily Status — {today's date}".

The agent will read this brief, decide which MCP tool calls to make, and weave the results into its final output — all without you scripting each API call manually.

Push and trigger a run _#

The /agentic-workflows skill recompiles the lock file automatically. Commit both files and push:

git add .
git commit -m "feat: add MCP tools to daily status workflow"
git push

Watch the agent reason _#

Open the run log in Actions. You'll see the agent interleaving tool calls with its reasoning — it fetches data, processes it, then produces the summary. That's the agentic loop in action.

✅ Checkpoint _#

• Your frontmatter has a tools: block with github: mode: gh-proxy
• Your task brief mentions what the agent should do with the tools
• The source and compiled workflow files are committed and pushed
• A manual run completes and the log shows at least one MCP tool call
• The workflow output reflects live data retrieved via MCP, not just static text

Share and Reuse Your Agentic Workflows

Your workflow is worth more than one repository — learn how to turn it into a reusable template your whole team can adopt.

🎯 What You'll Do _#

You'll copy your finished workflow file into a shared location so that teammates can add it to their own repositories with a single command. By the end of this step you'll have a reusable workflow template and know how to distribute it.

📋 Before You Start _#

• You have a working agentic workflow (completed Refine, Test, and Improve Your Workflow or any of the build steps).
• You have push access to at least one repository where you want to share the workflow (this can be the same practice repo).

Steps _#

Understand how gh-aw templates work _#

When you run gh aw add, the extension fetches a workflow Markdown file directly from a GitHub repository. Any .md file in a .github/workflows/ folder of a public (or accessible) repo can act as a template.

That means your workflow is already a template — you just need to point people at it.

Choose a sharing destination _#

You have two options:

For this step, you'll use your own practice repository. If you later want to move the template to a dedicated repo, the process is identical.

Verify your workflow file is committed _#

Your workflow lives at .github/workflows/<name>.md in your repository. Make sure the latest version is committed and pushed.

Terminal path — verify with Git _#

git status
git log --oneline -3

If you see uncommitted changes, commit them now before sharing.

Verify on GitHub _#

1. Navigate to your repository on GitHub.
2. Browse to .github/workflows/.
3. Confirm your workflow .md file appears in the file list with your most recent changes.

Share the gh aw add command _#

Once your workflow is pushed, give teammates this one-liner to add it to their own repository:

gh aw add <your-github-username>/<your-repo>/<workflow-name>

For example, if your username is jsmith, your repo is my-workshop, and your workflow file is daily-status.md:

gh aw add jsmith/my-workshop/daily-status

Your teammate runs this inside their repository. gh aw add copies the Markdown file into their .github/workflows/ folder and they can then edit and compile it for their own context.

Document your template _#

Add a short comment at the top of your workflow's Markdown task brief so users know what to customise:

<!-- TEMPLATE: Replace "my-repo" with your repository name.
     Adjust the schedule and permissions to match your needs. -->

This hint saves teammates guesswork when they first open the file.

✅ Checkpoint _#

• Your workflow .md file is committed and pushed to a GitHub repository
• You can construct the gh aw add command for your workflow
• You've added a brief template comment explaining what to customise
• A teammate (or you in a second repo) has successfully imported the template with gh aw add

Build a Research-Driven Next Training Node

Strong workshop content comes from real product signals, not guesses.

🎯 What You'll Do _#

In this step, turn github/gh-aw research into a concrete training plan update: review current gh-aw documentation signals, identify one meaningful learner gap, and draft a workshop node proposal ready to implement. By the end, you have a repeatable method for deciding what to teach next with confidence.

📋 Before You Start _#

• You completed Share and Reuse Your Agentic Workflows.
• You can open workshop/README.md and identify where new nodes belong in the curriculum table.
• You can run gh aw compile for workflow validation from earlier steps.

Steps _#

Review current gh-aw signals _#

Start by collecting the most current signal from the source repository and its docs references:

for url in \
  "https://raw.githubusercontent.com/github/gh-aw/main/LLMs.txt" \
  "https://raw.githubusercontent.com/github/gh-aw/main/llms.txt" \
  "https://github.github.com/gh-aw/llms.txt"; do
  if curl -fsSL "$url" | head -n 40; then
    break
  fi
done

This gives you a compact index of what the gh-aw project currently emphasizes for model and documentation consumption.

Pick one high-value learner gap _#

Read your existing workshop path and ask one practical question: what can a learner do now that they could not do before this new node exists? Keep your answer narrow. Good gaps are concrete, such as "how to validate workflow constraints before opening a PR" or "how to select safe outputs for automation."

Draft a node proposal with clear scope _#

Write a one-paragraph node scope and list the exact artifacts it should change:

• one new workshop/<step>-<slug>.md file
• one curriculum row in workshop/README.md
• optional wording refresh in workshop/00-welcome.md when total step count changes

Capture research metadata in XML comments _#

Add XML comments to preserve reasoning without interrupting learner flow:

<!--
<research-metadata>
  <focus>safe outputs selection</focus>
  <sources>
    <source>https://raw.githubusercontent.com/github/gh-aw/main/LLMs.txt</source>
    <source>https://github.github.com/gh-aw/reference/safe-outputs/</source>
  </sources>
  <rationale>...</rationale>
</research-metadata>
-->

Keep the comment concise and traceable to real sources you used.

Validate before opening a pull request _#

Run markdown lint and compile checks so your proposal is production-ready:

npx --yes markdownlint-cli2 "workshop/**/*.md"
gh aw compile

✅ Checkpoint _#

• You reviewed current gh-aw direction signals from LLMs.txt
• You identified one concrete learner gap for a new training node
• You drafted a bounded node scope tied to specific repository files
• You captured supporting rationale in XML comments
• You ran lint and compile validation before preparing a PR

Make Your Workflow Remember Across Runs

A workflow that forgets everything after each run will repeat itself. Give it memory and it can act only on what's new.

🎯 What You'll Do _#

You'll add persistent memory to your agentic workflow so it can carry state between runs. By the end of this step, your workflow will remember what it has already reported on and skip duplicates — so your team never gets the same alert twice.

📋 Before You Start _#

• You have a working agentic workflow from the build steps (Step 7 or equivalent).
• You are comfortable editing YAML frontmatter from Give Your Agent More Tools with MCP.
• You understand how safe-outputs controls write access (see Side Quest: Frontmatter Deep Dive — Part B if you need a refresher).

Why Memory Matters _#

Every workflow run you have built so far starts with a blank slate. That is fine for a daily summary, but it causes problems the moment you want to:

• Deduplicate alerts — alert only on new open issues, not the same ones every morning.
• Compare against a baseline — "did the number of failing tests increase since yesterday?"
• Scan incrementally — skip pull requests you have already reviewed.

This step uses cache-memory; see Side Quest: Choosing Between Cache Memory and Repo Memory for a full comparison.

Steps _#

Choose the right memory tool _#

For this deduplication use case, cache-memory is the right choice.

Add cache-memory to your frontmatter _#

In your Codespace terminal, run gh copilot and send this prompt:

/agentic-workflows update .github/workflows/daily-status.md to add `cache-memory`
under the `tools:` key in the frontmatter, with key `daily-status-seen-issues` and
ttl `7d`, and update the task brief to read and write that memory slot for deduplication.

The skill adds the frontmatter block and updates the brief. Review the diff before committing.

Here is the frontmatter structure the skill will use:

---
name: Daily Status Report
on:
  schedule: daily
  workflow_dispatch: {}
permissions:
  contents: read
  issues: write
tools:
  cache-memory:
    key: daily-status-seen-issues
    ttl: 7d
---

What each field does:

Update your task brief to use the memory _#

Below the frontmatter, tell the agent how to use its memory. The agent reads and writes the memory slot by name:

You monitor this repository for newly opened issues and post a daily digest.

Use your `daily-status-seen-issues` memory to track which issue numbers you
have already reported on. On each run:

1. Fetch all currently open issues.
2. Filter out any issue numbers that appear in your memory.
3. If there are new issues, post a comment on the tracking issue listing only
   the new ones.
4. Add the new issue numbers to your memory so you skip them next time.
5. If there are no new issues, post nothing.

Compile, validate, and push _#

The /agentic-workflows skill recompiles the lock file automatically. If you edited manually, run gh aw compile first to confirm the memory block is valid.

Common mistakes include putting cache-memory: at the top level instead of nesting it under tools:, and omitting the key: field for cache-memory.

Push your workflow update:

git add .
git commit -m "feat: add cache-memory deduplication to daily-status"
git push

1. Trigger a manual run in Actions → Daily Status Report → Run workflow.
2. Open the run log and confirm it contains cache-memory: loaded 0 items. This confirms the cache starts empty and initializes correctly.

Trigger a second run and confirm memory reuse _#

1. Trigger the workflow a second time with no new issues.
2. Open the second run log and find cache-memory: loaded N items.
3. Confirm N matches the number of issues processed in the first run.

Test deduplication with a new issue _#

1. Open a new issue in your practice repository.
2. Trigger the workflow again.
3. Confirm the run reports only the new issue.

✅ Checkpoint _#

• Your workflow frontmatter has cache-memory: nested under tools:
• Your task brief explicitly tells the agent to read and write the named memory slot
• The compiled lock file was updated and committed alongside the workflow source
• The first manual run log includes cache-memory: loaded 0 items
• The second run log includes cache-memory: loaded N items, and N matches the number of items from the first run
• After opening a new issue and running again, only the new issue is reported

Split Complex Workflows with [Inline Sub-Agents](https://github.github.com/gh-aw/reference/inline-sub-agents/)

One workflow file, multiple specialised agents — each doing exactly one thing, at the right cost.

🎯 What You'll Do _#

You'll add a sub-agent to your daily-status workflow so the parent agent can stay focused on planning and final writing while a focused sub-agent handles one repeated task. By the end of this step, your workflow will be easier to scale without turning the whole prompt into one long, repetitive brief.

📋 Before You Start _#

• You have a working agentic workflow from the build steps (Step 7 or equivalent).
• You understand YAML frontmatter from Write Your First Agentic Workflow.
• You know how to compile a workflow from Side Quest: Using gh aw compile to Catch Errors Early.

Understand the parent agent and sub-agent split _#

When your workflow repeats the same small job for many items, keep the parent agent focused on the overall plan and final output. Move the repeated item-by-item work into a sub-agent.

A sub-agent is just a helper you define inside the same workflow file. In this step, you only need one syntax rule: start the helper with a level-2 heading that begins with ## agent: and a backtick-wrapped name. Put the helper brief under that heading. If you want, add a short frontmatter block with fields such as description or model. Then call that helper by name from the parent workflow brief.

🤔 Predict: Look at your current workflow. Which instruction repeats once per issue, pull request, or file? Keep that answer in mind for the next section.

[!TIP] Want the full rules for names, frontmatter, model aliases, and block placement? See the existing Side Quest: Sub-Agent Syntax Reference. Stay on this page if you only want the main path.

Apply the pattern to your workflow _#

Pick one repeated task _#

Open your workflow file and choose one bounded task that repeats for each item, such as summarizing one issue or classifying one pull request.

Action: Before you edit, choose these two things:

• the sub-agent name you want to use
• the one-sentence job that sub-agent should do

Add one sub-agent block _#

In your AI agent, run this prompt:

/agentic-workflows update .github/workflows/daily-status.md to add an inline
sub-agent named `issue-summarizer` that reads one GitHub issue and returns a
one-sentence summary. Use model: small. Also update the parent brief to call
this sub-agent once per open issue and compile the summaries into a numbered list.

The skill appends the sub-agent block at the bottom of the file and updates the parent brief. Review the diff before committing.

Here is the sub-agent syntax the skill will add:

## agent: `issue-summarizer`
---
description: Summarizes a single open issue in one sentence
model: small
---

Read the title and body of one GitHub issue. Return exactly one sentence
that explains what the issue is asking for and its current status.

Keep the sub-agent brief narrow. If it processes one item at a time and returns a single result, it belongs here.

For each issue, use the `issue-summarizer` agent to produce a one-sentence summary.

Verify the diff and commit _#

The skill edits both the sub-agent block and the parent brief in one step. Review the diff, then commit:

git add .
git commit -m "feat: add issue-summarizer sub-agent to daily-status"
git push

Run and verify _#

Trigger a manual run. In the Actions log, confirm the parent agent calls your sub-agent and then uses the sub-agent result in the final summary.

✅ Checkpoint _#

• You identified one repeated task in your workflow that fits a sub-agent
• You wrote a sub-agent name and one-sentence job before editing the file
• Your workflow file now includes at least one ## agent: \name`` block
• You updated the main brief to call the sub-agent by name
• The compiled lock file was updated and committed alongside the workflow source
• A manual run completed and the Actions log showed the sub-agent being called
• The final workflow output used the sub-agent result

Make Your Workflows Resilient to Failure

A workflow that handles errors gracefully is one you can trust to run unattended, week after week.

🎯 What You'll Do _#

Learn the most common ways agentic workflows fail in production and apply three practical techniques — defensive task briefs, timeout settings, and safe-output fallbacks — to keep your workflow useful even when things go wrong.

📋 Before You Start _#

• You have a working scheduled workflow (see Refine, Test, and Improve Your Workflow).
• You're comfortable editing workflow frontmatter and task briefs.

Steps _#

Understand common failure modes _#

Agentic workflows can fail for several reasons:

Recognising these patterns helps you write instructions that stay on track.

The diagram below shows how these failure modes map to the three mitigations covered in this step.

Apply all three changes with the skill _#

In your Copilot CLI session in the terminal, paste:

/agentic-workflows make daily-status.md resilient: add a fallback brief for empty data, set timeout-minutes to 10, and include a fallback message on the safe-output call.

The skill applies all three changes and recompiles the lock file. Review the diff before committing.

gh aw compile
git add .
git commit -m "feat: add timeout and defensive fallback to daily-status"
git push

Write a defensive task brief _#

A defensive task brief tells the agent what to do when data is missing or sparse. Add an explicit fallback instruction in your task description:

If there are no open pull requests or issues to summarise,
write a brief "No activity" report instead of skipping the output step.
Always call the safe output tool — even for empty results.

This prevents the most common failure: the agent silently completes without writing any output.

Set a timeout _#

Long-running tasks can stall a workflow run indefinitely. Add timeout-minutes to your workflow frontmatter to cap the run:

---
name: Daily Status Report
on:
  schedule: daily
  workflow_dispatch: {}
permissions:
  contents: read
  issues: write
timeout-minutes: 10
---

On GitHub Enterprise Server (GHES) and GitHub Enterprise Cloud (GHEC), administrators can set a maximum job timeout at the organisation or enterprise level. When that policy is more restrictive than your timeout-minutes value, the enterprise limit takes precedence and the workflow job will be cancelled at the admin-set threshold. Check with your GitHub administrator before relying on a specific timeout-minutes value in an enterprise environment.

Add a fallback message to safe outputs _#

When your workflow uses a noop or comment safe output, always include a meaningful fallback body. If the agent reaches the output step but has nothing to report, this ensures the run still records a visible result:

If no meaningful changes were found, call noop with the message:
"No changes found in the past 24 hours — workflow ran successfully."

This makes it easy to distinguish a healthy "quiet" run from a silent failure in the Actions run log.

Commit and push your changes _#

The /agentic-workflows skill recompiles the lock file automatically. Commit both files and push:

git add .
git commit -m "feat: add timeout and defensive fallback to daily-status"
git push

Verify your changes _#

After pushing:

1. Trigger a manual run from the Actions tab.
2. Open the run log and confirm the safe output step runs even when the data set is small or empty.
3. Check the run duration — it should complete well within your timeout-minutes limit.

✅ Checkpoint _#

• Your task brief includes an explicit fallback instruction for empty or missing data
• Your workflow frontmatter sets timeout-minutes
• Your safe-output call includes a fallback message for quiet runs
• The compiled lock file was updated and committed alongside the workflow source
• A manual run completes successfully and the safe output step is visible in the log
• You can name at least two common agentic workflow failure modes and how to mitigate them

Test Your Prompt Ideas with [A/B Experiments](https://github.github.com/gh-aw/experimental/experiments/)

Stop guessing which prompt works better — let alternating runs tell you.

🎯 What You'll Do _#

You'll add an A/B experiment using experiments: and compare outcomes across runs.

📋 Before You Start _#

• You have a working agentic workflow from the build steps (Step 7 or equivalent).
• You are comfortable editing YAML frontmatter and task briefs.
• You know how to compile a workflow from Side Quest: Using gh aw compile to Catch Errors Early.
• Need internals? Jump to Understand how the round-robin works.

Add an experiment to your workflow _#

Choose one dimension to test _#

Start with one change to isolate its effect: output length (concise vs detailed). Add third variant later.

Use an agent to add the experiment (recommended) _#

In your AI agent, run this prompt:

Add an A/B experiment to `.github/workflows/daily-status.md`.
Use the `/agentic-workflows` skill.
Set `experiments: { output_style: [concise, detailed] }`.
Add conditional prompt blocks for `concise` and `detailed`.
Run `gh aw compile daily-status` and fix any errors.
Commit both workflow files.

Add the experiment manually (alternative) _#

If you prefer to edit directly, add this to the frontmatter in .github/workflows/daily-status.md:

---
experiments:
  output_style: [concise, detailed]
---

Below the frontmatter, add conditional blocks that swap the prompt instructions based on the active variant:

Summarise the activity in ${{ github.repository }} since yesterday.

{{#if experiments.output_style }}
Write according to the output_style: ${{ experiments.output_style }}.
- concise: maximum 5 bullet points, one sentence each.
- detailed: structured report with sections: open issues, merged pull requests,
  CI status, and a one-paragraph summary at the top.
{{#endif}}

Always call the [safe output](https://github.github.com/gh-aw/reference/safe-outputs/) tool — even if there is no activity.

Compile and commit:

gh aw compile daily-status
git add .
git commit -m "feat: add output_style A/B experiment to daily-status"

Run and inspect the experiment _#

Trigger two manual runs _#

1. Go to Actions → Daily Status Report → Run workflow and click Run workflow.
2. Open the run log once it completes. In the activation job, find the assigned variant (for example, experiment output_style: concise).
3. Check your safe output surface — confirm the output matches the concise variant.
4. Trigger a second manual run. This time the detailed variant should be assigned.
5. Compare the two outputs side by side.

Compare assignment counts from artifacts _#

1. Open your first run, scroll to Artifacts, and download experiment.
2. Open the JSON file and note the counts for concise and detailed.
3. Repeat for your second run and compare the two files.
4. Confirm both variants now have one assignment each.

Add a third variant and predict the order _#

1. Update the frontmatter variants to include a third option:

---
experiments:
  output_style: [concise, detailed, executive]
---

1. Update the task brief so each variant has explicit instructions:

{{#if experiments.output_style }}
Write a report according to the output_style: ${{ experiments.output_style }}.
- concise: Write a maximum of 5 bullet points. Each bullet is one sentence.
- detailed: Write a structured report with sections: open issues, merged pull requests,
  and CI status. Include a one-paragraph summary at the top.
- executive: Write an executive summary with exactly 3 bullets and one "Watch next" line.
{{#endif}}

1. Using your confirmed 1:1 counts for concise and detailed, predict the next three assignments.
2. Run the workflow three times and compare your prediction with activation logs and experiment counts.

Understand how the round-robin works _#

Analyse the results _#

After enough runs (10+ per variant reduces variation), compare usefulness and token cost. When one variant wins, keep it as baseline. Remove the experiments: frontmatter field and recompile.

✅ Checkpoint _#

• Your workflow frontmatter has an experiments: block with at least two variants
• Your task brief uses {{#if experiments.<name> }} blocks to swap instructions (the active variant is available as ${{ experiments.<name> }})
• gh aw compile daily-status passes with no errors
• The first manual run log shows the concise variant was assigned
• The second manual run log shows the detailed variant was assigned
• You can compare experiment artifact counts across runs
• You can predict and verify third-variant assignment order from lowest-count selection with first-in-array tie breaks
• You can explain what you would do once a winning variant is identified

Run Your Agentic Workflow on a Self-Hosted Runner

Enterprise teams often need workflows to run on their own infrastructure — this step shows you exactly how.

🎯 What You'll Do _#

Update your workflow's frontmatter to target a self-hosted runner using a runner label. By the end of this step, your agentic workflow queues on a runner your organisation manages rather than a GitHub-hosted machine.

📋 Before You Start _#

• Your agentic workflow runs successfully (see Refine, Test, and Improve Your Workflow).
• A self-hosted runner is registered and online for your repository or organisation. If you need to set one up first, see Side Quest: Enterprise Setup Considerations.
• You know the label assigned to your runner (for example, self-hosted, ubuntu-self-hosted, or a custom label your admin configured).

Understand runner targeting in frontmatter _#

An agentic workflow's frontmatter is compatible with standard GitHub Actions YAML. The runs-on: field tells Actions which runner to use — it works identically for agentic workflows and classic jobs.

Your current workflow likely targets a GitHub-hosted runner. Look for the runs-on: field in your frontmatter:

---
runs-on: ubuntu-latest
---

The only change needed is the value of runs-on:.

✏️ Exercise: Update your frontmatter _#

Update your workflow's runs-on: field to point at your self-hosted runner.

Open your workflow file _#

Open .github/workflows/daily-status.md (or whichever workflow you want to move).

Open the file in your editor of choice:

code .github/workflows/daily-status.md

Change the runs-on: value _#

Replace ubuntu-latest with your runner's label. Use a list if your runner has multiple required labels:

Single label:

---
runs-on: self-hosted
---

Multiple labels (all must match):

---
runs-on: [self-hosted, linux, x64]
---

The labels must exactly match what your admin registered on the runner. Ask your admin if you are unsure — they can find the labels in the runner's registration settings (Settings → Actions → Runners).

Running in an enterprise environment? See Side Quest: Self-Hosted Runner Infrastructure Deep Dive for guidance on ephemeral and JIT runners, proxy configuration, and network isolation for air-gapped environments.

✏️ Exercise: Compile and commit _#

Recompile after editing the frontmatter, then commit both files:

gh aw compile daily-status

Commit both the .md source and the regenerated .lock.yml:

git add .
git commit -m "chore: target self-hosted runner for daily-status workflow"
git push

✏️ Exercise: Verify the run lands on your runner _#

1. Go to the Actions tab in your repository.
2. Click Run workflow.
3. Open the run and look at the job summary.
4. Confirm the Runner field shows your self-hosted runner name (not GitHub Actions).

✅ Checkpoint _#

• Your workflow's runs-on: value matches the label of your self-hosted runner
• gh aw compile (if used) completed without errors
• daily-status.md and its .lock.yml file are committed and pushed
• A manual workflow run started without an error
• The Actions job summary Runner field shows your self-hosted runner's name, not GitHub Actions
• The workflow run log shows your runner's hostname in the job header
• You can explain why a list of labels ([self-hosted, linux, x64]) narrows runner selection
• You know where to find proxy and ephemeral runner guidance if your environment needs it
• No workflow steps failed due to runner availability or label mismatch

Audit and Monitor Your Agentic Workflows

Knowing what your agent did — and proving it — is what turns a useful automation into a trustworthy one.

🎯 What You'll Do _#

Use gh aw logs and gh aw audit to review the built-in artifacts that every agentic workflow run produces, understand token usage, and debug unexpected behavior. By the end you know where to look when a run behaves unexpectedly or when a compliance review asks what the agent did.

📋 Before You Start _#

• Your workflow runs successfully (see Refine, Test, and Improve Your Workflow).
• gh aw is installed and authenticated (see Install the gh-aw CLI Extension).

Steps _#

Review recent runs with gh aw logs _#

gh aw logs downloads artifacts from your workflow's recent runs and prints a summary table showing duration, token usage, and cost in AI Credits (AIC).

Run it from inside your repository:

gh aw logs <your-workflow-id>

Replace <your-workflow-id> with the basename of your workflow file (for example, daily-status for daily-status.md).

The summary table shows one row per run. Key columns:

To download all artifacts for further inspection, add --artifacts all:

gh aw logs <your-workflow-id> --artifacts all

Downloaded files land in .github/aw/logs/<run-id>/ by default.

Audit a specific run with gh aw audit _#

When you need a deeper look at one run — for debugging or compliance evidence — use gh aw audit with the run ID or URL from the Actions tab (both numeric IDs and full GitHub Actions URLs are accepted):

gh aw audit <run-id>

This downloads all artifacts for that run and generates a concise Markdown report covering run metadata, AIC, and any flagged issues.

To also parse the raw agent and firewall logs into readable Markdown, add --parse:

gh aw audit <run-id> --parse

For a full breakdown of report contents and artifact files, see Side Quest: Audit Reference.

Debug with an agent _#

Once you have an audit report, bring it to your AI agent with the /agentic-workflows skill and describe what puzzled you:

/agentic-workflows Here is my audit report. The agent called github.list_issues
three times and AIC was higher than expected. Help me understand why and
suggest how to reduce it.

<paste report here>

The skill understands agentic workflow frontmatter and safe-output rules. It can suggest a more efficient prompt, validate your changes, or walk you through a fix — all without leaving the chat. Ask the agent to make edits directly so it can run gh aw compile to validate before committing.

Browse artifacts in the GitHub UI _#

Every artifact is also available in the browser without the CLI:

1. Go to the Actions tab in your repository.
2. Click a completed workflow run.
3. Scroll to the Artifacts section and download the archive you need.

Retention policy _#

GitHub retains artifacts for 90 days by default. Ask your GitHub administrator whether a policy overrides this and whether you need to copy artifacts to external storage for longer-term audit requirements.

✅ Checkpoint _#

• You ran gh aw logs <your-workflow-id> and read the AIC summary for your workflow
• You ran gh aw audit <run-id> and reviewed the generated report
• You brought an audit report to your AI agent with the /agentic-workflows skill and got actionable feedback
• You can browse artifacts in the GitHub Actions UI
• You know your organisation's artifact retention policy (or know who to ask)

Manage Costs and AI Credit Budgets

Agentic workflows consume AI Credits (AIC) on every run — learning to measure, predict, and control that spend turns a powerful tool into a sustainable one.

🎯 What You'll Do _#

You'll review your workflow's AI Credit consumption in the GitHub billing dashboard, estimate monthly costs for a scheduled workflow, and apply at least one technique to keep spending within budget.

📋 Before You Start _#

• You have completed Audit and Monitor Your Agentic Workflows.
• You have run your workflow at least once and seen token usage data in gh aw logs output.
• (Enterprise users) Your GitHub administrator has confirmed that Copilot Enterprise billing is enabled for your organisation.

Steps _#

Understand AI Credits _#

Every agentic workflow run uses an AI model to process your task brief and produce output. GitHub bills this inference as AI Credits (AIC).

• One AIC corresponds roughly to 1,000 input tokens processed by the model.
• A typical daily-status workflow run costs between 0.5 and 3 AIC depending on brief length and tool calls.
• You pay for both input and output tokens, but input dominates cost for most briefs.

Check current usage in the billing dashboard _#

1. Open github.com and click your profile picture → Settings.
2. In the left sidebar, click Billing and plans.
3. Scroll to the Copilot section and click Usage.
4. Look for the Agentic Workflows row. It shows AIC consumed this billing cycle.

Estimate monthly cost for a scheduled workflow _#

Use the per-run cost from gh aw logs to project monthly spend.

gh aw logs daily-status --count 5

Look at the AIC column. Average the last five runs, then multiply:

monthly cost = average AIC per run × runs per day × 30

If your workflow averages 1.5 AIC and runs once a day: 1.5 × 1 × 30 = 45 AIC per month. Share this estimate with your GitHub administrator before enabling a high-frequency schedule.

Project costs with gh aw forecast _#

gh aw forecast uses your actual run history and Monte Carlo simulation to project future AIC consumption. Run it for a single workflow to see a P10/P50/P90 probability distribution:

gh aw forecast daily-status

Use the P90 figure as a conservative upper bound when requesting a spending limit from your administrator or setting max-daily-ai-credits.

Reduce token consumption and set guardrails _#

A few techniques keep spend in check:

• Shorten the task brief — fewer input tokens per run.
• Filter data before passing it to the agent — smaller context lowers cost.
• Cache results with persistent memory — skip re-processing unchanged data. See Make Your Workflow Remember Across Runs.
• Reduce run frequency — fewer runs means fewer AIC.

Three frontmatter fields enforce hard limits directly in the workflow file:

• timeout-minutes cancels the entire Actions job if it exceeds the limit. The run fails and you are billed only for tokens consumed before cancellation.
• max-ai-credits caps the AIC a single run may consume, enforced by the AWF firewall. The default when omitted is 1000 AIC. Set to a negative value (e.g. -1) to disable enforcement and token steering.
• max-daily-ai-credits caps the total AIC consumed by this workflow across the last 24 hours for the triggering user. Runs that would exceed the cap are blocked before they start. A system default threshold applies when this field is omitted; set to -1 to disable the guardrail, or provide an explicit integer value to override the default.

---
name: Daily Status Report
on:
  schedule: daily on weekdays
timeout-minutes: 10
max-ai-credits: 1000
max-daily-ai-credits: 2500
---

In this example, each run is capped at 1000 AIC and the 24-hour total is capped at 2500 AIC — roughly two full runs before the daily guardrail engages. Compile after editing:

gh aw compile

✅ Checkpoint _#

• You located your AIC usage for this billing cycle in the GitHub billing dashboard
• You calculated an estimated monthly AIC cost for your scheduled workflow
• You ran gh aw forecast and identified the P50 and P90 projections for your workflow
• You added max-ai-credits and max-daily-ai-credits to your workflow frontmatter
• You added or verified a timeout-minutes value in your workflow frontmatter
• You identified at least one technique to reduce token consumption

Want to choose another branch from the workshop hub? Return to What's Next? Keep Exploring.

Verify Your Workflow Quality with Evals

Add automated YES/NO checks so every run tells you whether your workflow actually met its goal.

🎯 What You'll Do _#

You'll add an evals: block to your workflow, define binary quality questions, run the workflow, and verify that results are recorded in the evals artifact and persisted for historical comparison.

📋 Before You Start _#

• You completed Test Your Prompt Ideas with A/B Experiments.
• You completed Manage Costs and AI Credit Budgets.
• You can run and inspect a workflow from Run and Watch Your Workflow.

Steps _#

Add an evals: block _#

Open .github/workflows/daily-status.md and add binary questions to frontmatter.

---
safe-outputs:
  create-issue:
    title-prefix: "Daily Repository Status"

evals:
  - id: issue_created
    question: Does the agent output confirm that a status issue was created?
  - id: includes_summary
    question: Does the agent output include a summary of repository activity from the last 24 hours?
  - id: no_unapproved_writes
    question: Does the agent output show no writes outside declared safe outputs?
---

Each question should test one observable claim and be answerable from agent output alone.

Compile and run _#

Compile after editing:

gh aw compile daily-status

Trigger a run from the Actions UI (or use gh aw run daily-status if you prefer CLI).

Inspect evaluation results _#

After the run completes:

1. Open the run's Artifacts section.
2. Download the evals artifact.
3. Open evals.jsonl and confirm each question has a YES/NO answer.

Example record:

{"id":"issue_created","question":"Does the agent output confirm that a status issue was created?","answer":"YES","model":"small"}

Use evals to catch regressions _#

When you update your prompt or tools, rerun the workflow and compare answers across runs. A question that flips from YES to NO is a fast signal that quality regressed and needs investigation.

✅ Checkpoint _#

• Your workflow frontmatter includes an evals: block with at least three binary questions
• gh aw compile daily-status succeeds after your eval changes
• You ran the workflow and downloaded the evals artifact
• You verified evals.jsonl contains YES/NO answers for each question
• You can explain how eval answer changes help detect regressions

Orchestrate Multiple Agentic Workflows

Chain your specialist workflows together — one orchestrator reads the situation, the right specialist takes action.

🎯 What You'll Do _#

You'll build an orchestrator workflow that reads repository state, decides which specialist workflow to activate, and dispatches it using the dispatch-workflow safe-output. By the end of this step, you'll have a coordinator that routes work to existing specialists rather than handling everything itself.

📋 Before You Start _#

• You completed Verify Your Workflow Quality with Evals.
• You have at least two working agentic workflows (for example, your daily-status workflow and a PR reviewer from Build Your First Event-Driven Workflow).
• You can compile workflows with gh aw compile from Using gh aw compile to Catch Errors Early.

Understand workflow orchestration _#

When a repository needs different kinds of AI work — status reports, PR reviews, cost audits — you can keep each concern in its own focused workflow. An orchestrator connects them: it reads signals from the repository and dispatches the right specialist.

The key primitive is dispatch-workflow in safe-outputs. It lets your orchestrator trigger another workflow in the same repository and optionally pass inputs to it.

🤔 Predict: Look at your existing workflows. Which one handles the broadest task? Which handles the narrowest? The broadest is a natural orchestration candidate; the narrowest is a natural specialist.

Steps _#

Design your orchestrator _#

Before writing code, decide:

• What signals will the orchestrator read? (open issues count, PR age, recent commit activity, or a combination)
• Which specialist workflows will it activate? (at most one per run keeps behavior predictable)
• What condition routes to each specialist?

A simple decision table helps:

Create the orchestrator workflow _#

In your AI agent, run:

/agentic-workflows create a new workflow named `repo-orchestrator` that reads
open PR count and checks whether a daily-status issue exists today.
If stale open PRs are found, use dispatch-workflow to trigger `pr-reviewer`.
If no status issue exists, use dispatch-workflow to trigger `daily-status`.
Add permissions: contents: read, issues: read, pull-requests: read.
Set safe-outputs: dispatch-workflow with the list of allowed workflows.

---
name: Repository Orchestrator
on:
  schedule: daily on weekdays
permissions:
  contents: read
  issues: read
  pull-requests: read
safe-outputs:
  dispatch-workflow:
    workflows:
      - daily-status
      - pr-reviewer
    max: 1
---

Read the current repository state:
1. Count open pull requests older than 3 days.
2. Check whether a GitHub issue with the title prefix "Daily Repository Status" was created today.

Based on what you find:
- If stale open PRs exist, dispatch the `pr-reviewer` workflow.
- If no status issue exists today, dispatch the `daily-status` workflow.
- If neither condition is true, output a one-line summary and stop.

Dispatch at most one workflow per run.

gh aw compile repo-orchestrator

Review the dispatch-workflow safe-output _#

After the skill or your manual edit creates the file, confirm the frontmatter contains:

safe-outputs:
  dispatch-workflow:
    workflows:
      - daily-status
      - pr-reviewer
    max: 1

The workflows list is an allowlist — your orchestrator can only dispatch workflows named here. The max: 1 cap prevents one run from triggering many specialists at once.

Compile and push _#

gh aw compile repo-orchestrator
git add .
git commit -m "feat: add repo-orchestrator workflow"
git push

Run and verify routing _#

Trigger a manual run from the Actions UI:

1. Open Actions → Repository Orchestrator → Run workflow.
2. After the run completes, open the run log.
3. Confirm the orchestrator identified a condition and dispatched the correct specialist.
4. Open Actions and verify the specialist workflow was triggered as a separate run.

If neither condition matched, the orchestrator should log a one-line summary and exit — confirm that no specialist was dispatched.

Iterate on routing logic _#

Return to your agent and refine the conditions:

/agentic-workflows update repo-orchestrator to also dispatch `daily-status` when
the latest commit is more than 48 hours old and no status issue was created today.

Each iteration follows the same loop: edit the brief, compile, push, run, inspect the dispatch log.

✅ Checkpoint _#

• You identified at least two specialist workflows and one orchestration condition for each
• Your repo-orchestrator.md includes a dispatch-workflow safe-output with an explicit workflows allowlist
• gh aw compile repo-orchestrator succeeds
• A manual run of the orchestrator produced a log showing which condition was evaluated
• You verified the specialist workflow was triggered (or confirmed it was correctly skipped when no condition matched)
• You can explain why max: 1 in the dispatch-workflow block keeps orchestrator behavior predictable

Teach Your Agent Domain Knowledge with Skills

Write your domain conventions once in a SKILL.md, and every workflow that needs them can reuse it.

🎯 What You'll Do _#

You'll write a local SKILL.md that encodes a repeatable domain convention — a naming rule, a review checklist, or a data format — and reference it from a workflow so the agent applies that knowledge without you repeating it in every brief. By the end of this step, you'll know when to let the agent discover skills itself (hint) versus when to paste in only the exact fragment it needs (fusion).

📋 Before You Start _#

• You completed Orchestrate Multiple Agentic Workflows.
• You have at least one working agentic workflow you can edit and recompile.
• You can compile workflows with gh aw compile from Using gh aw compile to Catch Errors Early.

Understand skills _#

A skill is a domain-specific knowledge file — SKILL.md — stored under skills/ or .github/skills/<name>/SKILL.md. Unlike a one-off prompt tweak, a skill is written once and reused across any workflow that needs the same convention: an issue-labeling rule, a code review checklist, a data schema, or a house style guide.

Your repository already has skills in .github/skills/ that power its own tooling. Look at one:

cat .github/skills/agentic-workflows/SKILL.md

Notice the shape: YAML frontmatter with name and description, followed by plain-language guidance the agent reads and applies.

🤔 Predict: Think of one convention you keep re-explaining to your agent across workflows — a commit message format, a labeling rule, a checklist. That's a skill candidate.

Steps _#

Install external skills with the frontmatter skills: key _#

To pull in a skill maintained elsewhere, add the top-level skills: array to your workflow frontmatter. The compiler installs it in the activation job before the agent runs — no manual gh skill install step needed:

skills:
  # Local development path, installed with --from-local
  - .github/skills/my-skill

  # External skill pinned to a commit SHA
  - owner/repo/skills/some-skill@801dca688564c529fa84f247f64472520d9ebe28

External references must be pinned to a full 40-character commit SHA (or an unpinned owner/repo@ ref, which the compiler warns about). Local paths like .github/skills/my-skill are for skills you author and maintain in this repository.

Write a local SKILL.md _#

Pick one narrow convention from your own repository — for example, "how to classify an issue" or "what fields a status report must include." In your AI agent, run:

/agentic-workflows create a skill at .github/skills/issue-triage/SKILL.md that
classifies incoming issues as bug, feature, or question, and lists the three
pieces of information a good bug report must include.

---
name: issue-triage
description: Classify incoming issues and flag missing bug-report details.
---

# Issue Triage

Classify each issue as `bug`, `feature`, or `question` based on its title and body.

For issues classified as `bug`, confirm the body includes:

- Steps to reproduce
- Expected vs. actual behavior
- Environment details (OS, version, or browser)

If any of these are missing, note which ones in your response.

Choose a strategy: hint or fusion _#

Once a skill exists, decide how your workflow prompt should point to it:

Use hint when you want the agent to discover and self-select relevant skills:

If the repository contains `SKILL.md` files under `skills/` or `.github/skills/`,
check which ones are relevant to this task. For each relevant skill, read its
content and apply the guidance it provides.

Use fusion when you know exactly which skill section the agent needs and want to keep the prompt compact — reference only the relevant fragment, never the whole file:

<!-- gh-skill-fusion: .github/skills/issue-triage/SKILL.md#issue-triage -->

Classify this issue as bug, feature, or question. If it is a bug, confirm the
body includes reproduction steps, expected vs. actual behavior, and environment
details.

💡 A third option, inline skills, lets you embed a skill fragment directly in the workflow file under a ## skill: \name`` heading. gh-aw extracts it to the right location at setup time. Use this when the skill is small and specific to a single workflow — you don't need it anywhere else.

Wire the skill into a workflow and validate _#

Add your chosen strategy to a real workflow brief, then compile to confirm the skill installs and the frontmatter is valid:

gh aw compile

Check the compiled .lock.yml for the activation step that installs your skill, and confirm no compile warnings mention an unpinned or missing skill reference.

✅ Checkpoint _#

• You located an existing SKILL.md in this repository and identified its name and description
• You wrote a local SKILL.md encoding one concrete domain convention
• You can explain the difference between the hint and fusion strategies, and when to use each
• You referenced your skill from a workflow (via skills:, a hint instruction, or a fusion comment)
• gh aw compile succeeded with no unpinned-skill warnings

Want to choose another branch from the workshop hub? Return to What's Next? Keep Exploring.

GitHub Agentic Workflows Factory Tour

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 — Part 1: Build Your First Workflow _#

Curriculum — Part 2: Go Deeper _#

Optional Side Quests _#

• 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.
• Agentic Workflows Deep Dive — classification exercises, example agent output, the two-file structure, and concept checks; branches from Step 5.
• Terminal Basics — optional primer that branches from Step 1.
• Set Up Your Local Terminal — optional alternative for experienced terminal users who want to work on their own machine instead of in the recommended Codespace.
• Enterprise Setup Considerations — required reading for GHES users and useful for any managed enterprise environment; common return points include Step 1, Step 2, the Local Terminal side quest, and Step 5.
• Environment Reference — glossary of workshop environments and tool terms with official docs links; branches from Step 1.
• Permission Errors — troubleshooting guide for permission denied errors encountered during terminal-based steps; branches from Step 1.
• Install gh-aw Troubleshooting — optional install troubleshooting reference that branches from Step 6.
• Use gh-aw with the GitHub Copilot Cloud Agent — how to open a terminal inside the Copilot Cloud Agent Codespace so gh-aw CLI commands work; branches from Step 6.
• Install gh-aw in a Local Terminal — optional alternative for learners who completed the local terminal setup side quest and want to continue on their own machine.
• Using gh aw compile to Catch Errors Early — quick reference for gh aw compile, --validate, --watch, and common compile errors; branches from Step 7 or Step 9.
• Fix Codespaces actions:write Errors When Running gh aw run — troubleshooting guide for Codespaces workflow-trigger permission errors with an Actions-tab option and advanced recovery steps; branches from Step 8.
• Diagnosing Common Agent Output Patterns — expanded troubleshooting guide for the five most common log patterns; branches from Step 9.
• Pattern: Long [plan] Chains — how to spot a planning loop and rewrite your workflow brief so the agent starts with an explicit first tool call; branches from Diagnosing Common Agent Output Patterns.
• Pattern: Empty [result] Data — how to diagnose empty tool responses and decide whether the root cause is missing read scope, over-filtering, or truly empty repository data; branches from Diagnosing Common Agent Output Patterns.
• Pattern: Safe-output limit reached — how to interpret blocked writes and choose between increasing allowed outputs or constraining agent behavior; branches from Diagnosing Common Agent Output Patterns.
• Pattern: permission denied — how to map permission failures to the correct control: read access in permissions: and write allowlisting in safe-outputs:; branches from Diagnosing Common Agent Output Patterns.
• Pattern: "Done" but Nothing Written — how to diagnose successful runs that produce no write output and tighten instructions so expected writes happen reliably; branches from Diagnosing Common Agent Output Patterns.
• Debugging Checklist — a repeatable seven-step triage flow to apply whenever a run produces unexpected output; branches from Diagnosing Common Agent Output Patterns.
• Writing a Clear Agent Brief — five-step framework for designing any agentic workflow brief; branches from Step 10.
• 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.
• 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 7.
• Workflow File Structure at a Glance — visual map of the two-file structure (.md + .lock.yml), the frontmatter sections, and the Markdown body; branches from Step 7.
• 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.
• Pattern: Auto-Label PRs by Content — apply labels automatically based on which files changed in a pull request; branches from Step 14b.
• Pattern: Generate a PR Summary Comment — post a structured, changelog-ready summary comment when a pull request opens; branches from Step 14b.
• Pattern: PR Review Checklist — evaluate pull requests against a quality checklist and post a pass/fail table; branches from Step 14b.
• Observe and Reduce Token Costs — hands-on optimization activity for building an AIC baseline, auditing expensive runs, identifying cost drivers, and testing one token-reduction change at a time; branches from Step 14b.
• Fuzzy Schedule Expressions — quick reference for choosing between daily, hourly, weekly, and other fuzzy schedule expressions; branches from Step 9.
• 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 9.
• GitHub Actions Expressions and Contexts — deep dive into ${{ }} syntax, available context objects, output references, and if: conditions; branches from Step 15.
• Chaining Conditions — Run an Agent Only When Security Findings Exist — hands-on exercise for adding a Dependabot alert-count step and chaining it with a branch check so the agent only runs when there are real security findings; branches from Step 15.
• YAML Frontmatter Pitfalls — reference guide for the five most common YAML mistakes; branches from Step 7.
• Write Better AI Task Briefs — five prompt-engineering techniques for getting clearer, more consistent AI output; branches from Step 7.
• Explore and Adapt an Annotated Workflow — annotated daily-status.md walkthrough with hands-on edits to confirm each design decision; branches from Step 7.
• 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.
• Passing Data Between Steps with $GITHUB_OUTPUT — deep-dive into how $GITHUB_OUTPUT works; branches from Step 16.
• 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.
• 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.
• 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.
• Deterministic vs Agentic Data Ops — decision guide for splitting fixed data operations from agentic interpretation in hybrid workflows; branches from Step 16.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• Configure GitHub Copilot for Agentic Workflows — explains organization centralized billing and personal COPILOT_GITHUB_TOKEN billing; branches from Step 7d.
• Method 1 — Copilot Requests Permission — use this when your organization has centralized Copilot billing enabled for GitHub Actions; branches from Configure GitHub Copilot for Agentic Workflows.
• Method 2 — COPILOT_GITHUB_TOKEN Secret — use this for personal billing or when centralized Copilot billing is not enabled; branches from Configure GitHub Copilot for Agentic Workflows.
• Method 2 (UI-only) — COPILOT_GITHUB_TOKEN Secret — complete personal-billing setup using only the GitHub web UI, without terminal commands; branches from Configure GitHub Copilot for Agentic Workflows.
• 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 7.
• 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 7.
• 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.
• Sub-Agent Syntax Reference — name rules, block boundary rules, supported frontmatter fields, and model alias table for inline sub-agents; branches from Step 21.
• Agent Session Phases Explained — full phase reference table, activity feed tips, steering prompts, and advanced agent merge / --watch paths; branches from Step 9.
• 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.
• Self-Hosted Runner Infrastructure Deep Dive — enterprise infrastructure primer covering ephemeral and JIT runners, proxy configuration, and network isolation for air-gapped environments; branches from Step 24.
• 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.

Side Quest: Terminal Basics

Optional: complete this quick primer if you're new to the terminal, then return to Step 1.

📋 Before You Start _#

• A computer running macOS, Windows, or Linux with internet access

How to open a terminal _#

macOS: Press Command ⌘ + Space, type Terminal, and press Enter. You'll see a prompt like yourname@MacBook ~ %.

Windows: Press Win, type Terminal, and press Enter. You'll see a prompt like C:\Users\yourname>.

Linux: Press Ctrl + Alt + T, or right-click the desktop and choose Open Terminal. You'll see a prompt like yourname@machine:~$.

The prompt is a short line of text ending in $, %, or >. When you see it, the terminal is ready for your command. Whatever the terminal prints back is the output.

Practice 1: Confirm your terminal works _#

Type this command and press Enter:

echo "hello, terminal!"

You should see hello, terminal! printed as output. If you do, your terminal is working. ✅

Practice 2: See where you are _#

Your terminal always has a current directory — the folder it is "standing" in. Run:

pwd
ls

• pwd prints your current directory path (for example /Users/alice).
• ls lists the files and folders inside it.

Practice 3: Navigate folders _#

To move into a folder and then back out, run each command one at a time:

cd Documents

cd ..

• cd <folder> moves into that folder.
• cd .. moves back to the parent folder.

Practice 4: Create and remove a folder _#

Create a new folder:

mkdir test-dir

Then step inside it:

cd test-dir

Then step back out and remove it:

cd ..
rm -r test-dir

✅ Checkpoint _#

• You opened a terminal and saw a prompt ($, %, or >)
• You ran echo "hello, terminal!" and saw the message printed
• You ran pwd and ls and saw your current directory and its contents
• You moved into a folder with cd and back out with cd ..
• You created a folder with mkdir and removed it with rm -r

When you're done here, return to What You Need Before We Start.

Side Quest: Environment Reference

Optional: use this quick glossary and visual reference to understand the environments and AI tools used throughout the workshop.

📋 Before You Start _#

You have a terminal open inside your practice repository (see Set Up a Codespace or the optional Local Terminal side quest).

Environment and tool glossary _#

Knowing which name maps to which role helps you follow workshop instructions without stopping to wonder what "the terminal" or "Codespaces" means in context.

✅ Verify your tools are ready _#

Run these commands in your terminal to confirm the required tools are installed and accessible:

gh --version
git --version

If you've already completed Step 6, you can also run:

gh aw --version

Conceptual screenshots _#

Recognizing what each environment looks like on screen helps you orient yourself quickly when workshop instructions say "open a terminal" or "use the Copilot app."

These visuals are simplified mental models, not literal product screenshots. Use them to recognize what each name refers to when it appears in later steps.

Development environments _#

GitHub Codespaces _#

You use Codespaces when you want a ready-to-go development environment in your browser.

Visual Studio Code (VS Code) _#

You use VS Code to browse files, edit workflows, and keep a terminal open beside your work.

Terminal (command line) _#

You use the terminal whenever the workshop asks you to run gh, gh aw, or git commands.

Workshop tools and model options _#

GitHub CLI (gh) _#

You use gh for GitHub-specific terminal tasks like authentication checks, repository shortcuts, and workflow commands.

gh-aw CLI extension _#

You use gh aw to compile agentic workflow files.

GitHub Copilot CLI _#

You use GitHub Copilot CLI when you want AI help inside the terminal.

GitHub Copilot app _#

You use the GitHub Copilot app when you want to start and steer repository sessions, manage coding tasks, and review pull requests from a Copilot workspace.

Claude _#

You may see Claude as one of the AI model options that can read a brief, reason through a task, and produce an output.

OpenAI Codex _#

You may see OpenAI Codex as a coding-focused model option that reads files and suggests edits.

✅ Checkpoint _#

• You ran gh --version in your terminal and it returned a version number
• If you've completed Install the gh-aw CLI Extension, you ran gh aw --version in your terminal and it returned a version number
• You ran git --version in your terminal and it returned a version number
• You can identify each environment and tool name used in the tutorial
• You can match each item to its conceptual screenshot
• You know where to find official docs for each item
• You're ready to continue with setup or return to your current workshop step

When you're done here, return to What You Need Before We Start.

Side Quest: Permission Errors

Optional: read this if you see a permission denied error and need help resolving it.

📋 Before You Start _#

• You have opened a terminal (see Side Quest: Terminal Basics if needed)
• You encountered a permission denied error during setup, or want to know what to do when you do

What is a permission error? _#

When you see permission denied, your user account does not have the rights to run that command as written. This is a security feature — it prevents accidental changes to system files.

How to fix it _#

macOS and Linux _#

Re-run the command with sudo in front:

sudo <your-command>

You'll be prompted for your password. sudo stands for "superuser do" and temporarily grants elevated rights for that one command.

Windows _#

Right-click Windows Terminal or PowerShell and choose Run as administrator, then retry the command.

Practice: Observe and fix a permission error _#

Run this command to deliberately trigger a permission denied message.

macOS / Linux:

cat /etc/sudoers

You should see output like cat: /etc/sudoers: Permission denied. Note the exact file path in the message.

Now re-run it with sudo and confirm the error disappears:

sudo cat /etc/sudoers

Windows: Open a standard (non-admin) PowerShell and run:

Get-Content "$env:SystemRoot\System32\drivers\etc\hosts"

Then open an administrator PowerShell and run the same command — it should succeed.

✅ Checkpoint _#

• You ran the practice command and saw permission denied (or an equivalent access-denied message) in your terminal output
• You identified the exact file path shown in the error message
• You re-ran the command with elevated rights (sudo or Run as administrator) and confirmed it completed without an error
• You can explain in one sentence why your account lacked access — write it as a comment on your practice repo issue

When you're done here, return to Side Quest: Terminal Basics.

Side Quest: Set Up Your Local Terminal

Optional: use your own machine instead of the recommended Codespace, then rejoin the core workshop.

🧪 5-question terminal self-assessment _#

Check each statement:

• I have opened a terminal before.
• I can tell which folder I am in and change folders in a terminal.
• I can copy, paste, and run multi-line commands.
• I know how to read command output and spot errors.
• I feel comfortable troubleshooting local install or proxy issues.

If any answer is No, switch to Set Up a Codespace for a faster setup with no local installs.

Working locally means you'll use the tools and shell you already know — let's get them ready in a few quick steps.

🎯 What You'll Do _#

You'll install Git and the gh CLI on your own machine and authenticate with GitHub. By the end you'll be ready to create your practice repository and continue to the core workshop steps.

📋 Before You Start _#

• You've completed What You Need Before We Start
• You have a free GitHub account and are signed in
• You have a terminal application open (Terminal on macOS, Windows Terminal or Git Bash on Windows, any terminal on Linux)

Steps _#

Verify Git _#

git --version

What success looks like: a line like git version 2.x.x.

You should see git version 2.x.x or higher. If you see an error, download Git from git-scm.com and re-run the check.

Install the GitHub CLI _#

GitHub CLI is GitHub's official command-line tool, and you run it with the gh command. Check whether it's already installed:

gh --version

What success looks like: version details for gh are printed.

If the command works, continue to the authentication section. If it does not, run the quick install command for macOS, Windows, or Linux.

macOS quick install _#

brew install gh

Windows quick install _#

winget install --id GitHub.cli

Linux quick install _#

sudo apt update && sudo apt install gh -y

Run gh --version again after installing to confirm it worked.

If you're on GHES, GHEC, behind SSO, or behind a proxy, complete Side Quest: Enterprise Setup Considerations. If any install step is blocked by proxy, permissions, or host-specific setup issues, use Side Quest: Install gh-aw Troubleshooting.

Authenticate the gh CLI _#

gh auth login

What success looks like: interactive prompts complete and login succeeds.

Choose GitHub.com and then Login with a web browser. A one-time code will appear in your terminal — copy it, open the URL shown, and paste the code when prompted.

New repository _#

1. Create your own public repository at github.com/new:
   • Name it my-agentic-workflows.
   • Check Add a README file.
   • Click Create repository.
2. Clone the repository to your local machine:

Clone repository _#

gh repo clone my-agentic-workflows
cd my-agentic-workflows

✅ Checkpoint _#

• I have cloned the my-agentic-workflows repository to my local machine
• I have navigated into the my-agentic-workflows directory in my terminal
• gh --version returns version 2.40.0 or newer

Side Quest: Agentic Workflows for GitHub Actions Power Users

Optional: read this quick-reference guide if you already know GitHub Actions and want a fast comparison before continuing with Step 5.

📋 Before You Start _#

To get the most out of this fast-track guide, you should have already:

• Completed GitHub Actions in 5 Minutes — or have hands-on experience authoring .github/workflows/*.yml files.
• Understood the core Actions concepts: triggers (on:), jobs, steps, and runners.
• Optionally reviewed What Are Agentic Workflows? for a beginner-friendly introduction before using this cheat sheet.

🎯 What You'll Do _#

Review the key shift from classic Actions to agentic workflows, compare concrete code examples, and keep a short list of what stays unchanged. By the end, you'll have a practical adoption lens for platform and DevOps use cases.

The core mental model shift _#

You keep the same GitHub Actions foundations — triggers, permissions, runners, repo context, and pull-request review flow — and add an agentic layer on top. In practice, this is a smooth transition: frontmatter stays Actions-compatible, while the Markdown body captures the goal and reasoning instructions for the agent.

Before and After: Classic Actions vs. Agentic Workflows _#

The biggest shift is replacing imperative shell steps with a plain-language goal. Here is the same "triage an issue" task written both ways.

Classic GitHub Actions — every decision is hard-coded in shell (simplified for illustration):

on: [issues]
jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - name: Apply bug label
        run: |
          # Must hard-code every label check
          if echo "${{ github.event.issue.body }}" | grep -qi "error\|exception"; then
            gh issue edit ${{ github.event.issue.number }} --add-label "bug"
          fi
          # Real workflows need more checks, error handling, and edge-case branches

Agentic workflow — a plain-language goal replaces the shell logic:

---
on: [issues]
---
Read the opened issue body and apply the single most relevant label
from the repository label list. Do not close or comment on the issue.

Key differences at a glance:

Superset, not replacement _#

Think of agentic workflows as a superset of Actions:

• Frontmatter remains compatible with the Actions model you already know.
• The Markdown body becomes the runtime prompt and can include templating and inline agent features.
• You can still keep deterministic logic when that is the right tool for the job.

Hybrid pattern for real teams _#

The diagram below shows the three-stage data flow: deterministic steps fetch and transform data, structured outputs bridge the two worlds, and the agent handles interpretation and communication.

A practical migration path is hybrid:

1. Keep deterministic jobs or steps for stable data operations (fetch, transform, validate).
2. Pass structured outputs into the workflow body.
3. Let the agent handle interpretation, prioritization, and communication.

This pattern works well for platform and DevOps teams because you preserve deterministic guardrails while reducing hand-written branching logic for context-heavy decisions.

🛠 Try it _#

Open the workflow file you created in Step 4, or find a run: step in any .github/workflows/*.yml file. Pick one step that handles a decision — checking a label, parsing a PR title, or filtering by file path.

Add a comment above that step with a one-sentence plain-language goal. The step body below is just a stand-in — your real step keeps its existing logic unchanged:

# Goal: suggest up to three relevant labels from the repo label list
- name: Check labels
  run: |
    # ... your existing logic stays here unchanged

Keep this goal statement handy — you will use it when authoring your first agentic workflow in Step 7.

What stays the same _#

• Workflows still run in GitHub Actions runners
• Triggers, permissions, and repository context still matter
• You still version workflows in git and review them like code

The same authoring and review workflow applies everywhere — only the runner configuration differs.

Why platform and DevOps teams adopt this model _#

For platform engineers and DevOps teams evaluating adoption, agentic workflows cut the cost of maintaining bespoke scripted automation:

• Less time updating fragile shell scripts; more time on higher-value work
• Every definition is a versioned Markdown file reviewed in a pull request
• Full auditability, change history, and approval gates stay intact
• Compatible with existing runner fleet investments and compliance requirements

✅ Checkpoint _#

• I can explain the mental model shift from scripted steps to goal-oriented execution
• I can identify what changes in agentic workflows and what stays the same from classic Actions
• I can explain why agentic workflows are best described as an Actions-compatible superset
• I identified one specific run: step in an existing workflow that could be replaced with a goal statement
• I can describe one scenario where classic Actions is still the right choice
• I can explain why this model can reduce automation maintenance overhead for platform teams

Return to the main adventure: What Are Agentic Workflows?.

Side Quest: Classify Agentic vs. Standard Workflows

Optional: work through this side quest after What Are Agentic Workflows? to sharpen the distinction through hands-on classification practice.

📋 Before You Start _#

• You've read What Are Agentic Workflows?

The core distinction _#

A standard Actions workflow runs the same fixed steps every time — no judgment required. An agentic workflow replaces those fixed steps with a plain-English task brief, and the AI agent decides how to carry it out.

Key signal: if the output could be different each run because the agent is reading context and making decisions, it's agentic.

Classify Task A _#

Task: Run unit tests on every pull request, fail if any test exits non-zero, and upload coverage.

Write your classification (agentic or standard) in your notes, then reveal.

# Example: standard deterministic step
- run: npm test

Classify Task B _#

Task: Review newly opened issues each morning, group them by theme, flag the urgent ones, and post a short triage summary.

Write your classification, then reveal.

<!-- Example task brief for Task B -->
Review all issues opened in the last 24 hours. Group them by theme,
flag any that look urgent, and post a triage digest as a new issue comment.

Classify Task C _#

Task: Each Friday, scan all open issues and pull requests, summarize recent activity by contributor, and post a weekly team progress digest.

Write your classification, then reveal.

Classify Task D — hybrid _#

Task: On every pull request, run ESLint (fail on errors), then have an AI read the diff and post a summary comment.

Write your classification, then reveal.

<!-- Hybrid example: deterministic + agentic -->
Run ESLint on the changed files, then read the diff and post a plain-English
summary of what changed and why it matters.

Your turn _#

Write one sentence describing what your agentic workflow should do. Save it in your notes — you'll use this idea in Step 7. Focus on a task that needs judgment, not a test or deploy script.

Self-check _#

What makes a workflow agentic rather than standard? Write your answer, then reveal.

Return to the main adventure: What Are Agentic Workflows?.

✅ Checkpoint _#

• You classified Task A as a standard workflow and explained why it needs no AI judgment
• You classified Task B as an agentic workflow and named the decision the agent makes
• You classified Task C as an agentic workflow and described how each Friday run would differ
• You classified Task D as a hybrid agentic workflow and identified its deterministic step
• You can explain what makes a workflow agentic in one sentence
• You've written down your own agentic workflow idea for Step 7

Side Quest: The Two-File Structure

Optional: work through this side quest after What Are Agentic Workflows? to understand how .md source files and .lock.yml lock files relate, and to check your vocabulary.

📋 Before You Start _#

• You've read What Are Agentic Workflows?

The two files _#

An agentic workflow has two files that live in .github/workflows/:

Never edit .lock.yml by hand — regenerate it with gh aw compile after every .md change.

The diagram below shows how they relate:

Read a sample .md source file _#

Here is a complete .md source file:

---
on:
  schedule: daily
permissions:
  issues: read
---

Review all open issues, summarize the key themes, and post a short digest as a new issue.

Look at the sample and answer: which part is the task brief, and which part tells GitHub Actions when to run?

What gh aw compile generates _#

After you run gh aw compile, the tool creates a .lock.yml:

# Auto-generated by gh aw compile. Do not edit by hand.
name: Review open issues
on:
  schedule:
    - cron: "0 8 * * *"
  workflow_dispatch:
permissions:
  issues: read

Try it: Run gh aw compile in your Codespace terminal and open the generated .lock.yml. Find the cron: value and compare it to schedule: daily in your .md source.

Check your vocabulary _#

Before you reveal the answers below, write a one-sentence definition for each term:

• Lock file
• Engine
• workflow_dispatch

How the agent posts output _#

An agent always operates read-only. Any writes — posting a comment, creating an issue — go through safe outputs and guardrails.

Try it: Open the .lock.yml you compiled earlier. Find the step or job that handles the agent's output. Notice how the write is separated from the agent's read-only work.

Return to the main adventure: What Are Agentic Workflows?.

✅ Checkpoint _#

• You can point to the task brief and the trigger in a sample .md file
• You can describe the difference between the .md source and the compiled .lock.yml
• You can define: lock file, engine, and workflow_dispatch
• You know that agents are read-only and writes go through safe outputs

Side Quest: Install `gh-aw` Troubleshooting

Optional: use this guide if Step 6 install fails, then return to the main path.

If gh extension install github/gh-aw fails, use the matching fix below and retry.

The diagram below shows how to identify your error type and apply the right fix:

Local terminal setup quick fixes (Adventure Local) _#

If you are still in local terminal setup and not yet installing gh-aw, use this table first:

Not authenticated (HTTP 401) _#

If you see errors like:

error connecting to api.github.com: HTTP 401: Bad credentials

or:

failed to authenticate to api.github.com

Run:

gh auth login
gh auth status
gh extension install github/gh-aw

Confirm gh auth status shows Logged in to github.com.

Organization Codespace token limitation (HTTP 403) _#

In an org-owned Codespace, gh is pre-authenticated with an org-scoped token that cannot access the extension marketplace. gh extension install github/gh-aw will fail with HTTP 403 in this environment. The main step now recommends the curl script as the primary install path for this reason.

If you arrived here after a 403, run the install script:

curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash
gh aw --version

You do not need to run gh auth login for this case.

Behind a corporate proxy _#

Set proxy variables in your current shell, then retry:

export HTTPS_PROXY="http://proxy.company.com:8080"
export HTTP_PROXY="$HTTPS_PROXY"
export NO_PROXY="127.0.0.1,localhost,.company.com"
gh config set git_protocol https
gh auth status
gh extension install github/gh-aw

GitHub Enterprise Server (GHE/GHES) endpoint _#

Authenticate against your GHES hostname and install with --hostname:

gh config set git_protocol https --host ghes.example.com
gh auth login --hostname ghes.example.com --scopes "repo,read:org,workflow"
gh extension install github/gh-aw --hostname ghes.example.com
gh auth status --hostname ghes.example.com

If your administrator requires different scopes, use the minimum required scopes they provide. When the steps above succeed, gh auth status --hostname ghes.example.com shows "Logged in to ghes.example.com" and gh aw --version prints a version number.

Extension download fails on a locked-down network _#

If install fails with a network error:

1. Download the matching release artifact from github/gh-aw releases.
2. Extract it on a machine that can reach GitHub.
3. Move the extracted folder to your workshop machine and install from a local path:

gh extension install /path/to/gh-aw
gh extension list

Return to Install the gh-aw CLI Extension.

✅ Checkpoint _#

Use this checklist to confirm the install issue is fully resolved before returning to the main path:

• gh auth status (or gh auth status --hostname <your-host> for GHES) shows "Logged in to …" with no errors
• gh extension install github/gh-aw completed without an HTTP 4xx or network error
• gh aw --version prints a version number (for example, gh-aw 1.x.x)
• gh extension list shows github/gh-aw in the output
• I am ready to return to Install the gh-aw CLI Extension and continue

Side Quest: Use `gh-aw` with the GitHub Copilot Cloud Agent

Use this side quest if you're working in the GitHub Copilot Cloud Agent (CCA) and need a terminal for gh-aw commands.

What you'll do _#

You'll open a GitHub Codespace from your browser, verify gh access, install gh-aw, and return to the main workshop flow.

Open a Codespace _#

From Step 6, select the Codespaces button in the Open a Codespace first (GitHub Copilot Cloud Agent users) section.

When the Codespace finishes loading:

1. Open the terminal tab.
2. Run gh auth status.
3. If needed, run gh auth login and complete browser sign-in.

Install gh-aw in the Codespace terminal _#

Run:

gh extension install github/gh-aw

If it's already installed, run:

gh extension upgrade github/gh-aw

Then verify:

gh aw --version

If you hit an HTTP 403 install error in an org-owned Codespace, use Side Quest: Install gh-aw Troubleshooting.

Return to the main workshop _#

Go back to Install the gh-aw CLI Extension, then continue to Step 7.

✅ Checkpoint _#

• You opened a Codespace from the browser
• gh auth status confirms you're logged in
• gh aw --version returns a version number
• You're ready to continue at Step 7

Side Quest: Configure GitHub Copilot Authentication

Optional: work through this guide when you need to configure Copilot authentication for an agentic workflow, then return to your main path.

📋 Before You Start _#

• You have completed Install the gh-aw CLI Extension.
• You have access to your repository's settings (needed if you choose Method 2).

Why authentication matters _#

Agentic workflows call the GitHub Copilot API at runtime to run AI reasoning steps. Without a valid credential, every call returns 401 Unauthorized and the workflow fails immediately. Configuring authentication once, before you run a workflow, ensures your agent can reach Copilot reliably on every future run.

If you are using a terminal, prefer the guided gh-aw setup flows where possible:

• gh aw secrets bootstrap --engine copilot after you choose personal billing
• gh aw add-wizard ... when you are installing a curated workflow and want setup prompts inline

Use the manual guides below when you need or prefer the step-by-step browser procedure.

Choose your method _#

Choose the method that fits your situation: