gh-aw: GitHub's next generation AI workflow engine, the AI abstraction layer developed by Don Syme

GitHub pulled another big move.

from GitHub Next and Microsoft Research joint project--gh-aw, has been achieved in a short period of time 4,300+ Stars。

Project warehouse: _ _ JHSNS _ URL _ 0 _ _

Technology Stack: Go 1.25.8
Current version: v0.67.3 (Technology Preview Phase)
Core contributors: Don Syme -Yes, the designer of the F#language and the originator of the async/await programming model.

This project is not simple. It's not another AI Code Review Bot, nor is it another"Writing YAML with AI"toys.

gh-aw is doing something more essential: defining workflows in the AI era and building a new set of abstraction layers.

What is it?

Let's give the simplest definition:

gh-aw is a gh CLI extension that compiles Markdown (.md file) written by humans in natural language into a machine-executable GitHub Actions workflow (.lock.yml file).

Markdown 文件（人类写的）
       ↓
   gh-aw 编译器
       ↓
GitHub Actions 工作流（机器跑的）

But this is just the surface. What really matters is the design philosophy behind it:

We should not use YAML to write workflows for AI. We should describe the workflow in human language and then let the compiler turn it into a machine-executable format.

This is a paradigm shift. used to be"People accommodate machines and write YAML that machines can understand"; now it is"Machines accommodate humans and compile natural language written by humans"。

Why is this important?

Before delving into the technical details, understand the background of the project.

Success and Limitations of GitHub Actions

GitHub Actions has been a huge success. Almost every open source project now uses it for CI/CD.

But it has a fundamental problem:YAML is written for people, not AI.

When you want AI to help you write a GitHub Actions workflow, you will encounter these problems:

1. AI doesn't know what custom Actions you have in your project
2. AI often uses non-existent parameters or outdated versions
3. The YAML format generated each time is different and difficult to maintain
4. If you change the requirements, AI will have to rewrite the whole thing, not incrementally modify it.
5. There is no type check. If you are wrong, you can only run it once to know it.

In other words,For AI, GitHub Actions is an assembly language with no type system, no standard library, and no compiler.

This is what gh-aw is trying to solve.

Don Syme's participation is of great significance

