在建立完共享庫（Shared Library）後，我們需要實作第一個標準化的管線：sonarqube.jenkinsfile。這個管線的主要目的是在開發者提交程式碼或發起 Merge Request (MR) 時，自動觸發品質分析並執行 Quality Gate，確保只有符合標準的程式碼能進入後續階段。

管線設計思路

此管線需要具備處理「一般分支分析」與「Pull Request (PR) 分析」的能力。我們透過 Jenkins 的參數化（Parameters）機制來接收來自 GitLab Webhook 的資訊。

sonarqube.jenkinsfile 完整實作

@Library('my-shared-library') _

pipeline {
    agent { label 'dotnet' }

    parameters {
        string(name: 'PROJECT_ID', defaultValue: 'user-service', description: '專案唯一 ID')
        string(name: 'BRANCH_NAME', defaultValue: 'develop', description: '待掃描的分支名稱')
        string(name: 'PR_NUMBER', defaultValue: '', description: '若是 PR 觸發，請帶入 ID')
    }

    stages {
        stage('Initialize') {
            steps {
                script {
                    // 從共享庫獲取專案配置
                    def config = project.getConfig(params.PROJECT_ID)
                    env.SQ_KEY = config.sq_key
                    env.SLN_PATH = config.solution
                }
            }
        }

        stage('Checkout') {
            steps {
                // 使用 Jenkins 預設的 SCM 或自定義 git 指令
                checkout scm
            }
        }

        stage('Build & Analysis') {
            steps {
                // withSonarQubeEnv 會自動注入 SONAR_HOST_URL 與 SONAR_AUTH_TOKEN
                withSonarQubeEnv('SonarQube') {
                    script {
                        def scanner = tool 'SonarQube MSBuild Scanner'
                        
                        // 基礎掃描參數
                        def scanCmd = "${scanner}/SonarScanner.MSBuild.exe begin /k:\"${env.SQ_KEY}\""
                        
                        // 若為 PR 觸發，則加入 PR 專用參數 (需搭配 Day 17 的插件)
                        if (params.PR_NUMBER) {
                            scanCmd += " /d:sonar.pullrequest.key=${params.PR_NUMBER} /d:sonar.pullrequest.branch=${params.BRANCH_NAME}"
                        } else {
                            scanCmd += " /d:sonar.branch.name=${params.BRANCH_NAME}"
                        }

                        // 執行分析與建置
                        sh "${scanCmd}"
                        sh "dotnet build ${env.SLN_PATH} -c Release"
                        sh "${scanner}/SonarScanner.MSBuild.exe end"
                    }
                }
            }
        }

        stage('Quality Gate Check') {
            steps {
                timeout(time: 5, unit: 'MINUTES') {
                    script {
                        def qg = waitForQualityGate()
                        if (qg.status != 'OK') {
                            error "Quality Gate failed: ${qg.status}. Please check SonarQube Dashboard."
                        }
                    }
                }
            }
        }
    }

    post {
        always {
            cleanWs() // 執行完畢清理工作空間，釋放 Agent 磁碟
        }
    }
}

關鍵技術說明

1. 動態參數化掃描

透過 if (params.PR_NUMBER) 的判斷，我們成功地將「一般分支掃描」與「PR 裝飾掃描」整合進同一個 Jenkinsfile 中。這降低了維護多個管線文件的成本。

2. 環境變數的橋接

withSonarQubeEnv 注入的 SONAR_AUTH_TOKEN 會被 SonarScanner 自動讀取，但在某些環境下，如果需要顯式傳遞，可以使用 /d:sonar.login=${SONAR_AUTH_TOKEN}。

3. 資源回收 (cleanWs)

在 AI 大量產出程式碼的情境下，Agent 的磁碟空間非常寶貴。使用 post { always { cleanWs() } } 確保每次建置不論成功與否，都會清理掉暫存的二進位檔案與分析日誌。

總結

透過 sonarqube.jenkinsfile，我們為開發團隊建立了一個自動化的「程式碼體檢站」。這套流程能抓出潛在 Bug，並透過 PR 裝飾功能直接在 Git 介面給予反饋。

品質保證後，下一個重大任務是「交付」。明天，我們將實作負責建置產出物與配置渲染的 MyDeploy.jenkinsfile。