Someone opened an issue on one of my RateMy repos last week that just said “doesn’t work” with a screenshot of a blank page. No browser, no tenant size, no idea which of the three apps it even was. I asked the usual questions, waited two days, got the details, and it turned out to be a permissions problem that’s already in the README. That whole exchange is about forty minutes of my attention spread across a week, and it’s the same forty minutes on every repo I look after. It is exactly the sort of chore I’d hand to an agent if I trusted it to only do the boring part and not start rewriting my code at midnight.
GitHub Agentic Workflows is GitHub Next’s answer to that, and the thing that made me actually try it is the sample pack that goes with it. This post is about both: what an agentic workflow is, where the samples live, and a close look at the one I started with, which is the issue triage workflow.
What an agentic workflow is#
The short version is that you write a GitHub Actions workflow in markdown instead of YAML. The file has a YAML front matter block that says when it runs, what it can read and what it’s allowed to write, and underneath that is a plain English prompt telling an AI agent what to do. A CLI extension called gh aw compiles that markdown into a normal, pinned Actions workflow with a .lock.yml suffix, and that compiled file is what GitHub Actions actually runs. You commit both.
The part that persuaded me it wasn’t a toy is the write model. The agent job itself is read-only. If you want it to add a label or post a comment, you declare that under a safe-outputs block with a maximum count, and a separate job with its own scoped permissions applies those writes after the agent has finished. So a workflow that’s allowed to add four labels and one comment can’t suddenly decide to close the issue or push a commit, however excited the model gets. There’s also a staged: true mode that previews every write without doing any of them, which is how I’d run anything for the first fortnight.
It supports several engines. The docs list GitHub Copilot, Claude Code, OpenAI Codex, Google Gemini and something called Pi, with Google’s Antigravity marked experimental, and the front page also mentions Kiro, OpenCode and Cursor as unsupported samples. I went with Copilot, because that’s what I already pay for and it means one less API key in the repo secrets.
The whole thing comes out of GitHub Next and Microsoft Research and the docs call it a technical preview. The README is blunt about it: use with caution, at your own risk, and keep a human supervising. I’d take that at face value.
The sample pack#
The repo to look at is githubnext/agentics, which describes itself as “a sample pack of GitHub Agentic Workflows”. It’s MIT licensed and there are a lot more workflows in there than I expected. Roughly, they fall into groups:
- Maintainer chores: Issue Triage, Repo Assist (a much broader one that investigates and fixes), and an AI Moderator for spam.
- CI and cost: CI Doctor investigates failing runs, CI Coach tries to make them cheaper, and Cost Tracker posts what each agent run cost on the PR.
- Code review: a Grumpy Reviewer, a PR Nitpick Reviewer, and a couple that check PRs against your contribution guidelines.
- Status and planning: daily and weekly repo status reports, a Daily Plan, a Weekly Research digest.
- Documentation: an updater that runs on push to main, a link checker, a markdown linter, a glossary maintainer, and one called Documentation Unbloat that I’m tempted to point at this blog.
- Code improvement: some report only (accessibility review, large file simplifier), and some that open PRs (duplicate code detector, test improver, perf improver).
- Slash commands:
/archiedraws Mermaid diagrams of how issues relate,/planbreaks an issue into sub-tasks, and PR Fix tries to repair failing checks. - Security: a daily malicious code scan and a VEX generator for dismissed Dependabot alerts.
The ones that open PRs are where I’d be most careful, and I’d read the full markdown of any of them before adding it. But the point of the pack is that you don’t start from a blank prompt. Each sample has a docs page describing what it does, what it needs, and the one-liner to add it. There are also shared fragments you can import, such as a Microsoft Docs MCP server block, so your own workflows can look things up on Learn.
Adding the issue triage workflow#
The install is two commands. From the root of the repo you want it in:
gh extension install github/gh-aw
gh aw add-wizard githubnext/agentics/issue-triageThe wizard checks you have Actions enabled and a recent GitHub CLI, asks which engine you want, sorts out authentication, and adds both the .md source and the compiled .lock.yml to .github/workflows/, either as a direct push or a PR. For Copilot there are two routes: organisation billing with a copilot-requests: write permission, or a fine-grained PAT with Copilot Requests set to Read, stored as a secret called COPILOT_GITHUB_TOKEN. For Claude it’s an ANTHROPIC_API_KEY secret, and the quickstart is explicit that a subscription token from claude login is not supported, so don’t try. The docs also say the CLI wants Linux, macOS, or Windows with WSL.
If you’d rather see what you’re getting before you run anything, the source is a single file: workflows/issue-triage.md. Here is its front matter, as it stood when I pulled it:
on:
issues:
types: [opened, reopened]
reaction: eyes
permissions:
contents: read
issues: read
safe-outputs:
add-labels:
allowed:
- bug
- feature
- question
- needs-info
- priority/p0
- priority/p1
- priority/p2
- duplicate
- invalid
- spam
max: 4
add-comment:
max: 1
set-issue-type:
max: 1
timeout-minutes: 10Read that as a contract. It fires on opened and reopened issues only, so you can’t start it by hand. It reads contents and issues and nothing else. It may apply up to four labels from a fixed list, post one comment, set the issue type once, and it gets ten minutes. The reaction: eyes line puts the eyes reaction on the issue while it’s working, which is a small touch I liked more than I expected to. There’s no engine: key in the file, so the engine comes from whatever you chose in the wizard or your repo defaults.
What the prompt actually tells it to do#
The prompt body is the interesting bit, because it’s where the sample pack earns its keep. It’s a maintainer’s checklist written out in full.
It starts by telling the agent to work only from the issue, its comments and the repo, and not to invent details. Then it gathers context: read the issue, look at which labels and issue types exist, search open and recently closed issues for the same symptoms, and check the docs where they clarify expected behaviour. That last step is the one that would have saved me the README round trip.
Next it assesses completeness. A bug needs repro steps, expected and actual behaviour, logs and environment; a feature needs the problem, the desired outcome and the scope. If things are missing it applies needs-info, asks specific questions and does not guess the type or priority. For obvious spam or gibberish it applies spam or invalid and stops.
Only if the issue is complete does it classify. One type label at most, one priority label at most. The priorities are defined in the prompt: p0 is an active security incident, severe data loss or broad outage; p1 is a major regression or a blocker with no reasonable workaround; p2 is normal work. There’s a line in there I’d copy into every prompt I write from now on: labels can trigger other automation, so prefer leaving one unset over applying it speculatively.
Duplicate detection is deliberately conservative. “Duplicate” means high confidence and a cited issue number, “related” is mentioned in the report but not labelled, three matches at most, and it is told never to mark a duplicate on similar words in the title alone. It also classifies whether the issue is suitable for handing to the Copilot coding agent, needs more information, or needs a maintainer’s judgment, without writing a speculative implementation plan.
Then it posts one comment headed “Triage report” with a short summary and a table of type, priority and coding agent suitability, each with its reasoning, followed by an optional list of similar issues and a next step. For an incomplete issue the table is replaced by the clarifying questions. On my “doesn’t work” issue that comment would have gone out within a few minutes of it being opened, and the reporter would have had the questions before I’d even seen the notification.
Making it fit your repo#
The one thing you must do before it runs for real is make sure the labels in the allowed list exist in your repo, or edit the list to match the labels you actually use. The safe-outputs job won’t invent labels. My repos use enhancement rather than feature and have no priority labels at all, so the list gets trimmed to the four I care about and the priority definitions in the prompt rewritten to match before it goes anywhere near a real issue. After editing you run gh aw compile and commit both the markdown and the regenerated lock file to the default branch.
Keeping it current is three commands, from the agentics README:
gh extension upgrade github/gh-aw
gh aw upgrade
gh aw updateThe first updates the CLI, the second moves your workflows to the latest engine version, and the third pulls in changes to any sample workflows you added.
Caveats#
This is a technical preview from a research group, and it moves. The gh-aw README mentions a security advisory where a range of versions was retired pre-emptively, which is reassuring in that they’re paying attention and a reminder that you need to keep the extension updated.
Cost is real but bounded. There are max-ai-credits and max-daily-ai-credits settings with defaults of 1,000 per run and 5,000 per workflow per day, where one credit is a cent. A busy repo could still spend a few dollars a day on triage alone, so look at gh aw logs after the first week.
The agent can only be as good as the prompt and the labels you give it. I’d expect a few wrong needs-info calls early on where the reporter did include enough detail and the model wanted more. The docs are honest that a human still reviews the reports and overrides the decisions, and the one-comment limit means at least it can’t argue with you.
And I haven’t tried the ones that open pull requests. Triage is low stakes. Something that edits code and raises a PR on a schedule is a different conversation, and one I’d want staged mode on for a long time first.
Final thoughts#
Pick one repo where issues arrive faster than you read them, run the add wizard for the issue triage workflow with staged mode on, and watch what it would have done for a week. If the labels it proposes match what you’d have picked, switch staging off and let it post. If they don’t, the whole workflow is one markdown file, and fixing it is a matter of editing a paragraph rather than learning a framework.
