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.
- 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, reasons about the results, and posts the output automatically. The frontmatter is fully Actions-compatible — triggers, permissions, and runners all apply.
Think of it like a scheduled email digest you've set up in an app: every morning it reads your inbox, picks out the three most important messages, and sends you a one-paragraph summary — without you touching a keyboard. An agentic workflow does the same thing for your GitHub repository: it runs on a schedule, reads your issues, pull requests, or code, and posts a structured summary exactly where your team will see it. You describe the job in plain English; the agent figures out how to do it.
The agent always runs within a sandbox and posts results through a guardrailed output system — you will explore how this works in How Agentic Workflows Stay Safe.
Why not just use a standard Actions workflow?
Not a DevOps engineer? Here is the short version: a standard workflow runs the same fixed script every time — like a recipe that always follows exactly the same steps in the same order. An agentic workflow reads the situation first, then decides what to do — like asking a colleague to "check what came in overnight and give me a quick rundown." The output is different every run because it reflects what actually happened.
Three concrete differences a DevOps engineer will also notice:
- Agent reasoning loop: Each run, the agent reads live repository context, decides what matters, and composes output that differs every time — no two runs are identical.
- Natural-language task brief: You write what you want in plain English. No
run:scripts, no fixed shell commands. - Dynamic tool use: The agent calls tools (read files, list issues, search code) based on what it discovers at runtime — not a predetermined sequence of steps hardcoded in YAML.
If you already write Actions YAML, the frontmatter stays the same (triggers, permissions, runners). And it is not one-or-the-other: agentic workflows can include custom jobs and deterministic steps alongside the AI agent — fixed data-fetch steps can run first, then the agent interprets and synthesizes the results.
- What it is: A Markdown file (
.md) with YAML frontmatter and a plain-language brief.gh aw compileconverts it into a standard Actions workflow (.lock.yml) that runs the agent. - What it produces: A synthesized report or action the agent composes from live repository data — different every run based on what it finds.
- Why it exists: Classic Actions handles deterministic CI/CD. Agentic workflows fill the gap for tasks that need judgment — or you can mix both in a single hybrid workflow.
Match each term to what it describes in an agentic workflow. Make your decision before revealing the answers.
Term 1: .md source file
- I've made my decision for Term 1
Reveal Term 1 answer
The Markdown source file — it contains the YAML frontmatter (trigger, permissions, runner) and your plain-English task brief. You author and edit this file.
Term 2: .lock.yml compiled file
- I've made my decision for Term 2
Reveal Term 2 answer
The compiled lock file — gh aw compile generates it from the .md source. GitHub Actions runs this file, not the .md. Never edit it by hand.
Term 3: gh aw compile
- I've made my decision for Term 3
Reveal Term 3 answer
The compile command — it reads the .md source and writes the .lock.yml file that Actions runs. You must recompile any time you change the source.
Tip
Want more examples of how the two-file structure works? Side Quest: Agentic Workflows Deep Dive includes a fully annotated workflow pair.
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
Reveal Task A answer
Standard Actions workflow. Every run follows the same fixed steps: run lint, run tests, report the exit code. No judgment is required.
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
Reveal Task B answer
Agentic workflow. The agent reads live issue data, applies judgment to assess urgency, and composes a summary that differs every run based on what it finds.
Tip
Want to go deeper? Side Quest: Agentic Workflows Deep Dive covers more exercises, example output, the two-file structure, and concept checks.
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: what data should the agent read, and what should it post when it's done?
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 one-sentence task brief for a real routine task
- My brief specifies what data the agent should read
- My brief specifies what the agent should post when done
Tip
Struggling to think of a task? Browse the gh-aw issue-ops pattern for inspiration. You will write a real version of your brief in Step 7.
- I can describe what an agentic workflow is in one sentence
- I can explain one way an agentic workflow differs from a standard Actions workflow
- I can identify the three parts: trigger → agent → safe output