GitHub Agentic Workflows: A Hands-On Tutorial

On February 13, 2026, GitHub shipped something that makes traditional CI/CD look quaint. GitHub Agentic Workflows (gh-aw) bring AI coding agents into GitHub Actions. Instead of writing deterministic YAML that checks whether a test passed or failed, you write plain-English instructions that tell an agent what you want done. The agent reads your repo, reasons about it, and produces artifacts like issues, pull requests, or reports.

GitHub calls the broader pattern Continuous AI: background agents that run on your repository the same way CI jobs do, but for tasks that require judgment instead of rules. Think issue triage, documentation drift, test coverage gaps, and performance regressions. Work that was too fuzzy for a linter, too tedious for a human to do daily, and too important to ignore.

This tutorial walks you through setting up two working agentic workflows from scratch. You'll have both running in well under an hour.

What Are GitHub Agentic Workflows?

Traditional GitHub Actions are deterministic. A workflow file says "run these commands, check these exit codes, pass or fail." That works brilliantly for builds, tests, and deploys. But a huge amount of engineering work resists that kind of automation: triaging incoming issues, keeping docs accurate after code changes, spotting subtle performance regressions, or reviewing whether new code matches the project's style conventions.

Agentic workflows fill that gap. You describe outcomes in a Markdown file with a YAML frontmatter block, and a coding agent (Copilot, Claude, or Codex) executes the instructions inside a sandboxed GitHub Actions runner. The agent has read access to your repository by default. Write operations happen through a controlled mechanism called safe outputs, which constrain the agent to pre-approved GitHub operations like opening a PR or creating an issue.

Each workflow consists of two files in .github/workflows/:

• A .md file with your intent (YAML frontmatter for triggers, permissions, and safe outputs; Markdown body for instructions)
• A .lock.yml file (generated by the CLI) that GitHub Actions actually executes

The Markdown is human-readable intent. The lock file is the machine-readable execution plan. You review both before pushing.

Prerequisites and Setup

Before you start, you'll need:

• An AI account: GitHub Copilot, Anthropic Claude, or OpenAI Codex. Any of these can serve as the agent engine.
• A GitHub repository where you have write access and GitHub Actions enabled.
• GitHub CLI v2.0.0+ installed. Verify with gh --version.
• Linux, macOS, or Windows with WSL.

Install the gh-aw extension:

gh extension install github/gh-aw

If you hit authentication issues, you can also install via the bootstrap script:

curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash

Next, configure your AI engine secret. For Copilot, you'll set a COPILOT_GITHUB_TOKEN (a separate token with Copilot access, distinct from the default GITHUB_TOKEN). For Claude or Codex, set ANTHROPIC_API_KEY or OPENAI_API_KEY as a repository secret.

Your First Workflow: Continuous Issue Triage

Let's start with something immediately useful: an agent that triages new issues by summarizing them, applying labels, and adding a comment with suggested next steps. This is exactly the kind of judgment-heavy chore that CI was never designed for.

Create a file at .github/workflows/issue-triage.md:

---
on:
  issues:
    types: [opened]
permissions:
  contents: read
  issues: read
safe-outputs:
  add-comment:
    issue-number: "${{ github.event.issue.number }}"
  add-labels:
    issue-number: "${{ github.event.issue.number }}"
    labels: [bug, enhancement, question, documentation, good-first-issue]
tools:
  github:
---

# Issue Triage Agent

You are a repository maintainer triaging a newly opened issue.

## Steps

1. Read the issue title and body carefully.
2. Review the repository README, recent issues, and labels to understand project context.
3. Determine the most appropriate label(s) from the allowed set.
4. Add the label(s) to the issue.
5. Write a brief, helpful comment that:
   - Acknowledges the issue
   - Summarizes your understanding of the problem or request
   - Suggests concrete next steps (e.g., "Could you share your OS and Node version?")
   - Tags related issues if any exist

Be concise. Don't repeat the issue text back verbatim.

Let's break this down. The frontmatter tells GitHub Actions:

• Trigger: Run when a new issue is opened.
• Permissions: Read-only access to contents and issues.
• Safe outputs: The agent can add a comment and apply labels to the triggering issue. Nothing else. It can't open PRs, create branches, or modify code.
• Tools: The GitHub tool set, giving the agent access to repo metadata and the GitHub API.

The Markdown body below the frontmatter is the agent's instruction set. Write it the way you'd brief a new team member.

Now compile and push:

# Generate the lock file
gh aw compile

# Commit both files
git add .github/workflows/issue-triage.md .github/workflows/issue-triage.lock.yml
git commit -m "feat: add issue triage agentic workflow"
git push

# Optionally trigger a manual run
gh aw run issue-triage

Open a test issue in your repository. Within two to three minutes, the agent will read the issue, apply labels, and leave a comment. Check the Actions tab to see the full execution log, including what the agent read, what it reasoned about, and what outputs it produced.

Your Second Workflow: Continuous Documentation

Documentation rot is one of those problems every team knows about and nobody solves. A function's behavior changes, the docstring doesn't, and three months later someone wastes half a day debugging the mismatch. Agentic workflows can catch this automatically.

Create .github/workflows/docs-sync.md:

---
on:
  push:
    branches: [main]
permissions:
  contents: read
  pull-requests: read
safe-outputs:
  create-pull-request:
    title-prefix: "docs: "
    branch-prefix: "agentic/docs-sync-"
    labels: [documentation, automated]
tools:
  github:
---

# Documentation Sync

After each push to main, check whether documentation still matches the code.

## What to check

