为 GitHub Actions 构建 PR 描述 Agent

在本指南中，你将构建一个 GitHub Action，它使用 Mastra Agent 读取 pull request diff、生成多语言摘要，并直接写入 GitHub UI 中的 PR 描述。每当创建或更新 pull request 时，该 Action 都会运行，并随着 diff 变化重新生成描述。

这种方法与 CodeRabbit 和 Greptile 等 AI 驱动的 PR Tool 类似，但它使用原生 GitHub Actions Workflow 和 Mastra Agent 构建。

设置包括三个部分：

• 用于生成描述的 Mastra Agent
• 在 pull request 时触发的 GitHub Actions Workflow
• 将 Workflow 连接到 Agent 的 Node.js 脚本

最终的 Action 会写入包含英文、西班牙文和日文摘要的描述，并使用国旗 emoji 标记各语言，便于快速浏览。例如：

🇬🇧 English
This PR integrates Astro into the project, adding configuration files and updating scripts to support Astro development.

🇪🇸 Español
Este PR integra Astro en el proyecto, añadiendo archivos de configuración y actualizando scripts para soportar el desarrollo con Astro.

🇯🇵 日本語
このPRは、Astroをプロジェクトに統合し、Astro開発をサポートするための設定ファイルを追加し、スクリプトを更新します。

开始之前

• 一个 Mastra 项目（请参阅快速入门）
• 受支持的 Model Provider 提供的 API 密钥。如果没有偏好，可以使用 OpenAI
• Node.js v22.13.0 或更高版本

设置仓库 secret

Workflow 需要访问你的模型 Provider API 密钥。请在 GitHub 中将其添加为仓库 secret：

1. 在 GitHub 上打开你的仓库

2. 转到 Settings > Secrets and variables > Actions

3. 单击 New repository secret

4. 使用名称 OPENAI_API_KEY（或 Provider 对应的密钥名称）添加 API 密钥

   

Workflow 通过 ${{ secrets.OPENAI_API_KEY }} 引用该 secret，并在运行时将其提供给 Mastra Agent。

创建描述 Agent

PR 描述 Agent 负责将 git diff 转换成清晰、便于审查者阅读的 pull request 描述。

此 Agent 接收 pull request 的原始 diff。它会使用配置的语言生成描述，并用国旗 emoji 设置输出格式，以便在 PR 中快速浏览各语言部分。

src/mastra/agents/description-agent.ts

import { Agent } from '@mastra/core/agent'

export const descriptionAgent = new Agent({
  id: 'description-agent',
  name: 'PR Description Agent',
  instructions: `You are a helpful assistant that creates clear, concise PR descriptions.

When given a git diff of changed files, you will:
1. Analyze the changes to understand what was modified
2. Write a brief summary and list of changes
3. Output the same content in English, Spanish, and Japanese

Guidelines:
- Be concise but informative
- Focus on the "what" and "why" of changes
- Use technical terms appropriately
- Keep bullet points short and scannable
- Each language section should contain the same information, naturally translated

Output format:

### 🇬🇧 English

[1-2 sentence summary]

- [Change 1]
- [Change 2]
- [Change 3]

---

### 🇪🇸 Español

[Same summary in Spanish]

- [Same changes in Spanish]

---

### 🇯🇵 日本語

[Same summary in Japanese]

- [Same changes in Japanese]
`,
  model: 'openai/gpt-5.6-sol',
})

在本地测试 Agent

部署 Workflow 前，可以在 Studio 中测试 Agent，确认它能够正确生成描述。

1. 在任意公开 GitHub PR 的 URL 后添加 .diff，获取 diff：

   https://github.com/owner/repo/pull/123.diff

2. 在 Studio 中打开 PR Description Agent，然后使用以下提示词粘贴 diff 内容：

“请为以下更改创建 PR 描述。<paste the diff content here>”

Agent 会返回带有英文、西班牙文和日文部分的格式化描述。

GitHub Actions

GitHub Actions 会在 GitHub 基础设施上的短期环境中运行 Workflow。每次运行都会从一台干净的虚拟机开始，并检出你的代码。它会先安装依赖项，再运行 Workflow 步骤。运行完成后，环境会关闭。除非明确将内容保存为 artifact 或 cache，否则运行之间不会保留任何内容。

创建 Workflow

