An agentic automation pipeline watches your repository for an event, hands the change to a model with a tightly scoped set of tools, and lets that model do a chore you keep putting off: draft the docs, write the changelog, summarize the release, or triage a new issue. This tutorial builds one from scratch on GitHub using GitHub Agentic Workflows, the open pattern GitHub describes as GitHub Actions with a model as the work-item processor. Budget about 30 to 45 minutes, a repository you control, and a GitHub account with Actions enabled. There is no paid product to buy: the tooling is MIT-licensed and runs on the Actions minutes you already have.

The reason this pattern is worth learning now is that GitHub has moved it from demo to production. In a 30-day run on the microsoft/aspire project, an agentic docs workflow turned 396 merged product pull requests into 82 documentation pull requests, all of which merged, with a median time-to-merge of 44.8 hours and 96 percent merged inside a week. That is the target: an agent that produces reviewable pull requests, not autonomous commits you have to police.

What You Need

Everything here runs inside your existing GitHub setup. There is no external service to sign up for.

  • A GitHub repository you own or admin, with GitHub Actions enabled.
  • The gh CLI installed and authenticated, plus the gh-aw extension (install script and commands are in the official docs).
  • A model provider your org allows. GitHub Agentic Workflows can drive the built-in Copilot engine or other supported models, selected with the engine field.
  • A low-risk repository to prototype in. Do not wire your first agent into the repo that ships to customers.
  • Ten minutes to read the GitHub token permissions model, because the whole design rests on giving the agent as little write access as possible.
Matte 3D render of a single event trigger feeding a scoped work item into a processing block
An agentic workflow is an event listener with a model in the middle and guardrails on the way out.

The Workflow

The mental model is simple. You write one Markdown file that declares a trigger, a set of tools, a permission budget, and an output contract, followed by a plain-English prompt. A compile step turns that Markdown into a standard Actions workflow. The agent then runs on your trigger, reasons over the change, and proposes a result through a constrained output channel. Here is the full build.

Step 1: Scaffold the workflow file

Create the file at .github/workflows/pr-docs.md. The frontmatter is YAML; the body is the instruction you would give a careful teammate. A minimal skeleton looks like this: an on block that fires when a pull request closes, an engine line that picks the model, a permissions block, a tools block, and a safe-outputs block that says the only thing this agent may produce is a pull request. Under the frontmatter, write the prompt: "When a pull request merges, read the diff and linked issues, and draft documentation updates that match the conventions in the docs directory." Keep the prompt specific about inputs (the diff, the issue) and outputs (a docs pull request), because vague prompts are the single biggest cause of low-quality drafts.

Step 2: Declare tools and the model engine

The tools block is where you grant capabilities. For a docs agent you typically enable the github toolset scoped with toolsets, a min-integrity level, and an allowed-repos list so the agent can read the source repo and open a pull request in the docs repo, and nothing else. If your job needs an external capability, such as querying an API or a database, expose it as a Model Context Protocol server rather than handing the agent shell access; MCP tools are declarative and auditable, which is exactly what you want in a workflow that runs unattended. The engine field selects the model, so you can start on the built-in Copilot engine and swap later without rewriting the logic.

Step 3: Lock down writes with safe-outputs

This is the step that makes the pattern safe enough for production. The agent itself runs with a read-only token. It never gets broad write access to your repository. Instead, anything the agent wants to change flows through a safe-outputs handler that materializes the action through a scoped GitHub App with explicit allow-lists. If the contract says create-pull-request, the agent can open a pull request and nothing more. You can add protected-files: blocked so the agent can never touch security config or workflow files, and allowed-base-branches: [main, release/*] so it can only target branches you name. The result is a pipeline where the model proposes and a scoped, verifiable channel disposes, so a bad or hijacked prompt cannot escalate into repository write access.

Matte 3D render of a read-only model output passing through a narrow allow-list gate before reaching a pull request
Writes never come from the model directly. They pass through a scoped safe-outputs gate.

Step 4: Compile, commit, and review the first runs

Run the compile command from the gh-aw extension. It reads your Markdown file and generates a sibling .lock.yml, which is an ordinary GitHub Actions workflow. Commit both files together: the Markdown is the source you edit, and the lock file is the artifact Actions actually runs, so keeping them in sync is what stops silent drift. Push, then merge a small test pull request to fire the trigger. Watch the Actions run, open the pull request the agent proposes, and review it by hand. Do this for the first dozen runs. Only widen the trigger or the tool scope once the drafts consistently match your conventions. GitHub's own guidance is the same: start narrow, review everything, expand slowly.

Troubleshooting

Five failure modes account for almost every first-run problem.

  • Compile succeeds but nothing runs. You forgot to commit the generated .lock.yml, or the on trigger does not match the event you tested. Actions runs the lock file, not the Markdown, so both must be committed.
  • The agent produces no pull request. Your safe-outputs contract does not include create-pull-request, or the scoped app lacks permission on the target repo. Check that the output type is declared and the app is installed where the pull request should land.
  • The run touches files it should not. Add protected-files: blocked and tighten allowed-base-branches. If the agent had any way to write beyond the safe-output channel, the token was over-scoped; the agent token should be read-only.
  • Runs are noisy or expensive. Your trigger is too broad. Narrow it to specific events, paths, or labels so the agent only wakes for changes that actually need its help.
  • Drafts miss your conventions. The prompt is too vague. Name the style guide, point at an example, and tell the agent which directory holds the canonical patterns. Specificity in the prompt is what turns a generic draft into a mergeable one.
Matte 3D render of one workflow blueprint branching into docs, changelog, and release-note outputs
One skeleton, many chores: docs, changelogs, release notes, and issue triage share the same shape.

What to Try Next

Once the docs agent is stable, the same skeleton covers a family of post-merge chores. Point it at release tags to draft release notes, at merged pull requests to append changelog entries, or at new issues to propose triage labels and a first-response summary. The cross-repository version, where an agent in your product repo opens documentation pull requests in a separate docs repo, is the exact pattern GitHub shipped on the aspire project, and it is a natural second workflow. If you want to compare approaches before you standardize, read how the GitHub Copilot coding agent handles assigned tasks, and how a durable-orchestration engine like Mistral Workflows models the same idea outside GitHub. Teams that want their agents to reach internal systems should pair this with a deployed MCP server so the tools stay declarative and reviewable. The gh-aw source is open on GitHub if you want to read exactly how the compile step and safe-output handler work.

Frequently Asked Questions

Is GitHub Agentic Workflows free to use?

The gh-aw tooling is MIT-licensed and open source, and the compiled workflows run as standard GitHub Actions, so they consume the Actions minutes in your plan. The only variable cost is the model provider you select with the engine field.

How is this different from the Copilot coding agent?

The Copilot coding agent is a task-assignment product: you hand it an issue and it works the task interactively. An agentic workflow is event-driven infrastructure: it fires automatically on a repository event, runs headless, and returns a reviewable pull request. They solve different problems and can be used together.

Can the agent push directly to my main branch?

No, not if you configure it correctly. The agent runs with a read-only token. Writes only happen through the safe-outputs channel, which materializes an allow-listed action such as opening a pull request via a scoped GitHub App. Add allowed-base-branches and protected-files to constrain it further.

Which models can I run?

The engine field selects the model. You can start on the built-in Copilot engine and switch to another supported provider without rewriting the workflow logic, since the trigger, tools, and output contract stay the same.

Does it work across multiple repositories?

Yes. Scoping the github toolset with an allowed-repos list lets an agent read one repository and open pull requests in another, which is how the cross-repo documentation pattern works. Install the scoped app on each repository the workflow needs to reach.