在 GitHub Actions 中配置 Qodo Merge：實現自動化 PR 審查與程式碼規範落實

在現代軟體工程團隊的日常協作中，程式碼審查（Code Review）往往是影響交付效率的最大瓶頸。隨著研發團隊規模擴張，資深工程師耗費大量心力在解讀缺乏脈絡的 PR 描述、指出缺少單元測試或修正基礎編碼風格；與此同時，提交變更的開發者常常需要等待數小時甚至數天才能收到第一輪審查意見，導致上下文切換頻繁、交付週期被顯著拉長。

Qodo 旗下的自動化程式碼審查工具 Qodo Merge（前身為開源專案 PR-Agent）正是為了解決這項痛點。藉由在 GitHub Actions 中建立自動化工作流程，每當開發者發起或更新 Pull Request 時，系統即可自動生成變更摘要、掃描潛在安全性威脅與回歸風險、檢驗測試覆蓋度，並提供可一鍵採納的程式碼改進建議。

本文將為研發主管與 DevOps 工程師提供完整的實戰指南，詳解如何在 GitHub Actions 中建構 Qodo Merge 工作流程、配置 API 憑證與權限、落實防無窮迴圈機制、利用 .pr_agent.toml 建立團隊專屬工程標準，並實現跨專案的組織級治理。

架構解析：Qodo Merge 在 GitHub Actions 中的運作原理

相較於需要自行託管常駐伺服器的 Webhook 整合方案，在 GitHub Actions 中運行 Qodo Merge 具備完全無伺服器（Serverless）的架構優勢。審查任務完全依賴 GitHub 提供的短暫 Runner 容器環境即時啟動與執行。

       開發者發起 PR / 推送 Commit / 發表評論
                         │
                         ▼
             GitHub Actions 工作流程觸發
          (.github/workflows/pr-agent.yml)
                         │
                 Bot 迴圈防護校驗
        (github.event.sender.type != 'Bot')
                         │
                         ▼
        容器步驟：the-pr-agent/pr-agent
                         │
         ┌───────────────┴───────────────┐
         ▼                               ▼
    讀取儲存庫上下文與規範           呼叫大型語言模型 API
  (.pr_agent.toml / AGENTS.md)   (OpenAI / Anthropic / Azure)
         │                               │
         └───────────────┬───────────────┘
                         │
                         ▼
             GitHub REST & GraphQL API
       （發布行內註解、審查總結摘要、更新 PR 描述）

關鍵觸發事件與權限配置

為了兼顧「PR 變更時的全自動審查」與「團隊成員在討論串中的按需互動」，工作流程需註冊兩大事件：

pull_request：監聽 PR 生命週期，涵蓋 opened（建立）、reopened（重新開啟）、ready_for_review（從草稿轉為正式審查）與 synchronize（推入新 Commit）。
issue_comment：監聽評論區的 created 事件，讓開發者或審查者能隨時透過斜線指令（如 /review 或 /improve）觸發專屬分析。

在權限設定方面，GitHub Actions 的內建權杖（GITHUB_TOKEN）必須明確授予以下權限：

pull-requests: write：允許審查機器人回覆審查意見、建立行內修改建議，並修改 PR 標題與說明。
issues: write：允許機器人在討論串發布留言並管理標籤。
contents: read：允許 Runner 讀取程式碼差異與設定檔（若需要機器人直接自動推入修復 Commit，則需設定為 contents: write）。

逐步實作指南：從零搭建自動化審查流水線

步驟一：儲存模型 API 存取密鑰

Qodo Merge 仰賴底層的大型語言模型提供語意分析能力。它原生支援 OpenAI（如 gpt-4o）、Anthropic Claude、Azure OpenAI 以及各類相容 LiteLLM 的端點。

進入目標 GitHub 儲存庫。
點選 Settings > Secrets and variables > Actions。
點擊 New repository secret 建立密鑰。
依所選模型提供商設定密鑰名稱：
- OpenAI 提供商：設定為 OPENAI_KEY
- Anthropic 提供商：設定為 ANTHROPIC_KEY
貼上對應的 API Token 並儲存。

(備註：GITHUB_TOKEN 是由 GitHub 系統於 Action 執行時動態產生並管理的，無需額外手動配置個人存取權杖)。

步驟二：建立工作流程檔案 `.github/workflows/pr-agent.yml`

在專案預設分支中建立 .github/workflows/pr-agent.yml 檔案：

name: Qodo Merge Automation

on:
  pull_request:
    types: [opened, reopened, ready_for_review, synchronize]
  issue_comment:
    types: [created]

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.event.issue.number }}
  cancel-in-progress: true

jobs:
  pr_agent_job:
    # 重要防護：過濾 Bot 自身發布的留言，阻斷無窮迴圈
    if: ${{ github.event.sender.type != 'Bot' }}
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
      pull-requests: write

    steps:
      - name: Run Qodo Merge
        id: pr-agent
        uses: the-pr-agent/pr-agent@main
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          OPENAI_KEY: ${{ secrets.OPENAI_KEY }}
          # 若選用 Anthropic Claude，可替換為：
          # ANTHROPIC_KEY: ${{ secrets.ANTHROPIC_KEY }}

關鍵防護措施詳解

避免 Bot 遞迴死迴圈（if: ${{ github.event.sender.type != 'Bot' }}）： 當 Qodo Merge 於 PR 中回覆審查結論時，GitHub 會觸發 issue_comment 事件。如果未檢查留言者類型，機器人發出的留言將再度觸發此工作流程，造成無窮迴圈並快速耗盡 API 配額與 GitHub Actions 執行分鐘數。
並行控制（concurrency 與 cancel-in-progress: true）： 當開發者在短時間內連續推送多次修正 Commit 時，並行取消機制會主動中止針對舊 Commit 的未完成審查，確保資源集中分析最新的程式碼狀態。

制定團隊標準：透過 `.pr_agent.toml` 注入工程規範

預設設定僅提供通用的審查建議。為了讓審查品質高度契合團隊的架構與規範，團隊應在儲存庫根目錄配置 .pr_agent.toml。

[config]
# 配置主力大模型與後備模型
model = "gpt-4o"
fallback_models = ["claude-3-5-sonnet"]

# 報告輸出控制
output_relevant_configurations = false
output_run_details = true
output_run_cost = false

# 注入專案架構文件與規範脈絡
repo_context_files = ["CONTRIBUTING.md", "docs/architecture.md"]

[pr_reviewer]
# 強制執行核心維度評估
require_tests_review = true
require_security_review = true
require_can_be_split_review = true

# 行內建議嚴重性閥值：
# 1 = 資訊參考，2 = 建議改善，3 = 阻斷級 / 必須修正
inline_comments_severity_threshold = 2

# 注入團隊客製化工程規範
extra_instructions = """
審查時請嚴格執行以下團隊工程規範：
1. 資料庫操作必須採用 Parameterized Query 或 ORM，嚴禁任何字串拼接 SQL 行為。
2. 所有對外暴露的 API 端點必須具備結構化例外處理機制，並回傳統一格式的 JSON 錯誤回應。
3. 涉及網路請求或非同步操作的函式，必須強制支援 Context 取消或明確設定逾時上限（Timeout）。
4. 新增或修改業務邏輯時，PR 變更中必須包含對應的單元測試或整合測試。
"""

[pr_description]
# 自動擴充 PR 詮釋資料
publish_labels = true
publish_description_as_comment = false
add_pr_commands = true
include_generated_by_header = false
use_description_markers = true

[pr_code_suggestions]
# 配置可直接採納的程式碼建議區塊
num_code_suggestions_per_chunk = 4
committable_code_suggestions = true
extend_ignoring_files = [
    "package-lock.json",
    "yarn.lock",
    "pnpm-lock.yaml",
    "go.sum",
    "dist/**",
    "*.min.js"
]

關鍵參數說明與工程價值

