經過前幾天的基礎建置，我們已經準備好了所有零件：SonarQube 伺服器、Jenkins Agent、Shared Library 以及 Vault 秘密管理。今天，我們將把這些零件聯動起來，構建一條專業級的程式碼品質掃描 Workflow。

什麼是 Quality Gate (品質守門員)？

在 CI/CD 流程中，掃描只是手段，Quality Gate 才是目的。它是一組自動化的評估準則，決定了目前的程式碼是否「足夠好」以進入下一階段。如果程式碼不符合指標（例如：出現了新的嚴重漏洞、單元測試覆蓋率未達標），Quality Gate 會將狀態標記為 Failed。

為什麼需要 Quality Gate？

1. 強制執行品質標準：防止團隊在壓力下犧牲程式碼品質。
2. 防止技術債累積：確保新加入的程式碼至少維持與舊程式碼相同、甚至更高的品質指標。
3. 自動化簽核：減少人工 Code Review 對基礎品質問題的負擔，讓人工審核專注於架構與邏輯。

技術細節：waitForQualityGate 的工作原理

這是本篇最關鍵的技術點。在 Pipeline 中，當我們上傳分析報告後，Jenkins 不會立即知道結果。

1. 分析階段：SonarScanner 將數據上傳至 SonarQube。
2. 處理階段：SonarQube Compute Engine (CE) 開始計算指標並判定 Quality Gate。
3. 回傳階段：SonarQube 透過 Webhook 向 Jenkins 發送一個 JSON 通知。
4. 恢復階段：waitForQualityGate() 捕捉到這個 Webhook 後，才會結束「暫停」狀態，並返回結果。

注意：如果未在 SonarQube 中配置對應 Jenkins 的 Webhook 地址，waitForQualityGate 會一直等待直到超時。

實戰：設計具備防禦性的 Jenkinsfile

@Library('common-pipeline-library') _

pipeline {
    agent { label 'dotnet' }
    
    stages {
        stage('SonarQube Build & Scan') {
            steps {
                script {
                    // 使用 Shared Library 封裝的工具路徑
                    def sqScanner = tool 'SonarQube MSBuild Scanner'
                    
                    // withSonarQubeEnv 會自動注入 URL 與 Credentials
                    withSonarQubeEnv('SonarQube') {
                        // 開始分析 (參數 /k 代表 Project Key, /n 代表 Project Name)
                        sh "${sqScanner}/SonarScanner.MSBuild.exe begin /k:\"my-project\" /n:\"my-project\""
                        sh "dotnet build my-project.sln --configuration Release"
                        sh "${sqScanner}/SonarScanner.MSBuild.exe end"
                    }
                }
            }
        }

        stage('Quality Gate Check') {
            steps {
                script {
                    // 設定超時防止 Pipeline 永久掛起
                    timeout(time: 5, unit: 'MINUTES') {
                        // 等待 Webhook 回傳結果
                        def qg = waitForQualityGate() 
                        if (qg.status != 'OK') {
                            // 主動拋出錯誤，強制中斷 Pipeline
                            error "Pipeline aborted due to Quality Gate failure: ${qg.status}"
                        }
                    }
                }
            }
        }
    }
}

建議的 Quality Gate 配置門檻 (專業標準)

在 SonarQube UI 中，我們建議為「New Code (新程式碼)」設定以下門檻：

• New Bugs is greater than 0 (零容忍)。
• New Vulnerabilities is greater than 0 (安全性優先)。
• Coverage on New Code is less than 80% (確保測試跟上進度)。
• Duplicated Lines on New Code is greater than 3% (防止 Copy-Paste 濫用)。

總結

透過聯動 Webhook 與 waitForQualityGate，我們建立了一個「無人值守」的品質檢查站。這確保了只有健康的程式碼能夠進入 CD（持續部署）階段。

至此，CI（持續整合）的部分已經告一段落。從明天開始，我們將正式跨入 CD 的領域，探討如何安全地將這些通過檢核的產出物，部署到多樣化的運行環境中。