> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/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 會寫入包含英文、西班牙文及日文摘要的描述，每個語言部分均以旗幟表情符號標示，方便快速瀏覽。例如：

```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/zh-HK/guides/getting-started/quickstart)）
- 受支援的[模型 Provider](https://mastra.zisheng.pro/zh-HK/models) 所提供的 API 金鑰。如沒有偏好，可使用 [OpenAI](https://mastra.zisheng.pro/zh-HK/models/providers/openai)
- Node.js `v22.13.0` 或更新版本

### 設定儲存庫機密

Workflow 需要存取模型 Provider 的 API 金鑰。請在 GitHub 中將它加入為儲存庫機密：

1. 前往 GitHub 上的儲存庫

2. 前往 **Settings** > **Secrets and variables** > **Actions**

3. 按一下 **New repository secret**

4. 加入 API 金鑰，名稱設為 `OPENAI_API_KEY`（或 Provider 所使用的適當金鑰名稱）

   ![GitHub UI 中儲存庫機密的畫面截圖](/zh-HK/assets/images/github-action-repository-secrets-4e97642b3aa65178a3459a5deebe6f79.jpg)

Workflow 以 `${{ secrets.OPENAI_API_KEY }}` 參照此機密，並在執行期間將它提供給 Mastra Agent。

## 建立描述 Agent

PR 描述 Agent 負責將 git diff 轉換為清晰且方便審閱者閱讀的 Pull Request 描述。

這個 Agent 會接收 Pull Request 的原始 diff。它會以設定的語言產生描述，並使用旗幟表情符號格式化輸出，讓 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/zh-HK/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 步驟。執行完成後，環境便會關閉。除非你明確將內容儲存為成品或快取，否則不會有任何內容保留至下次執行。

### 建立 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`**：定義各步驟共用的檔案路徑，並從儲存庫機密讀取所需值，包括 Mastra Agent 使用的模型 API 金鑰。
- **`actions/checkout@v4` + git 指令**：取出完整的儲存庫歷史記錄、擷取 PR 基礎分支，並將 PR diff 寫入 `/tmp/pr_diff.txt`。
- **`actions/setup-node@v4`**：設定 Workflow 使用的 Node.js 執行環境。
- **`npm ci`**：根據鎖定檔安裝儲存庫的 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`。鎖定檔通常很大且充滿雜訊，加入它們可能會佔滿 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 及支援檔案合併至主分支後，Agent 會在下次建立或更新 Pull Request 時自動執行。你可以在儲存庫的 **Actions** 分頁中監察執行情況。

接下來，你可以自訂 Agent 指示或更改輸出語言，也可以擴充 Workflow 以處理其他事件。

進一步了解：

- 閱讀 [Agent](https://mastra.zisheng.pro/zh-HK/docs/agents/overview) 文件
- 為 Agent 提供 [Tool](https://mastra.zisheng.pro/zh-HK/docs/agents/using-tools)，以擷取額外上下文
- 探索其他 [GitHub Actions 觸發條件](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows)，例如 issue 留言或版本發佈