配置區段	關鍵參數	預設值	工程應用價值
`[config]`	`repo_context_files`	`["AGENTS.md"]`	將架構準則或開發規範文件注入 Prompt，提升領域上下文理解力。
`[pr_reviewer]`	`inline_comments_severity_threshold`	`2`	過濾瑣碎的排版雜訊（級別 1），聚焦於核心邏輯缺陷與資安隱患（級別 2、3）。
`[pr_reviewer]`	`extra_instructions`	`""`	將團隊長久累積的架構決策與避坑指南固化為強制檢查項。
`[pr_code_suggestions]`	`extend_ignoring_files`	`[]`	排除編譯產物與相依性鎖定檔，節省 Token 並避免無謂干擾。
`[pr_description]`	`publish_labels`	`true`	自動根據變更語意標註標籤（例如 bug、refactor、security），利於後續追蹤。

互動式斜線指令與人機協作閉環

部署完成後，Qodo Merge 將化身為 PR 討論串中的專屬副駕駛。開發者與審查者可隨時在留言區輸入斜線指令（Slash Commands）呼叫專項 Agent：

       /describe               /review                /improve                 /ask
          │                       │                      │                      │
          ▼                       ▼                      ▼                      ▼
  自動產生 PR 摘要、       深度評估安全性、測試、    針對變更程式碼產生      圍繞 PR 上下文提問
   影響元件與時序圖        複雜度與團隊規範相符度    可一鍵 Commit 的修復建議   解答架構相容性與邊界疑慮

1. `/describe`（自動化變更導讀）

當 PR 缺乏詳細說明或標題過於簡略時，執行 /describe 可全自動分析 Git Diff，產出涵蓋修改動機、受影響元件清單的完整摘要，並可為複雜流程繪製 Mermaid 時序圖。

2. `/review`（全方位程式碼品質評審）

執行全方位的靜態與邏輯檢驗，產出條理清晰的審查卡片：

評估風險與審查工時： 提供 PR 複雜度評分與建議的人工複查預估時間。
安全性專項排查： 檢查常見注入攻擊、機密外洩風險、不安全的反序列化或權限漏洞。
測試完備度驗證： 比對變更程式碼是否具備相對應的測試案例，並點出未被覆蓋的例外邊界。
團隊規範合規核對： 逐項檢視是否符合在 extra_instructions 中設定的團隊準則。

3. `/improve`（一鍵提交的程式碼建議）

不同於傳統 Linter 僅給予文字警告，/improve 會直接在程式碼行內建立 GitHub Suggestion 區塊。開發者只需在介面上點選 Commit suggestion，即可將建議修復寫入分支。

4. `/ask <問題>`（上下文推演與問答）

支援針對 PR 內容進行互動式提問，例如：

/ask 這項修改是否會對既有的 API v1 行動端使用者產生向下相容破壞？

Qodo Merge 將結合變更前後的型別定義與呼叫路徑進行分析並給予反饋。

跨專案組織級多儲存庫治理

對於維護數十個微服務或函式庫的大型工程團隊，在每個儲存庫中各自維護 .pr_agent.toml 容易造成標準發散。

Qodo Merge 支援組織級全域繼承模式：

在 GitHub 組織（Organization）下建立名為 pr-agent-settings 的儲存庫。
於其預設分支根目錄放置全域共用的 .pr_agent.toml，定義公司級的通用工程基準。
組織內所有執行 Qodo Merge 的專案將自動繼承這份全域設定。
個別專案僅需在本地檔案中宣告差異（例如前端專案特有的建置產物忽略規則），實現「全域底線一致、個別專案保持彈性」。

生產環境落地實踐與防坑要點

1. 控制 CI 資源與 API 成本

排除草稿 PR（Draft PR）： 避免在開發者頻繁進行本地實驗階段浪費審查資源，在工作流程中加入過濾邏輯：
```
if: ${{ github.event.sender.type != 'Bot' && !github.event.pull_request.draft }}
```
依檔案路徑篩選： 針對純文件、設定或靜態資產變更，略過大模型審查：
```
on:
  pull_request:
    paths-ignore:
      - 'docs/**'
      - '**/*.md'
```

2. 企業級資安與資料隱私考量

原始程式碼屬於核心資產，在整合第三方 API 時應遵循規範：

