@semantic-release/gitlab插件verifyConditions步骤失败求助

核心问题说明 #

ENOGLTOKEN错误的本质是semantic-release无法从CI环境中读取到有效的GitLab令牌，注意：semantic-release不会从配置文件（.releaserc.json或package.json）中读取令牌，手动在配置文件里添加令牌完全无效。

分步解决方案 #

1. 修正CI环境变量配置

• 变量名必须正确：使用GL_TOKEN或GITLAB_TOKEN作为变量名（GitLab CI区分大小写，严格匹配）
• 令牌权限必须足够：创建GitLab个人访问令牌（PAT）时，必须勾选api和write_repository权限（前者用于创建Release，后者用于推送标签和提交变更）
• 变量生效范围匹配：如果你的test分支是受保护分支，需将环境变量设置为「受保护」状态，否则CI运行时无法读取
• 验证变量存在性：在CI脚本中添加echo $GITLAB_TOKEN（掩码变量会显示星号，但能确认变量已加载）

2. 清理配置文件的冲突与冗余

你同时在.releaserc.json和package.json中配置了semantic-release，会导致配置合并冲突，需统一配置源：

• 移除.releaserc.json顶层的release嵌套字段（该字段冗余，semantic-release的配置应直接放在顶层）
• 修正@semantic-release/gitlab的配置错误：
  • gitlabUrl应为GitLab实例根地址（如https://gitlab.com），而非仓库地址（你在package.json中写的仓库地址是错误的）
  • 移除插件内部重复的verifyConditions配置，仅保留顶层的验证规则
  • 修正@semantic-release/changelog的配置项（插件不识别SEMREL_CHANGELOG_FILE，应使用changelogFile）

修正后的.releaserc.json示例：

{
  "branches": ["test"],
  "tagFormat": "v${version}",
  "verifyConditions": [
    "@semantic-release/changelog",
    "@semantic-release/gitlab",
    "@semantic-release/npm"
  ],
  "prepare": [
    "@semantic-release/changelog",
    "@semantic-release/npm",
    "@semantic-release/git"
  ],
  "publish": [
    "@semantic-release/gitlab"
  ],
  "fail": [
    "@semantic-release/gitlab"
  ],
  "plugins": [
    ["@semantic-release/commit-analyzer", {
      "preset": "conventionalcommits"
    }],
    ["@semantic-release/release-notes-generator", {
      "preset": "angular",
      "parserOpts": {
        "noteKeywords": ["feat"]
      },
      "writerOpts": {
        "commitsSort": ["subject", "scope"]
      }
    }],
    ["@semantic-release/changelog", {
      "changelogFile": "CHANGELOG.md"
    }],
    ["@semantic-release/git", {
      "assets": ["package.json", "CHANGELOG.md"],
      "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
    }],
    "@semantic-release/exec",
    "@semantic-release/npm",
    ["@semantic-release/gitlab", {
      "gitlabUrl": "https://gitlab.com",
      "assets": [
        { "path": "dist/asset.min.css", "label": "CSS distribution" },
        { "path": "dist/asset.min.js", "label": "JS distribution", "target": "generic_package" },
        { "path": "dist/asset.min.js", "label": "v${nextRelease.version}.js" }
      ]
    }]
  ]
}

3. 本地调试的正确方式

本地调试时，需通过终端临时设置环境变量，而非修改配置文件：

# Linux/macOS
export GITLAB_TOKEN="你的PAT令牌"
npx semantic-release --debug --dry-run

# Windows PowerShell
$env:GITLAB_TOKEN="你的PAT令牌"
npx semantic-release --debug --dry-run

--dry-run会模拟发布流程，不会实际推送变更到GitLab，适合调试。

4. 检查令牌与Runner权限

• 确认PAT未过期，且权限未被撤销
• 如果使用自托管Runner，检查Runner的网络是否能访问GitLab API，以及Runner令牌是否有效

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