使用semantic-release对接GitLab与Nexus时遇权限错误求助

背景 #

我有一个托管在GitLab上的Vite项目，计划用semantic-release v20.0.0处理版本管理并发布到Nexus npm服务器。当前CI/CD的release阶段配置如下：

release:
  stage: release
  script:
    - npm ci
    - npm run build
    - npm run semantic-release
  only:
    - developer
    - master
  when: manual

已配置的CI/CD变量 #

根据semantic-release文档，原本需要配置：

GL_TOKEN or GITLAB_TOKEN    // GitLab个人访问令牌（已在用户设置/访问令牌中新建）
NPM_TOKEN                   // Nexus不支持该认证方式

由于Nexus需用户名密码认证，我额外添加了以下变量：

NPM_PASSWORD    // Nexus密码
NPM_USERNAME    // Nexus用户名
NPM_EMAIL       // Nexus邮箱

错误信息 #

流水线执行时抛出认证错误：

An error occurred while running semantic-release: Error: Command failed with exit code 128: git ls-remote --heads https://company-gitlab.company.de/user/project-name.git
remote: HTTP Basic: Access denied. The provided password or token is incorrect or your account has 2FA enabled and you must use a personal access token instead of a password.

.releaserc配置 #

{
  "branches": [
    "+([0-9])?(.{+([0-9]),x}).x",
    "master",
    {
      "name": "developer",
      "prerelease": "alpha"
    }
  ],
  "plugins": [
   "@semantic-release/commit-analyzer",
   "@semantic-release/release-notes-generator",
   [
     "@semantic-release/npm",
     {
       "pkgRoot": "./dist"
     }
   ],
   [
     "@semantic-release/gitlab",
     {
       "gitlabUrl": "https://company.gitlab.com"
     }
   ]
 ]
}

排查思路 #

• 检查GitLab令牌的变量名与权限：确认CI变量使用的是GL_TOKEN或GITLAB_TOKEN（注意大小写敏感），且该个人访问令牌（PAT）已授予api、read_repository、write_repository权限。
• 验证变量的可见性：确保变量在developer和master分支上可用（GitLab变量配置中有“保护”和“掩码”选项，需确认未限制分支访问）。
• 核对GitLab URL一致性：错误信息中的仓库URL是https://company-gitlab.company.de/...，但.releaserc中配置的gitlabUrl是https://company.gitlab.com，二者域名不一致，这会导致semantic-release使用错误的地址进行认证，需统一URL。
• 检查Nexus认证配置：semantic-release的npm插件默认读取NPM_TOKEN，但Nexus用用户名密码时，需在CI脚本中生成临时.npmrc文件，比如添加：

  echo "//your-nexus-url/repository/npm-registry/:_authToken=\$(echo -n \$NPM_USERNAME:\$NPM_PASSWORD | base64)" > .npmrc
  

• 确认账号2FA状态：如果你的GitLab账号开启了2FA，必须使用PAT而非密码，且PAT需正确生成（生成时要选择正确的权限范围）。
• 检查Git远程仓库配置：确保CI环境中git的remote URL与错误信息中的地址一致，避免因URL不匹配导致认证失败。

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