GitLab CI/CD中SDK版本管理与发布的版本号持久化方案问询

问题背景 #

我们的产品采用Monorepo架构，包含后端、SDK、前端三大核心模块，SDK与后端一同开发，由后端团队构建后发布至私有GitLab npm仓库。debug分支需要自动化构建发布流程，当前使用npm version patch完成版本更新与发布，但版本号未持久化，下次构建时会尝试创建重复版本，必须手动本地更新版本并推送至仓库才能继续。

你的思路可行：GitLab变量+自定义脚本实现版本持久化 #

你提到的用GitLab变量结合API更新版本的方案完全可行，以下是具体落地步骤：

1. 初始化GitLab项目变量 #

在GitLab项目的「设置」→「CI/CD」→「变量」中添加一个名为SDK_VERSION的变量，初始值设为当前SDK的版本号（例如1.0.0），建议勾选「保护变量」和「掩码变量」以保障安全。

2. 编写版本更新脚本 #

在仓库根目录创建一个可执行脚本（以Shell脚本为例，命名为update-sdk-version.sh），实现版本号递增、npm版本更新以及GitLab变量同步：

#!/bin/bash

# 从GitLab CI变量读取当前版本
CURRENT_VERSION=$SDK_VERSION

# 拆分版本号并递增patch段
IFS='.' read -r major minor patch <<< "$CURRENT_VERSION"
NEW_PATCH=$((patch + 1))
NEW_VERSION="$major.$minor.$NEW_PATCH"

# 更新SDK的package.json版本（不生成Git标签）
cd packages/sdk
npm version "$NEW_VERSION" --no-git-tag-version

# 调用GitLab API更新项目变量
PROJECT_ID="你的GitLab项目ID"
GITLAB_TOKEN="$CI_JOB_TOKEN" # 直接使用CI内置令牌，无需手动创建个人令牌

curl --request PUT \
  --url "https://你的GitLab域名/api/v4/projects/$PROJECT_ID/variables/SDK_VERSION" \
  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  --header "Content-Type: application/json" \
  --data "{\"value\":\"$NEW_VERSION\"}"

注：使用CI_JOB_TOKEN替代手动创建的个人令牌更安全，该令牌由GitLab CI自动生成，仅在当前流水线有效，且具备项目API权限。

3. 调整CI流水线配置 #

将版本更新逻辑从Dockerfile迁移到GitLab CI流水线（更符合CI/CD职责分离原则），修改.gitlab-ci.yml：

stages:
  - publish-sdk

publish-debug-sdk:
  stage: publish-sdk
  script:
    - chmod +x ./update-sdk-version.sh
    - ./update-sdk-version.sh
    - cd packages/sdk
    - npm run build
    - npm publish --tag debug --verbose
  only:
    - debug

4. 关键注意事项 #

• 如果需要根据分支类型调整版本递增规则（例如stage分支递增minor版本、prod分支递增major版本），可在脚本中添加分支判断逻辑：

  if [ "$CI_COMMIT_BRANCH" == "stage" ]; then
    NEW_MINOR=$((minor + 1))
    NEW_VERSION="$major.$NEW_MINOR.0"
  elif [ "$CI_COMMIT_BRANCH" == "prod" ]; then
    NEW_MAJOR=$((major + 1))
    NEW_VERSION="$NEW_MAJOR.0.0"
  else
    NEW_PATCH=$((patch + 1))
    NEW_VERSION="$major.$minor.$NEW_PATCH"
  fi
  

• 确保GitLab CI运行环境能访问私有GitLab API（内部部署的GitLab通常无需额外配置）。

替代方案：基于Git标签的版本推导 #

若不想依赖GitLab变量，也可通过Git标签实现版本追溯与递增：

• 每次发布时，在CI中创建带版本前缀的Git标签（例如sdk-v1.0.1）
• 下次构建时，通过git describe --tags --abbrev=0 | sed 's/sdk-v//'获取最新版本号，解析后递增
• 该方案版本号与Git提交绑定，可追溯性强，但需要CI具备推送Git标签的权限（需评估是否符合团队规范）

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