Skip to content

05-agentic-workflows-intro.md

Latest commit

 

History

History
137 lines (87 loc) · 6.65 KB

05-agentic-workflows-intro.md

File metadata and controls

137 lines (87 loc) · 6.65 KB
Raw

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

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

Term What it means
Trigger The event or schedule that starts the workflow
Task brief The plain-English instructions you write for the agent
Safe outputs The guardrails that control how the workflow writes back to GitHub

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?

Agentic workflow lifecycle: a Markdown file with YAML frontmatter and a task brief is compiled by gh aw compile into a lock.yml file, which GitHub Actions triggers, runs the AI agent that reads repository data and calls tools, and produces a structured output posted back to GitHub
  • .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.

Side-by-side comparison of Classic GitHub Actions YAML versus an Agentic Workflow with safety highlights. Classic: schedule trigger flows through static YAML steps and shell scripts to produce output. Agentic: same trigger flows through a plain-English task brief with safety config (permissions, tools, safe-outputs) into a sandbox-isolated AI agent that applies integrity filtering and zero-secrets constraints, producing output only through declared safe-output surfaces.

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.

Reveal Task A answer

Standard Actions workflow. Every run follows the same fixed steps. No judgment required.

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

Reveal Task B answer

Agentic workflow. The agent reads live data, applies judgment, and composes a different summary every run based on what it finds.

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.
Reveal one possible brief

You are a repository triage assistant. Each day, review issues opened in the last 24 hours, summarize each in one sentence, flag potential blockers, and post one concise digest comment for maintainers.

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.

Tip

Want annotated examples and more exercises? See Side Quest: Agentic Workflows Deep Dive.

✅ 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
Still uncertain? Try this before moving on

Does gh aw compile change what the agent does at runtime? Decide first.

Reveal

No. Compile converts .md to .lock.yml. Runtime output comes from your task brief and live repo state.

Next: How Agentic Workflows Stay Safe