- README.md: Do setup instructions, API examples, and feature descriptions
  reflect the current code?
- Docstrings and inline comments: Do they accurately describe what functions
  and classes actually do?
- CHANGELOG: Are recent changes reflected?

## Rules

- Only flag genuine mismatches. Don't rewrite docs for style.
- If everything is in sync, do nothing. Don't create empty PRs.
- When you find a mismatch, fix the documentation (not the code) and open
  a pull request with a clear description of what changed and why.

This workflow triggers on every push to main. The agent reads the diff, compares documentation to the current implementation, and if something's out of sync, opens a PR with the fix. The safe outputs section constrains it: it can only create PRs with a docs: title prefix on branches matching agentic/docs-sync-*. Pull requests are never auto-merged. A human always reviews.

Compile and push:

gh aw compile
git add .github/workflows/docs-sync.md .github/workflows/docs-sync.lock.yml
git commit -m "feat: add continuous docs sync workflow"
git push

The push itself will trigger the workflow. If your most recent commits changed any code that's referenced in docs, you should see a PR appear within a few minutes.

The Lock File and Guardrails

The security model here deserves attention, because it's what makes agentic workflows practical rather than terrifying.

When you run gh aw compile, the CLI reads your .md workflow and generates a .lock.yml file. This lock file is a standard GitHub Actions YAML workflow with all the agent configuration baked in. GitHub Actions executes the lock file, not the Markdown directly. The key safety mechanisms:

• Read-only by default. The agent can read your repository, but it can't write to it unless you explicitly define safe outputs.
• Safe outputs are declarative. Each write operation (creating a PR, adding a label, posting a comment) must be listed in the frontmatter. The agent can't invent new output types at runtime.
• Sandboxed execution. Agents run in isolated containers with network restrictions and tool allowlisting.
• PRs are never auto-merged. Any code change the agent proposes goes through your normal review process.
• Full audit trail. Every agent action is logged in the Actions run, so you can inspect exactly what it did and why.

This defense-in-depth approach is what separates gh-aw from "just run Claude in a GitHub Action." Running a coding agent CLI directly in a standard YAML workflow often grants more permissions than any single task requires. Agentic workflows constrain the blast radius by design.

Performance Considerations

Agentic workflows add a new class of CI load. Each run involves an LLM call, which means agent runs typically take two to three minutes even for simple tasks. If you're running triage on every new issue, docs-sync on every push, and maybe a daily test coverage agent, that's a meaningful increase in runner utilization.

A few things to consider:

• Runner startup time matters. GitHub-hosted runners can take 30-60 seconds just to spin up. When your workflow itself only takes two minutes, that overhead is significant. Self-hosted or bare-metal runners eliminate it.
• Concurrency adds up. If your repo gets 50 issues a day, that's 50 concurrent or near-concurrent agent runs on top of your existing builds and tests.
• Scheduled workflows need reliable runners. Daily status reports, weekly test coverage sweeps, and recurring quality checks all hit your runner pool at predictable times. You want those to start on time, not queue behind a busy CI backlog.

If you're already hitting runner limits or paying for GitHub-hosted minutes, adding agentic workflows is a good reason to look at faster alternatives. Tenki's bare-metal runners plug directly into your existing GitHub Actions setup and run 35-67% faster than GitHub-hosted runners at roughly half the cost. For agentic workloads specifically, the near-zero startup latency means your agent starts reasoning immediately instead of waiting for a VM to provision.

When using Copilot as your agent engine, each workflow run typically incurs two premium requests: one for the agentic work and one for a guardrail check through safe outputs. Keep this in mind when planning your workflow frequency.

The Wizard Shortcut

If writing Markdown workflows from scratch feels like too much for a first try, the CLI includes an interactive wizard that handles prerequisites, engine selection, secrets, and deployment in one go:

gh aw add-wizard githubnext/agentics/daily-repo-status

This pulls a pre-baked daily status report workflow from GitHub's template library, walks you through configuration, and triggers the first run. It's the fastest way to see an agentic workflow in action before writing your own.

You can also let AI write workflows for you. Point your favorite coding agent at the creation instructions and describe what you want automated. The agent will generate the Markdown file, validate it, and prompt you to review before committing.

Design Patterns Worth Exploring

Once you've got the basics working, the gh-aw documentation describes several patterns for structuring agentic automation at scale:

• DailyOps: Scheduled workflows for recurring reports, cleanup tasks, and health checks.
• IssueOps: Trigger agent actions from issue comments, turning issues into a command interface.
• ChatOps: Respond to slash commands in PR comments or issue threads.
• Orchestration: Chain multiple agent workflows together, where the output of one triggers the next.
• MultiRepoOps: Run the same agentic workflow across multiple repositories from a central control repo.

The mental model that works best: not one omniscient agent per repo, but many small, focused agents, each responsible for one chore. The same way you'd structure microservices.

What's Next

GitHub Agentic Workflows are still in technical preview, but the trajectory is clear. The teams behind gh-aw at GitHub Next and Microsoft Research are actively expanding the pattern into areas like continuous test improvement (in one experiment, test coverage went from ~5% to near 100% over 45 days with ~$80 in token costs), continuous security hygiene, and automated interaction testing.

The practical takeaway: start small. Pick one recurring task that drains your attention, something you'd love to never do manually again. Write a workflow for it. If it works, add another. If it doesn't, check the troubleshooting guide, tweak the instructions, and try again.

CI automated rule-based work over the past decade. Continuous AI is poised to do the same for judgment-based work. The tooling's here. The guardrails are solid. The only question is what you'll automate first.