Don Syme 是谁？
- Designer of the F#programming language
- Proposer of the async/await asynchronous programming model (later borrowed by almost all languages such as C#, JavaScript, Python, Rust, etc.)
- A core contributor to the. NET platform
- Academician of Microsoft Research

he's not here to"join in the fun"of. His involvement in the project means that gh-aw is not a simple tool-it is exploring Programming paradigm in the AI era。

Just like when async/await redefined how we write asynchronous code, gh-aw may be redefining how we define workflows with AI.

Core concept: aw language

The core of gh-aw is a project called aw Domain Specific Language (DSL).

But what makes it special is that:The syntax of the aw language is Markdown.

one of the simplest examples

create a file ci.aw.md：

# CI Workflow

当有人提交 PR 或者推送到 main 分支时，运行这些步骤：

1. 签出代码
2. 安装 Node.js 20.x
3. 安装依赖：npm install
4. 运行测试：npm test
5. 如果测试通过，并且是 main 分支，部署到生产环境

Then run:

it generates a ci.aw.lock.yml The content of the document is roughly like this:

name: CI Workflow
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20.x
      - run: npm install
      - run: npm test
      - name: Deploy to production
        if: github.ref == 'refs/heads/main'
        run: npm run deploy

this looks like"AI-generated YAML"？Don't worry, look down.

The real magic: incremental compilation

Suppose you later changed the Markdown file:

# CI Workflow

当有人提交 PR 或者推送到 main 分支时，运行这些步骤：

1. 签出代码
2. 安装 Node.js 20.x
3. 安装依赖：npm install
4. 运行测试：npm test
+ 5. 运行 lint 检查：npm run lint
6. 如果测试通过，并且是 main 分支，部署到生产环境

And then you run it again gh aw compile。

gh-aw does not regenerate the entire file. It will understand what you changed and then incrementally modify YAML.

It knows:
- You added a new step
- This step should be after testing and before deployment
- No other steps need to be moved

This is the compiler and"AI blindly generated"the difference. The compiler has semantic understanding, state, and incremental compilation logic.

Type system and verification

gh-aw does not just throw your words to LLM and output YAML. It has a complete type system:

# Deploy Workflow

## 输入参数
- environment: [staging, production]  # 这是一个枚举类型，只能是这两个值之一
- dry_run: boolean = true              # 布尔类型，默认 true
- timeout: number = 30                 # 数字类型，默认 30 分钟

## 步骤
1. 部署到 {{ environment }} 环境，超时时间 {{ timeout }} 分钟
2. 如果不是 dry_run，发送通知到 Slack

When you compile, gh-aw does type checking:

$ gh aw compile deploy.aw.md

✅ 类型检查通过
✅ 生成 deploy.aw.lock.yml

If you pass an enumeration value that does not exist:

$ gh aw compile deploy.aw.md

❌ 类型错误
  Line 5: environment 参数值 "prod" 不是有效值
  有效值：staging, production

This is the true value of gh-aw. It is not a generator, it is a compiler.

Deep technical analysis

Let's take a look at the internal structure of this compiler.

Three-layer compilation architecture

The compilation process of gh-aw is divided into three levels:

┌─────────────────────────────────────────────┐
│  第一层：Markdown 解析器                      │
│  - 解析 Markdown 结构                        │
│  - 提取标题、列表、代码块、表格、参数定义       │
│  - 生成 AST（抽象语法树）                     │
└─────────────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────┐
│  第二层：语义分析器                           │
│  - 类型检查                                   │
│  - 依赖分析（步骤之间的顺序和依赖）           │
│  - 变量作用域解析                             │
│  - 错误检测和提示                             │
└─────────────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────┐
│  第三层：代码生成器                           │
│  - 生成 GitHub Actions YAML                  │
│  - 优化步骤顺序                               │
│  - 合并重复逻辑                               │
│  - 生成 .lock.yml 锁文件                      │
└─────────────────────────────────────────────┘

This is almost identical to the compiler architecture of traditional programming languages-except that the front-end input is not code, but natural language.

The Role of LLM: Semantic Understanding Engine

In this architecture, LLM is not an end-to-end black box generator, but a component in the compiler--Semantic understanding engine。

Its job is:
1. Translate the steps of natural language description into standardized operational semantics
2. Identify vague or ambiguous descriptions and ask users questions for clarification
3. Match the right actions from the GitHub Actions ecosystem

The key difference is that the output of LLM is a structured semantic representation rather than the final YAML.

自然语言描述："安装 Node.js 20.x"
       ↓ LLM 翻译
语义表示：{
  type: "setup-node",
  version: "20.x",
  cache: null,
  registry: null
}
       ↓ 代码生成器
最终输出：uses: actions/setup-node@v4
          with:
            node-version: 20.x

This design is very important because:
- Predictable: The same input will always produce the same output
- Testable: Unit tests can be written at the semantic layer
- Cacheable: LLM does not need to be called repeatedly for the same semantic
- Can be debugged: If something goes wrong, you know which layer of the pot it is on

The meaning of. lock.yml

You may have noticed that the file suffix generated by gh-aw is .lock.yml, rather than .yml。

this .lock Suffixes are not added casually. Like package-lock.json, Cargo.lock, and go.sum, it is alock file。

Its role is:
1. Guaranteeing reproducibility: The same input always produces the same output
2. Prevent drift: The LLM has been updated, or the Actions version has been updated, and it will not secretly change your workflow behavior
3. incremental update: Only the places you changed will change, and the places that have not changed will remain the same

This is a very mature software engineering practice, and gh-aw has brought it into the realm of AI workflows.

Modules and import systems

gh-aw Not every workflow is written from scratch. It has a complete module system:

# 我的工作流

@import: https://github.com/github/gh-aw/blob/main/library/node/ci.aw.md
@import: ./custom-steps.aw.md

## 步骤
1. @node/ci(version="20.x")  # 导入的标准模块
2. @custom/my-step()         # 自定义模块
3. 运行我的自定义命令

This means that you can build a library of reusable workflow components. Teams can define their own standard workflows that everyone can import and use instead of copy-and-paste YAML.

This is engineering AI. Instead of letting AI invent wheels from scratch for every task, let AI help you assemble standard components.

typical use scenario

Scenario 1: Project initialization

To start a new project, you no longer need to copy and paste the CI configuration of the old project:

# Rust 项目 CI

对于这个 Rust 项目：

1. 提交 PR 时运行 cargo test 和 cargo clippy
2. 每天晚上运行 cargo audit 检查安全漏洞
3. 打 tag 时自动发布到 crates.io
4. 所有失败都通知到团队 Discord

Compiled with one line of commands and can be used directly.

Scenario 2: Complex release process

# 发布流程

当有人在 Issue 里留言 "/release" 时：

1. 检查这个人是不是有发布权限
2. 创建发布分支 release/vX.Y.Z
3. 更新 CHANGELOG.md 和版本号
4. 跑一遍完整的测试套件
5. 打 Git tag
6. 发布到 GitHub Releases
7. 部署到预发布环境
8. 等待 1 小时，如果没有问题，自动部署到生产环境
9. 发送发布通知到 Slack
10. 如果任何一步失败，自动回滚，并创建 Issue 记录

In the past, writing such a workflow might take a day, and it was easy to write it incorrectly. Now it's ready in 5 minutes.

Scenario 3: Cross-project standardization

The team has 50 warehouses, and the CI of each warehouse is similar but slightly different. In the past, you needed to use setup script or template engine to maintain it.

Now you can write a standard library:

# 团队标准 CI 库

## 函数 standard-ci(language)
- 标准的签出和缓存配置
- 标准的测试运行步骤
- 标准的代码质量检查
- 标准的通知配置

Then each project only needs to:

# 项目 CI

@import: https://github.com/my-org/aw-library/standard.aw.md

@standard-ci(language="python")

Defined once, used everywhere. The compiler ensures that every project meets team standards.

Why is this a big event?

gh-aw seems to be just a"Compile Markdown to YAML"is a gadget, but its significance goes far beyond that.

1. A new paradigm for AI programming

The model for most AI programming tools today is:

You say requirements → AI generates code → you check code → merge

This model has a fatal problem:Generation is easy and maintenance is difficult.

What if needs change? AI recreates it for you again, and you have to check it again. No increments, no state, no version management.

gh-aw proposes a new model:

You write the high-level description (Markdown) → the compiler generates low-level code (YAML) → the compiler is responsible for incremental updates

This is the same reason as we compile it into machine code in a high-level language. You don't need to understand assembly to write C code; the compiler helps you translate it into assembly. If something goes wrong, you can change the C code and compile it again. There is no need to change the assembly.

This is what AI programming should look like.

2. Don Syme is playing a big game of chess

Everything Don Syme has done in his life is essentially doing one thing:Invent better abstractions so that programmers don't have to worry about underlying complexity.

• He invented F#to make functional programming practical
• He invented async/await to make asynchronous programming simple
• Now he is doing gh-aw to make AI workflow programming easier

The underlying logic for all three things is the same: find the right abstraction and hide complexity behind the compiler.

If gh-aw's idea succeeds, its impact will not be limited to GitHub Actions. It may be extended to:
- Terraform Infrastructure Definition
- Kubernetes deployment configuration
- CI / CD system
- Anything defined in YAML

3. GitHub's niche advantages

GitHub has unique advantages in doing this:

• It knows all the GitHub Actions in the world
• It knows the usage, parameters, version, popularity of each Action
• It knows what actions are used for each project
• It knows what workflow models are industry best practices

gh-aw is not built out of thin air. Behind it is data from the entire GitHub ecosystem. This is something no other company can do.

Current limitations and future prospects

gh-aw is still in the technical preview stage (v0.67.3), and there are still many imperfections:

Current limitations

1. Support scenarios are still limited: Mainly covering common scenarios of CI/CD, complex workflows cannot be handled well
2. LLM costs: Compilation requires a call to LLM. Although there is a cache, there is still a cost
3. of interpretability: Sometimes you don't know why it generated something and need better debugging tools
4. The ecology is still very small: There are not many module libraries yet and it takes time to grow

Possible future directions

1. Multiple backend support: Now only compiled to GitHub Actions, and may support GitLab CI, CircleCI, Jenkins, etc. in the future
2. A richer type system: More powerful abstraction capabilities such as generics, interfaces, inheritance, etc.
3. bidirectional compilation: Not only can you compile from.md to.yml, you can also decompile back to.md from an existing.yml
4. AI-assisted reconstruction: Automatically discover problems in your workflow and suggest optimization solutions
5. visual editor: Drag, drag, drag, drag workflow to automatically generate Markdown descriptions

How to start using it?

installation

# 首先你需要安装 GitHub CLI
# 然后安装 gh-aw 扩展
gh extension install github/gh-aw

Create your first workflow

create a file .github/workflows/ci.aw.md：

# CI Workflow

当有人提交 PR 或者推送到 main 分支时：

1. 签出代码
2. 安装 Go 1.22
3. 运行测试：go test ./...
4. 运行 lint：golangci-lint run

compilation

gh aw compile .github/workflows/ci.aw.md

Then submit the generated .lock.yml File to Git. It's that simple.

other commands

# 检查工作流是否有问题，不生成文件
gh aw check ci.aw.md

# 显示编译后的工作流预览
gh aw preview ci.aw.md

# 更新已有的工作流（增量编译）
gh aw update ci.aw.md

written in the end

gh-aw is the kind of thing that looks at first glance"Isn't it just AI that generates YAML?", but the more you think about the project, the more interesting it is.

Its true value is not"Saved time writing YAML", but it raises a question:

In the AI era, how should we define programs?

Fifty years ago, we wrote programs in assembly language.
Thirty years ago, we wrote programs in C.
Ten years ago, we wrote programs in Python/JavaScript.

Today, we may need a new way to write programs-a way that is closer to human natural language, but maintains all the best practices of software engineering (type systems, module systems, incremental compilation, locking files, testable, debugatable).

gh-aw is a serious exploration in this direction. And it's not a toy for a startup, it's made by world-class programming language experts like GitHub Next + Microsoft Research + Don Syme.

This may not be the final answer, but it is definitely the right direction.

In the next few years, we will see more such explorations. Tools that truly combine the wisdom of software engineering with the capabilities of AI will define the programming paradigm for the next decade.

reference resource

1. gh-aw official warehouse - _ _ JHSNS _ URL _ 0 _ _
   Project source code, including documentation and examples

2. GitHub Next official introduction - _ _ JHSNS _ URL _ 0 _ _
   Project introduction article from GitHub Next team

3. Don Syme - The Next Big Programming Model
   Don Syme's speech on future programming models, including gh-aw design ideas

4. GitHub Actions Official Document - _ _ JHSNS _ URL _ 0 _ _
   GitHub Actions 完整文档，理解 gh-aw 的底层基础

作者: itech001
来源: 公众号：AI人工智能时代
网站: https://www.theaiera.cn/
每日分享最前沿的AI新闻资讯和技术研究。

本文首发于 AI人工智能时代，转载请注明出处。