Agentic Workflows

Software collaboration keeps evolving. With Continuous AI, GitHub Next are exploring how LLMs can help teams with documentation, quality, triage, and more. Agentic Workflows is a follow‑up exploration: a research demonstrator focused on expressing repository‑level behaviors in natural language and running them on GitHub. Agentic Workflows is not a product and not even a technical preview; it's a vehicle for learning, exploring the agentic design space, and mapping what works (and what doesn't) in day‑to‑day repositories.

What are Agentic Workflows?

Agentic Workflows are a form of natural language programming over GitHub. Instead of writing bespoke scripts that operate over GitHub using the GitHub API, you describe the desired behavior in plain language. This is converted into an executable GitHub Actions workflow that runs on GitHub using an agentic "engine" such as Claude Code or Open AI Codex. It's a GitHub Action, but the "source code" is natural language in a markdown file.

Critically, agentic workflows are compiled to existing GitHub Actions workflows (YAML). In this research demonstrator, you use the gh aw GitHub CLI extension to perform a short, simple, manual compile step to generate the Actions workflow. In the future, we envisage that it may be possible to simply commit a markdown file to .github/workflows, and agentic things "start happening." Just like YAML files on GitHub Actions today.

The design of Agentic Workflows takes an "Actions-first" approach to the agentic design space. This means the design aligns with familiar concepts from GitHub Actions: repo‑centric execution, team‑visible logs, permissions, partial sandboxing of execution, secrets, environments, triggers, security controls, and job semantics stay as with GitHub Actions. Because Agentic Workflows build on top of GitHub Actions rather than around it, the organization can audit the workflows, version them, and reuse established tools and patterns. Agentic Workflows provide a clearer, more declarative way to express what some users are already doing on GitHub Actions today.

A minimal example

Below is a minimal agentic workflow that keeps documentation up to date. This is just a simple example to illustrate the syntax; a more complete example is available in the examples repository. This is a demonstrator sample and is not for production use.

---
on:
  push:
    branches: [main]

permissions:
  contents: write # needed to push changes in preparation for the pull request
  pull-requests: write # needed to create pull requests for the changes

tools:
  github:
    allowed:
      [
        create_or_update_file,
        create_branch,
        delete_file,
        push_files,
        create_pull_request,
      ]
  claude:
    allowed:
      Edit:
      MultiEdit:
      Write:
      WebFetch:
      WebSearch:
---

# Documentation Updater

You are a technical writer. Your job is to make the documentation in the repository ${{ github.repository }} _excellent_.

Steps:

1. Analyze Repository changes. On every push to the main branch, examine the diff to identify changed/added/removed entities.
2. Review existing documentation for accuracy and completeness. Identify documentation gaps including missing or outdated sections.
3. Update documentation as necessary.
4. Create a new branch and push changes.
5. Create a pull request with a clear description of the changes.
6. Request reviews from relevant team members or stakeholders.

Note that the triggers, permissions and tools are all made clear and explicit in the definition of the workflow. For triggers: and permissions:, the exact GitHub Actions specifications you are already familiar with are used. For tools: a new declaration form is used. This is followed by the natural language program.

Design philosophy

• GitHub‑native. Agentic Workflows assume access to the GitHub ecosystem, including MCP‑based tools and GitHub‑specific conveniences like ai-reaction, automatic upload of logs, and built‑in job control/reporting.

• Model and engine independence. An agentic workflow is largely independent of the underlying LLM and the agentic engine. You shouldn't have to rewrite your workflows to move from Claude Code to Codex.

• Actions alignment. Repo‑centric, team‑visible, auditable. We inherit Actions' ergonomics and compile down to Actions YAML so everything remains transparent and source‑controlled.

• Shareable pieces. You can publish and consume packages of workflows, as well as share tool specifications, so teams can standardize and remix.

• You're in control. There are no hidden prompts or secret sauce. You can inspect the generated YAML and own the behavior end‑to‑end.

Multi‑engine by design

Agentic Workflows are engine‑neutral. They support multiple agentic engines, including Claude Code and OpenAI Codex. Because the natural‑language "program" is decoupled from the engine, you get portability: keep your workflow, swap your engine, compare results.

Where natural language shines

Natural‑language programming works best where a bit of productive ambiguity helps. A human teammate understands instructions like "read the coverage report and write tests to improve coverage." That's not a line‑by‑line spec, but it is a useful direction for an agent to take initiative. Agentic Workflows are built to express those kinds of intentions cleanly, and then run them safely in a team context with logs, guardrails, and review.

How it fits with Continuous AI

Continuous AI is our umbrella project opening the door for the industry to a new era of AI‑enriched automation in software collaboration. Agentic Workflows are one concrete demonstrator of how some of that workload can be implemented on GitHub today. If Continuous AI is the category, Agentic Workflows are one way of doing it, focusing on clarity, control, and reuse.

