> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# 为 GitHub Actions 构建 PR 描述 Agent

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

这种方法与 [CodeRabbit](https://coderabbit.ai/) 和 [Greptile](https://www.greptile.com/) 等 AI 驱动的 PR Tool 类似，但它使用原生 GitHub Actions Workflow 和 Mastra Agent 构建。

设置包括三个部分：

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

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

```text
🇬🇧 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 项目（请参阅[快速入门](https://mastra.zisheng.pro/guides/getting-started/quickstart)）
- 受支持的 [Model Provider](https://mastra.zisheng.pro/models) 提供的 API 密钥。如果没有偏好，可以使用 [OpenAI](https://mastra.zisheng.pro/models/providers/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 密钥

   ![GitHub UI 中仓库 secret 的截图](/assets/images/github-action-repository-secrets-4e97642b3aa65178a3459a5deebe6f79.jpg)

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

## 创建描述 Agent

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

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

```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](https://mastra.zisheng.pro/docs/studio/overview) 中测试 Agent，确认它能够正确生成描述。

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

   ```text
   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。

```yaml
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。

```typescript
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](https://mastra.zisheng.pro/docs/agents/overview) 文档
- 为 Agent 提供 [Tool](https://mastra.zisheng.pro/docs/agents/using-tools)，用于获取额外上下文
- 探索 issue 评论或 release 等其他 [GitHub Actions 触发器](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows)