Jenkins Groovy无法通过HTTPS使用OAuth2 Token克隆GitLab仓库

我之前踩过一模一样的坑，咱们来拆解一下问题根源和解决方案：

问题核心 #

Jenkins的GitSCM插件默认只识别SSH私钥或用户名/密码类型的凭证，而你通过GitLab插件创建的OAuth2 Token凭证是GitLab插件专属的，GitSCM根本认不出来——这就是为什么你明明在凭证管理器里能看到ID，但脚本里却报CredentialId "2002" could not be found，后续 fallback 到HTTP Basic认证自然就失败了。

而你用Git CLI或直接把Token嵌URL能成功，是因为GitLab允许把OAuth2 Token以oauth2作为用户名、Token作为密码的方式，通过HTTP Basic认证访问仓库，这刚好绕过了Jenkins凭证类型不兼容的问题。

解决方案 #

方案1：把OAuth2 Token转成Jenkins通用的“用户名/密码”凭证 #

这是最稳妥的兼容方案，因为GitSCM完全支持这种凭证类型：

1. 打开Jenkins凭证管理器，创建一个用户名和密码类型的凭证
   • 用户名填固定值：oauth2
   • 密码填你的GitLab OAuth2 Token
   • 给这个凭证设置一个新的ID（比如gitlab-oauth-userpass）
2. 修改你的Groovy流水线代码，使用这个新的凭证ID：

checkout([$class: 'GitSCM', 
          branches: [[name: "*/$GIT_BRANCH"]], 
          doGenerateSubmoduleConfigurations: false, 
          extensions: [], 
          gitTool: 'Default', 
          submoduleCfg: [], 
          userRemoteConfigs: [[credentialsId: "gitlab-oauth-userpass", url: "$GIT_URL"]]])

方案2：使用GitLab插件的原生检出步骤 #

如果你已经安装了Jenkins GitLab插件，可以直接用它提供的gitlabBranch步骤，这个步骤能原生识别GitLab的OAuth2凭证：

gitlabBranch(
  branch: "$GIT_BRANCH",
  credentialsId: "$GIT_CREDS_ID", // 这里直接用你原来的GitLab OAuth2凭证ID就行
  projectUrl: "$GIT_URL"
)

验证方法 #

创建完新凭证后，建议在Jenkins的Git仓库配置里测试连接，确保能正常访问GitLab仓库，避免后续流水线再出问题。

内容的提问来源于stack exchange，提问作者Swapnil jaiswal