What can be built with Agentic Workflows

We're especially excited about use cases that help open‑source maintainers and team health:

• Issue triage and labeling. Keep the queue tidy, summarize conversations, route work, and suggest next actions.

• Continuous QA. Propose targeted test cases, run selective checks, and file PRs that improve robustness.

• Accessibility review. Continuously scan code and docs, raise actionable issues, and open PRs with suggested fixes.

• Continuous documentation. Improve README fragments and API docs as code evolves; nudge authors when explanations drift.

• Continuous test improvement. Suggest new tests based on coverage reports, and code changes.

These are the important (and unglamorous) tasks that help projects scale. They're also ideal for agentic automation because they're repetitive, collaborative, auditable, and cannot be expressed as simple heuristics — they benefit from a touch of judgment and careful fitting into the team's workflow.

We've created a number of demonstrator workflows to illustrate these use cases and published them at github.com/githubnext/agentics. These examples show how to automate common tasks, such as triaging issues, improving documentation, and enhancing code quality. They serve as a reference point for teams to explore how agentic natural language programming is relevant to their own repositories.

Built on what you already use

Agentic Workflows stand on the shoulders of the ecosystem: GitHub Actions, MCP‑enabled tools, and AI providers. We embrace the community around LLM frameworks, tools, and actions. Agentic Workflows don't replace those pieces, they compose them into something easier to author, share, and reason about from inside your repo.

Security and safety

Security is foundational — Agentic Workflows inherit GitHub Actions' sandboxing model, scoped permissions, and auditable execution. The attack surface of agentic automation can be subtle (prompt injection, tool invocation side‑effects, data exfiltration), so we bias toward explicit constraints over implicit trust: least‑privilege tokens, allow‑listed tools, and execution paths that always leave human‑visible artifacts (comments, PRs, logs) instead of silent mutation.

A core reason for building Agentic Workflows as a research demonstrator is to closely track emerging security features in agentic engines. With Agentic Workflows we can assess these features under near‑identical inputs, so differences in behavior and guardrails are comparable. Additionally, the "compilation" process of Agentic Workflows enforces additional security checking suitable for the GitHub Actions context, for example highly restricted context substitutions. We are in active conversations with providers of agentic engines to increase and improve the security-related offerings available in the engines. Alongside engine evolution, we are working on our own additional mechanisms including MCP proxy filtering, container-configuration and hooks‑based security checks that can veto or require review before effectful steps run.

We aim for strong, declarative guardrails — clear policies the workflow author can review and version — rather than opaque heuristics. Lock files are fully reviewable so teams can see exactly what was resolved and executed. This will keep evolving; we would love to hear ideas and critique from the community on additional controls, evaluation methods, and red‑team patterns.

Prior work

Agentic Workflows build on what we learned in earlier GitHub Next projects. It's a descendant of SpecLang, which explored end‑to‑end development from a structured, Markdown‑like "spec" that serves as the program's source of truth. It's also inspired by Copilot Workspace, where we frequently discussed the need to continuously automate tasks like documentation and test improvement.

We use both Claude Code and Codex directly. We have been inspired by Claude Code GitHub Actions and the SuperClaude Framework. SuperClaude includes the convenient @include syntax for composing Markdown prompts from reusable fragments. That idea of modular, shareable building blocks shows up in Agentic Workflows' design for sharing tool specs and workflow components.

We were also directly inspired by Agentic Workflow Definitions project by @danielmeppiel, which informed parts of this project's premise and design.

Why a research demonstrator (and not a product)?

Because we are still learning. There are sharp edges around resource limits, tool reliability, evaluation, and safety. We're optimistic that these seams will tighten, perhaps one day something like Agentic Workflows are integrated directly into GitHub.com, but we're not there yet. Shipping a research demonstrator facilitates conversations with providers of agentic engines, product designers, and the GitHub Community. This lets us learn out in the open with you: what abstractions stick, what stays portable across engines, and what governance and UX patterns teams actually need.

Get involved

• Explore the repos: github.com/githubnext/gh-aw; examples at github.com/githubnext/agentics.

• Read the README for setup details, examples, and the design rationale.

• Try a workflow in a test repo. Start small, keep the agentic step focused, and wire it to a low‑risk trigger.

• Share feedback on what's confusing, what's missing, and what patterns you'd like to reuse across repos. Please file issues in github.com/githubnext/gh-aw and chat with us in the Continuous AI channel in the Next Discord server.

Agentic Workflows is an invitation to help invent the next layer of repo automation, one that's conversational, auditable, and works the way teams actually collaborate. We're excited to explore with you.