Agentic Engineering in Action

Issue 9 of Agentic Engineering in Action

GitHub Agentic Workflows: The Five-Minute Version + Free Book

By Maxim Salnikov · · 5 min read

Originally published on LinkedIn: read the original ↗

Contents

What gh-aw is, where it fits, and what to expect from my new interactive book

Note: this article is not a book itself (see below) but a quick introduction to GitHub Agentic Workflows so you could take decision on exploring this topic further.

What if your repository kept doing useful work after you closed your laptop? Not just running a build or deploying an application. I mean reading a new issue, deciding whether it is a bug or a feature request, asking for missing details, investigating failed CI, or preparing a documentation update for review.

CI/CD already automates the predictable part of repository life: build, test, deploy. But much of repository maintenance depends on judgment. Someone has to interpret issue descriptions, compare documentation with code, make sense of logs, and decide what to suggest next.

This work sits in the repository’s outer loop — the collaborative activity around the code. GitHub Agentic Workflows brings coding agents into that loop.

So, what exactly is gh-aw?

A GitHub Agentic Workflow is an intent-driven repository workflow written in Markdown and executed by a coding agent inside GitHub Actions.

You author a Markdown file with YAML frontmatter. The frontmatter sets the operational boundaries: when the workflow runs, which engine it uses, what it can access, and which effects it may request. The Markdown body describes the job in natural language.

Then  gh aw compile  turns that source into a hardened GitHub Actions workflow — a generated  .lock.yml  file that GitHub can run.

That distinction matters. A traditional Actions workflow encodes an exact sequence of steps. An agentic workflow describes an outcome and its constraints, then gives a coding agent room to interpret the repository context. It uses the same Actions infrastructure for a different kind of work.

The prompt is only half of the workflow

The natural-language instructions get most of the attention, but the surrounding controls are what make the workflow operational:

  • on:  decides when the agent wakes up.
  • engine:  selects the coding-agent runtime.
  • permissions: ,  network: , and  tools:  define what it can access.
  • safe-outputs:  defines what it may ask GitHub to change.

Safe Outputs are especially important. The agent’s repository token is read-only by default. If the workflow needs to add a comment, apply a label, or propose a pull request, the agent requests a structured output. A separate permission-scoped job validates that request and applies it according to the configured policy.

I describe this boundary as propose → validate → apply.

Does it guarantee a correct result? No. An allowed comment can still be unhelpful, and a proposed patch can still contain a bug. Reduced authority is not the same as correctness. The goal is to limit the blast radius and keep consequential changes reviewable.

What belongs in an agentic workflow?

A good candidate usually has three properties:

  • The task repeats, but still requires interpretation.
  • A useful answer may vary from one run to another.
  • The result is narrow, inspectable, and easy to correct or reverse.

Issue triage, pull-request summaries, documentation maintenance, CI investigation, dependency research, and draft changes all fit this shape.

When exact reproducibility is the requirement, keep the job in deterministic GitHub Actions. Publishing releases, deleting data, or force-pushing? Not a sensible first workflow. And if the result must be 100% correct without human review, an agentic workflow is probably the wrong tool.

The best first workflow is deliberately small: one teammate, one job, one reviewable output. Small is good here.

The book picks up where this article stops

Today I’m releasing GitHub Agentic Workflows: An Interactive Book.

The book follows one running example — the Repo Assistant — from a small issue-triage workflow to a governed multi-repository fleet. Its 14 chapters widen the scope in three parts:

  • The Individual: authoring, compilation, triggers, and engines.
  • The Team: Safe Outputs, defense in depth, tools and MCP, reusable patterns, and observability.
  • The Organization: shared components, memory, governance, cost, and fleet adoption.

Builders can follow the examples step by step. Technical leaders can focus on the security, cost, governance, and adoption decisions around them.

I also wanted the examples to be more than plausible-looking snippets. Every positive workflow example was compiled with the real  gh aw  CLI. The launch edition covers gh-aw v0.88.7 (Public Preview), so the book states exactly which version its claims and examples were verified against.

Compilation proves that a workflow’s source is valid and produces a lock file. It does not pretend that every example was deployed with live credentials. That distinction is visible throughout the book.

And yes, the book uses gh-aw to stay current

The book’s update process now begins with an agentic workflow.

Every two weeks, a strict, read-only gh-aw workflow checks official releases and documentation for changes newer than the book’s verified framework baseline. It compares those sources with the current prose edition, then maps actionable changes to the exact chapters, examples, and research files that maintainers may need to revisit.

Its authority is intentionally narrow. The workflow can read the official  github/gh-aw  repository, its published documentation, and the book repository. Through Safe Outputs, it may create at most one deduplicated review issue describing what changed, which parts of the book may be affected, and what must be verified before an update.

It cannot edit a chapter, rewrite an example, advance the framework version, or open a pull request. If an existing issue already covers the change, it creates nothing. If an official source is unavailable, it reports the blocker instead of guessing.

This is the pattern I want the book to teach: let an agent monitor a moving upstream project and prepare the evidence, but keep editorial decisions and publication with human maintainers. Useful automation, bounded authority, visible review.

Where to start

This article is deliberately the short version. Read it to understand the shape of GitHub Agentic Workflows and decide whether they fit your repository. The book takes the next steps: authoring, securing, debugging, reusing, and scaling them.

If you have a recurring repository task that can be described in words but not reduced to a reliable  if/then  script, start with one narrow workflow. Give it the minimum capabilities it needs, compile it, inspect the generated Actions workflow, and keep a human at the review boundary.

Then see whether it earns the next job.

#github-agentic-workflows#books