建議選用具備商業資料隱私承諾的 API 方案（如 OpenAI Enterprise 或 Azure OpenAI），確保程式碼不會被用於模型二次訓練，並符合零資料留存（Zero Data Retention）標準。
在高度監管或封閉網路環境下，可透過 LiteLLM 代理將呼叫指向內部私有部署的開源程式碼大模型（例如透過 vLLM 部署的開源權重）。

3. 建立「人機協同」的雙層審查文化

AI 審查的核心價值在於扮演第一層守門員（Tier-1 Gate）：

提交 PR 後，先由 Qodo Merge 自動掃除語法瑕疵、安全漏洞與測試缺失，開發者先行依建議修正。
人工審查者介入時，程式碼品質已具備一定基礎，資深工程師可將寶貴時間專注於業務邏輯的正確性、系統擴充性與整體架構取捨等關鍵問題。

落地檢查清單

階段	關鍵任務	驗收方式
工作流程配置	建立 `.github/workflows/pr-agent.yml`	確認建立 PR 與發表評論時皆能正常觸發 Action。
權限驗證	設定 `pull-requests: write` 與 `issues: write`	確認機器人能成功發布行內評論與標籤，無 403 錯誤。
防死循環	設定 `github.event.sender.type != 'Bot'`	確認機器人回覆時不會再度引發第二次執行。
規範落地	配置 `.pr_agent.toml` 中的 `extra_instructions`	確認審查結果卡片有確實檢查團隊專屬規約。
互動指令	於 PR 討論串測試 `/review` 與 `/improve`	成功取得結構化分析結果與可一鍵提交的行內修復補丁。

透過在 GitHub Actions 中整合 Qodo Merge，團隊能在提升 PR 週轉速度的同時，建立起客觀、穩定且永不疲憊的高標準程式碼防線。

在 GitHub Actions 中配置 Qodo Merge：實現自動化 PR 審查與程式碼規範落實

讓你的 AI 用上 365 Wiki

365Wiki Skill

架構解析：Qodo Merge 在 GitHub Actions 中的運作原理

關鍵觸發事件與權限配置

逐步實作指南：從零搭建自動化審查流水線

步驟一：儲存模型 API 存取密鑰

步驟二：建立工作流程檔案 `.github/workflows/pr-agent.yml`

關鍵防護措施詳解

制定團隊標準：透過 `.pr_agent.toml` 注入工程規範

關鍵參數說明與工程價值

互動式斜線指令與人機協作閉環

1. `/describe`（自動化變更導讀）

2. `/review`（全方位程式碼品質評審）

3. `/improve`（一鍵提交的程式碼建議）

4. `/ask <問題>`（上下文推演與問答）

跨專案組織級多儲存庫治理

生產環境落地實踐與防坑要點

1. 控制 CI 資源與 API 成本

2. 企業級資安與資料隱私考量

3. 建立「人機協同」的雙層審查文化

落地檢查清單

參考資料

在 GitHub Actions 中配置 Qodo Merge：實現自動化 PR 審查與程式碼規範落實

架構解析：Qodo Merge 在 GitHub Actions 中的運作原理

關鍵觸發事件與權限配置

逐步實作指南：從零搭建自動化審查流水線

步驟一：儲存模型 API 存取密鑰

步驟二：建立工作流程檔案 .github/workflows/pr-agent.yml

關鍵防護措施詳解

制定團隊標準：透過 .pr_agent.toml 注入工程規範

關鍵參數說明與工程價值

互動式斜線指令與人機協作閉環

1. /describe（自動化變更導讀）

2. /review（全方位程式碼品質評審）

3. /improve（一鍵提交的程式碼建議）

4. /ask <問題>（上下文推演與問答）

跨專案組織級多儲存庫治理

生產環境落地實踐與防坑要點

1. 控制 CI 資源與 API 成本

2. 企業級資安與資料隱私考量

3. 建立「人機協同」的雙層審查文化

落地檢查清單

參考資料

涉及產品

步驟二：建立工作流程檔案 `.github/workflows/pr-agent.yml`

制定團隊標準：透過 `.pr_agent.toml` 注入工程規範

1. `/describe`（自動化變更導讀）

2. `/review`（全方位程式碼品質評審）

3. `/improve`（一鍵提交的程式碼建議）

4. `/ask <問題>`（上下文推演與問答）