GitHub's Agentic Workflows

June 23, 2026·5 min read

There's a category of work that lives in every repo that nobody actually wants to do. Updating the README after the API changes. Fixing twelve broken links that crept in over six months. Regenerating the architecture slides before the quarterly review. It's not hard. It's just relentless and invisible until someone notices it's wrong.

GitHub Agentic Workflows are GitHub's answer to that. They're currently in public preview.

What They Are

Regular GitHub Actions automation is deterministic. You define steps, a runner executes them, done. It doesn't reason—it does what you told it.

Agentic workflows are Markdown files that live in .github/workflows/ alongside your regular YAML. Instead of scripted steps, you describe what you want in natural language. When the workflow runs, a coding agent—Copilot CLI, Claude Code, or OpenAI Codex—reads the repo, figures out what to do, and opens a PR.

Traditional Workflow                Agentic Workflow
─────────────────────────           ──────────────────────────
Trigger → Fixed Steps → Done        Trigger → Agent reads repo
                                               Agent forms plan
                                               Agent edits files
                                               Agent runs tests
                                               Agent opens PR
                                               You review + merge

The format is a Markdown file with a YAML frontmatter block. Frontmatter handles the trigger, permissions, tools, and what the agent is allowed to output. The Markdown body is the instruction:

---
on:
  schedule: daily

permissions:
  contents: read
  issues: read
  pull-requests: read

safe-outputs:
  create-issue:
    title-prefix: "[report] "
    labels: [automated]

tools:
  github:
---

# Daily Repo Status Report

Create a daily status report for maintainers. Include recent activity,
open PRs worth reviewing, and any CI failures that need attention.
Keep it concise and link to the relevant issues/PRs.

The safe-outputs block is what keeps it from going rogue. Write operations—creating PRs, posting comments, opening issues—have to be explicitly listed. Anything not in that list the agent can't do. PRs are never auto-merged.

Setting One Up

GitHub Agentic Workflows are in public preview. Once you're in, install the CLI extension:

gh extension install github/gh-aw

The easiest way to write your first workflow is to ask a coding agent to do it:

Generate a workflow that checks for broken links in my docs weekly.
Use the instructions at https://github.com/github/gh-aw/blob/main/create.md

It drafts the Markdown file and a corresponding .lock.yml that GitHub Actions actually executes. Review both, then compile and push:

gh aw compile
git add .github/workflows/check-links.md .github/workflows/check-links.lock.yml
git commit -m "add: broken link check workflow"
git push

AGENTS.md

Drop an AGENTS.md in the repo root. The agent reads it at the start of every task—what it can touch, what it can't, any style rules:

# AGENTS.md

## What you can change
- `docs/` — All Markdown documentation
- `README.md` — Top-level readme
- `CHANGELOG.md` — Add entries, never modify existing ones

## What you must not touch
- `environments/` — Terraform configs, changes here deploy to production
- `.github/workflows/` — Workflow changes require human review

## Style
- Sentence case for headings
- External links must use HTTPS
- Code examples must be runnable before including them

This is also where structured documentation frameworks like Diataxis pay off. If your docs follow a consistent structure—tutorials, how-tos, reference, explanation—you can tell the agent exactly which sections are safe to update automatically. Reference tables: fine. Conceptual explanation: probably leave that to a human.

Scheduling

Any trigger GitHub Actions supports works in the frontmatter:

---
on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday at 9am
  workflow_dispatch:

permissions:
  contents: read
  pull-requests: write

safe-outputs:
  create-pull-request:
    title-prefix: "[automated] "
    base-branch: main
    labels: [documentation, automated]

tools:
  github:
  shell:
---

# Weekly Documentation Refresh

Review all documentation in `docs/` for:
- Broken or outdated external links
- Version numbers that don't match `package.json`
- API endpoints or config keys that no longer exist in the codebase

Fix what's mechanical. Flag anything requiring judgment with a
`<!-- TODO: verify -->` comment. Open a pull request with all changes
and a summary of what was updated and why.

Some Things Worth Building

Broken Link Repair

---
on:
  schedule:
    - cron: '0 8 * * 0'
  workflow_dispatch:

permissions:
  contents: read
  pull-requests: write

safe-outputs:
  create-pull-request:
    title-prefix: "[automated] "
    labels: [documentation, automated]

tools:
  shell:
  github:
---

# Broken Link Repair

Install markdown-link-check. Scan all Markdown files for broken external links.
For each broken link: find the new URL if the content moved, remove the hyperlink
but keep the text if the page is gone, or add a <!-- TODO: verify --> comment if
the entire reference is outdated. Open a pull request with all fixes.

Documentation Freshness

Docs drift. API docs reference endpoints that were renamed. Setup guides reference package versions from two releases back. Nobody notices until someone follows the guide and it breaks.

---
on:
  schedule:
    - cron: '0 9 * * 1'
  workflow_dispatch:

permissions:
  contents: read
  pull-requests: write

safe-outputs:
  create-pull-request:
    title-prefix: "[automated] "
    labels: [documentation, automated]

tools:
  shell:
  github:
---

# Documentation Freshness Check

Review all documentation in docs/ against the current codebase. Find anywhere
the docs describe behavior, APIs, or configuration that no longer matches the
actual code. Update the docs to match. Do not rewrite prose—only fix factual
inaccuracies. Include a list of every change with before/after.

If your docs follow Diataxis—tutorials, how-tos, reference, explanation—you can scope it to just the reference section and keep the risk low.

PowerPoint Updates

The agent can edit .pptx files directly using python-pptx. Point it at your architecture deck and the current infrastructure config and it'll update slide text to match.

---
on:
  workflow_dispatch:

permissions:
  contents: read
  pull-requests: write

safe-outputs:
  create-pull-request:
    title-prefix: "[automated] "
    labels: [slides, automated]

tools:
  shell:
  github:
---

# Architecture Slide Refresh

Install python-pptx. Open `docs/slides/architecture.pptx` and read the current
slide content. Compare service names, topology, and component labels against the
current infrastructure configuration in `environments/`.

For each slide where the content no longer matches reality:
- Update service names, counts, and connection labels to match current config
- Do not change layout, styling, or colors—only text content

Save the updated file. Open a PR with before/after notes for each changed slide.

Changelog Generation

---
on:
  workflow_dispatch:

permissions:
  contents: read
  pull-requests: write

safe-outputs:
  create-pull-request:
    title-prefix: "[automated] "
    labels: [changelog, automated]

tools:
  shell:
  github:
---

# Changelog Generation

Look at the git log since the last tagged release. Group commits by type:
features, fixes, breaking changes, internal. Generate a new CHANGELOG.md entry
following the existing format. Do not modify any previous entries.

Security Advisory Response

---
on:
  issues:
    types: [opened]

permissions:
  contents: read
  issues: write
  pull-requests: write

safe-outputs:
  create-pull-request:
    title-prefix: "[security] "
    labels: [security]
  add-issue-comment: true

tools:
  shell:
  github:
---

# Security Advisory Response

A security advisory has been filed. Review whether this repo uses the affected
package and the affected API surface. If affected: describe the exposure in
plain language, propose a fix, implement it if mechanical, open a PR with a
security label. If not affected, comment on the issue with an explanation.

README Hygiene

---
on:
  schedule:
    - cron: '0 9 * * 1'

permissions:
  contents: read
  pull-requests: write

safe-outputs:
  create-pull-request:
    title-prefix: "[automated] "
    labels: [documentation, automated]

tools:
  shell:
  github:
---

# README Hygiene

Review README.md against the current state of the repo. Update the getting started
section to match current setup steps, fix any command-line examples that no longer
work, and update the architecture overview if the major components have changed.
Do not change the introduction, contributing guidelines, or overall structure.

Where It Falls Down

It can't reach your production systems or query live observability data unless you wire that up via tools in the frontmatter. It'll make confident decisions on open-ended architecture questions, which isn't always what you want. And the vaguer the instruction, the more variable the output—same as any AI task.

The more specific the instruction and the more bounded the scope, the more predictable the result.

Tags:

#github #github-actions #github-copilot #ai #devops #automation #platform-engineering #agents #developer-tools

Enjoyed this post? Give it a clap!