By the end of this chapter you can say precisely what an agentic workflow is, explain why the repository's outer loop is where it earns its keep, and judge when to reach for GitHub Agentic Workflows (gh-aw) instead of plain GitHub Actions. This is the vocabulary chapter: the terms defined here — outer loop, Continuous AI, safe-by-default — are used as settled language for the rest of the book.
This chapter targets gh aw v0.88.7 (Public Preview). You won't write a workflow yet — that is Chapter 2. First, the idea.
Think about how work actually moves through a repository. There is the inner loop: the fast, interactive coding you do at your desk — edit, run, debug, repeat — minute to minute. And there is the outer loop: the repository's slower, collaborative life that surrounds and outlives any one editing session — issues filed, pull requests opened and reviewed, discussions, releases, CI results, and docs that quietly drift out of date. You leave the inner loop every time you close your laptop. The outer loop keeps going.
CI/CD automated half of the outer loop
Continuous integration and deployment were a triumph of outer-loop automation — but only for the deterministic half. A build, a test suite, a release: these “do exactly what you tell them, every time, in the same way” (How They Work). That determinism is precisely what you want when correctness means identical behavior on every run.
But a large, genuinely useful class of outer-loop work is not like that. Reading a new issue and deciding whether it's a bug or a feature request. Asking a reporter for the missing reproduction step. Keeping the docs honest as the code changes. Investigating why CI went red. None of these can be written as a fixed if/then rule, because the right action depends on unstructured context you can only interpret. That is judgment work, and CI/CD was never built to express it — so it fell to already-overloaded humans, or it simply didn't get done.
Where the throughput actually stalls
This is the gap the book is about. Individual AI productivity has advanced quickly, but GitHub Next observes that faster inner-loop coding “can shift burdens to other team members, or to later stages in software projects” — more code generated means more to review, triage, document, and maintain (Continuous AI). The bottleneck moves outward, into the collaborative loop, and that is exactly the loop CI/CD left to human judgment.
GitHub Next gives this idea a name: Continuous AI — “all uses of automated AI to support software collaboration on any platform.” It is deliberately named to rhyme with CI/CD: “Just as CI/CD transformed software development by automating integration and deployment, Continuous AI covers the ways in which AI can be used to automate and enhance collaboration workflows” (Continuous AI). The framing is a third leg alongside CI and CD — and, notably, a category rather than a product: “not a term GitHub owns, nor a technology GitHub builds.”
An agentic workflow, defined
An agentic workflow is the concrete unit that practices Continuous AI. GitHub defines these as “automated, intent-driven repository workflows that run in GitHub Actions, authored in plain Markdown and executed with coding agents” (launch blog). You describe the outcome you want in natural language; a coding agent interprets that intent and carries out the multi-step work. Where traditional automation follows fixed logic, an agentic workflow has agency — it can “understand context, make decisions, and generate content by interpreting natural language instructions flexibly” (How They Work).
That makes it three things it is often confused with, but isn't:
Not a chatbot or an IDE assistant. Those are interactive and human-driven, turn by turn. An agentic workflow is standing and event-driven: it wakes on a repository event, does one job unattended, and proposes a result.
Not a grant of unlimited authority. It gets a defined task and configured permissions, not a general mandate to maintain the repository. For proposed code changes, this book deliberately requires human review and merge. That is our policy, not a product limitation: v0.88.7 supports opt-in auto-merge and merge operations, which these recipes do not enable (Safe Outputs: Pull Requests, v0.88.7).
Not a replacement for GitHub Actions. Which brings us to how it actually runs.
It compiles to GitHub Actions
Here is the key architectural fact, and the reason gh-aw is additive rather than a competitor to your existing pipelines. You author a Markdown file; the gh aw compile command turns it into an ordinary, security-hardened GitHub Actions workflow that GitHub runs. “The .md file is the editable source of truth, while .lock.yml is the compiled GitHub Actions workflow with security hardening” (How They Work). Agentic workflows “run on GitHub Actions because that is where GitHub provides the necessary infrastructure for permissions, logging, auditing, sandboxed execution, and rich repository context” (launch blog). So gh-aw adds three things Actions alone lacks — an agentic engine that reasons over context, a natural-language authoring surface, and a security model — on top of the substrate you already trust. The compile model is Chapter 3.
Safe by default (a first look)
A standing agent needs a boundary between reasoning about a change and having authority to apply it. That is least privilege: give it only the authority its task needs. The agent's repository token is read-only by default, so that token cannot authorize direct pushes or issue edits (Safe Outputs, v0.88.7). This does not make the local workspace read-only: preparing a patch in checked-out files is different from having permission to publish it to GitHub.
To publish a change under this model, the agent requests a structured safe output. A separate, permission-scoped job checks the request against the configured output types and limits before applying it. This propose → validate → apply boundary separates reasoning from remote write authority. It does not mean a person approves every comment or label: authorized outputs can be applied automatically. The mechanism is Chapter 6.
Reduced authority is not a guarantee of harmless content. An allowed comment can still mislead a reporter or reveal private context; a proposed patch can still be wrong. The default threat detector adds AI analysis, not perfect detection (Threat Detection, v0.88.7). Narrow permissions and mediated outputs reduce the blast radius; they do not guarantee zero damage or prevent every leak. Layered defenses and their limits are the subject of Chapter 7.
The mental model GitHub offers is refreshingly simple: “if repetitive work in a repository can be described in words, it might be a good fit for an agentic workflow” (launch blog). More precisely, a task fits when it has all three of these traits:
It's judgment work — subjective and repetitive, the kind of task “that traditional CI/CD struggle to express” because there's no fixed rule to encode.
Exact reproducibility isn't the point — triage, drafting docs, researching dependencies, proposing improvements for review. A slightly different (good) answer each time is fine.
The permitted effects are limited and reviewable — a comment or label is a useful starting point when a mistake is easy to spot and correct, not because those outputs are inherently harmless. A draft PR provides a review point before code lands; it still needs tests and human review.
When to reach for something else
Agentic workflows are additive, not universal. Keep the work in deterministic GitHub Actions — or a human's hands — when:
The task must be exactly reproducible. Builds, tests, and releases must behave identically every run. GitHub is explicit: don't use agentic workflows “as a replacement for GitHub Actions YAML workflows for CI/CD”; the use cases “largely do not overlap” (launch blog).
The action is high-stakes or hard to reverse. Publishing a release, deleting data, force-pushing — if a mistake can't be shrugged off with a click, it isn't a starting point.
Success must be 100% correct with no human in the loop. The value here is throughput on reviewable proposals, not unsupervised perfection.
One workflow is trying to do everything. The unit is one teammate, one job. Start narrow and let patterns emerge.
There's a deeper reason the human stays central. The impact study of GitHub Next's real repository assistant found that throughput was gated less by the model than by “how often human maintainers chose to act on the agent's proposals” (Repo Assist impact report). Design around that review capacity, rather than simply generating more proposals.
Concepts land when you see them in one artifact. Here is the book's running example — the Repo Assistant, an agentic workflow that triages a newly opened issue. You'll build and ship it in Chapter 2; right now we're just reading it, because every concept from this chapter is visible in one file.
This is the complete shared workflow, not a shortened prompt; the explanations follow the code. Its vague-issue instruction matters: the assistant should ask for details rather than guess a label.
---
on:
issues:
types: [opened]
workflow_dispatch:
permissions:
contents: read
issues: read
engine: copilot
network: defaults
safe-outputs:
add-comment:
max: 1
add-labels:
allowed: [bug, enhancement, question, documentation]
max: 1
---
# Repo Assistant — triage a new issue
You are the **Repo Assistant**. A new issue was just opened in this repository.
Read the triggering issue's title and body, then triage it:
1. Decide what kind of issue it is (a bug report, a feature request, a question,
or a documentation gap) and how a maintainer should treat it.
2. Post **one** short, friendly triage comment that (a) restates the request in a
sentence, (b) names the category you chose and why, and (c) lists any missing
information the reporter should add.
3. Apply **at most one** label from the allowed set that best matches the issue.
If the issue is empty or too vague to categorize, post a comment asking for the
missing details and do not apply a label.
This workflow demonstrates **safe-outputs**: the agent runs read-only and never
writes to GitHub directly — it *requests* a comment and a label, which gh-aw
applies from separate, permission-scoped jobs.
Five concepts, one artifact
(1) Agentic workflow. The whole file is one: YAML frontmatter configures execution, while the natural-language body asks the agent to judge context. engine: copilot selects the coding agent that interprets that intent. Engines are Chapter 5.
(2) Outer loop. The issues trigger with types: [opened] binds it to a collaborative, outer-loop moment — a new issue — not to your keystrokes. workflow_dispatch also permits manual activation, but does not supply a newly opened issue's payload; use an issue event to exercise this mission. Triggers are Chapter 4.
(3) Continuous AI. This is Continuous Triage, one of the named patterns, expressed as a single workflow.
(4) Compiles to Actions. Running gh aw compile turns this Markdown into a hardened .lock.yml that GitHub Actions executes — the subject of Chapter 3.
(5) Least privilege and mediated effects.permissions gives the agent read-only access to repository contents and issues, not a ban on local workspace edits. The configured triage outputs are at most one comment and one allow-listed label, requested through safe-outputs and applied by permission-scoped jobs. These limits bound the requested operations, not their content's correctness or safety. Full mechanism in Chapter 6.
The same least-privilege idea extends to network access: network: defaults selects the default allowed destinations, not an offline mode. Model inference normally uses a separate proxy path, and allowed destinations can still receive sensitive data (Network, v0.88.7). That is another reason to treat the boundary as risk reduction, not a no-leakage promise.
You now have the vocabulary the rest of the book stands on:
The inner loop is your interactive coding; the outer loop is the repository's collaborative life. CI/CD automated the outer loop's deterministic work and left its judgment work to humans.
An agentic workflow is intent-driven, event-triggered repository automation authored in Markdown and run by a coding agent — a standing teammate with configured authority, not a chatbot. This book keeps human review and merge as the policy for proposed code changes.
Continuous AI is GitHub Next's name for applying AI to that outer loop — a third leg beside CI/CD — and gh-aw is how you practice it.
gh-aw compiles to GitHub Actions; it is additive, adding an engine, a natural-language surface, and a security model on top of the substrate you already trust.
The agent's repository token is read-only by default; local workspace edits are a different kind of authority. Safe outputs mediate remote effects through configured operations and limits. They reduce the blast radius, but neither validation nor detection guarantees harmless content.
What's next. Enough theory — time to ship. In Chapter 2: The 10-Minute Win you'll install the gh aw CLI and get this exact Repo Assistant running end to end, triaging a real issue through the safe-by-default boundary.