跳轉到

Jenkins SSH to Secret Text Credential Migration

概念概覽

遷移路徑

核心知識

遷移路徑

從 SSH Key credential 改用 Secret Text token（如 GitLab Private Token）時，有**兩個必須分開處理的連帶效應**，缺一都會導致失敗：

1. Jenkins 原生 checkout() 不相容 Secret Text

Jenkins checkout() SCM 步驟直接以 SSH 方式 clone，無法使用 Secret Text 類型的 credential。必須改成手動 git 指令：

// ❌ 不可行：checkout() 不支援 Secret Text
checkout([$class: 'GitSCM', userRemoteConfigs: [[credentialsId: 'my-token']]])

// ✅ 改為手動 git 指令搭配 withCredentials
withCredentials([string(credentialsId: 'my-token', variable: 'GIT_TOKEN')]) {
    sh """
        git -c http.extraHeader='PRIVATE-TOKEN: ${GIT_TOKEN}' clone ${REPO_URL}
    """
}

2. oauth2 URL 嵌入方式有嚴重連線延遲

oauth2:TOKEN@gitlab.example.com/repo.git 方式在此環境下實測導致約 109 秒連線等待後被中斷（Build #570：04:03:26 → 04:05:15 abort）。

必須改用 PRIVATE-TOKEN header 方式（Build #571 驗證有效）：

git -c http.extraHeader='PRIVATE-TOKEN: ${GIT_TOKEN}' clone ${REPO_URL}

獨立 Job 的 credential 設定不會自動同步

AutoBuildSiteDeploy 的 checkout stage 是**獨立的 credential 設定**，不會因 BuildServer 的 gitlabAccount 參數更換而自動更新。分散在不同 Job 的 credential 設定，必須逐一手動修改。

gitlabAccount 環境變數來自 Jenkins Job 的 Environment Variables 設定頁，不在 Jenkinsfile 的 parameters block 內，容易遺漏。

經驗教訓

  • SSH 換 Token 時，checkout() SCM 步驟必須同步改成手動 git 指令

  • oauth2 URL 嵌入方式在某些 GitLab 環境下有嚴重連線延遲，PRIVATE-TOKEN header 是更穩定的選擇

  • 跨 Job 的 credential 設定完全獨立，沒有任何自動同步機制

常見陷阱

  • oauth2:TOKEN@URL 語法簡單但實測有 109 秒延遲問題，不能想當然認為可用

  • Jenkins Job 的 Environment Variables 頁面設定的變數不在 Jenkinsfile 裡，容易排查時漏看

最佳實踐

  • 統一使用 PRIVATE-TOKEN header 方式而非 oauth2 URL 嵌入

  • 遷移 credential 類型時，建立 checklist 確認所有引用該 credential 的 Job 都已同步更新

相關概念

來源 Sessions

日期 Session 貢獻摘要

| 2026-03-26 | 85f4d935-df5b-46e9-9e46-529869bf6e72 | 完整記錄從 SSH Key 遷移到 Secret Text token 時的兩個必須同步處理的連帶效應 |

本概念頁面由 Semi-Brain Wiki 系統自動維護

最後更新: 2026-03-26