GitHub Actions Workflow 位于 .github/workflows 目录中。在项目根目录创建 .github 目录，然后在其中创建 workflows 目录。添加 pr-description.yml。

每当 pull request 被打开或更新时，此 Workflow 都会运行。它会为 PR 生成 diff，调用 Mastra Agent 描述变更，并直接将描述写入 GitHub UI 中的 PR。

.github/workflows/pr-description.yml

name: PR Description Generator

on:
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: read
  pull-requests: write

env:
  GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
  PR_DIFF_FILE: /tmp/pr_diff.txt
  PR_DESCRIPTION_FILE: /tmp/pr_description.md

jobs:
  generate-description:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'

      - run: npm ci

      - id: pr
        run: |
          BASE_REF=$(gh pr view ${{ github.event.pull_request.number }} --json baseRefName -q '.baseRefName')
          git fetch origin $BASE_REF
          git diff origin/$BASE_REF...HEAD -- . ':!package-lock.json' > $PR_DIFF_FILE

      - run: npx tsx .github/scripts/generate-description.ts

      - run: gh pr edit ${{ github.event.pull_request.number }} --body-file $PR_DESCRIPTION_FILE

Workflow 说明

• on: pull_request：在 pull request 被打开或更新时运行。
• permissions: pull-requests: write：允许 Workflow 更新 PR 描述。
• env：定义各步骤共用的文件路径，并从仓库 secret 中读取所需值，包括 Mastra Agent 使用的模型 API 密钥。
• actions/checkout@v4 + git 命令：检出完整的仓库历史记录，获取 PR 基础分支，并将 PR diff 写入 /tmp/pr_diff.txt。
• actions/setup-node@v4：设置 Workflow 使用的 Node.js 运行时。
• npm ci：根据 lockfile 安装仓库的 Node.js 依赖项。
• generate-description.ts：读取 /tmp/pr_diff.txt，调用 Mastra Agent，并将生成的描述写入 /tmp/pr_description.md。
• gh pr edit：使用 /tmp/pr_description.md 的内容更新 pull request 描述。

备注

Workflow 在生成 diff 时会排除 package-lock.json。lockfile 通常很大且包含大量干扰内容，将其纳入上下文可能会超出 Agent 的上下文窗口，并使生成的描述更难理解。

创建 Workflow 脚本

在 .github 中创建 scripts 目录，并添加 generate-description.ts。

该脚本会从 PR_DIFF_FILE 读取 PR diff，使用 Mastra Agent 生成描述，然后将结果写入 PR_DESCRIPTION_FILE，供 Workflow 发布到 pull request。

.github/scripts/generate-description.ts

import { readFileSync, writeFileSync } from 'fs'
import { mastra } from '../../src/mastra'

const agent = mastra.getAgent('descriptionAgent')

await agent.generate(
  `Please create a PR description for the following changes.

Git diff:
\`\`\`diff
${readFileSync(process.env.PR_DIFF_FILE!, 'utf-8')}
\`\`\``,
  {
    onError: () => {
      writeFileSync(
        process.env.PR_DESCRIPTION_FILE!,
        'This PR diff is too large to generate a description automatically.',
      )
    },
    onFinish: result => {
      writeFileSync(process.env.PR_DESCRIPTION_FILE!, result.text)
    },
  },
)

Workflow 脚本说明

• mastra.getAgent("descriptionAgent")：获取生成 PR 描述的 Mastra Agent。
• agent.generate(...)：从 PR_DIFF_FILE 读取 pull request diff，并让 Agent 编写 PR 描述。
• onError 回调：当 diff 过大而无法处理时，将回退消息写入 PR_DESCRIPTION_FILE。
• onFinish 回调：将生成的 PR 描述写入 PR_DESCRIPTION_FILE。

后续步骤

现在，你已经拥有一个使用 Mastra Agent 生成多语言 PR 描述的 GitHub Action。将 Workflow 和支持文件合并到主分支后，下次创建或更新 pull request 时，Agent 会自动运行。你可以在仓库的 Actions 选项卡中监控运行情况。

接下来，可以自定义 Agent instructions 或更改输出语言，也可以扩展 Workflow 以处理其他事件。

了解更多：

• 阅读 Agent 文档
• 为 Agent 提供 Tool，用于获取额外上下文
• 探索 issue 评论或 release 等其他 GitHub Actions 触发器