javachanges

简体中文

English

简体中文

English

Appearance

javachanges GitLab CI/CD 使用指南 ​

English | 简体中文

1. 概述 ​

这份指南说明如何在 GitLab CI/CD 中使用 javachanges 完成：

  1. 常规校验
  2. GitLab CI/CD 变量管理
  3. release merge request 生成
  4. 基于生成后的 release plan 创建正式 tag
  5. 在 tag pipeline 中执行 Maven 发布
  6. Maven 依赖缓存

javachanges 目前有两个 GitLab 专用命令：

命令作用
gitlab-release-plan创建或更新 release 分支和 release merge request
gitlab-tag-from-plan在 release plan 合入后创建并推送正式 tag

2. javachanges 在 GitLab CI/CD 中能做什么 ​

推荐的命令分工如下：

目标命令
查看当前待发布状态status
在本地或 CI 中应用 release planplan --apply true
根据环境变量生成 Maven settingswrite-settings
预览 GitLab 变量render-vars --platform gitlab
检查平台就绪状态doctor-local、doctor-platform
通过 glab 同步 GitLab 变量sync-vars --platform gitlab
通过 glab variable export 回读审计audit-vars --platform gitlab
创建或更新 GitLab release MRgitlab-release-plan --execute true
在 release plan 落地后创建并推送 taggitlab-tag-from-plan --execute true
做发布前检查preflight
执行真正的 Maven deploypublish --execute true

3. 变量模型 ​

3.1 通用 Maven 仓库变量 ​

javachanges 会读取 env/release.env.example 里的这些变量：

变量必填含义
MAVEN_RELEASE_REPOSITORY_URL是release 仓库地址
MAVEN_SNAPSHOT_REPOSITORY_URL是snapshot 仓库地址
MAVEN_RELEASE_REPOSITORY_ID是release 仓库 id
MAVEN_SNAPSHOT_REPOSITORY_ID是snapshot 仓库 id
MAVEN_REPOSITORY_USERNAME是，除非你显式拆分了 release/snapshot 凭据通用用户名
MAVEN_REPOSITORY_PASSWORD是，除非你显式拆分了 release/snapshot 凭据通用密码
MAVEN_RELEASE_REPOSITORY_USERNAME否release 专用用户名
MAVEN_RELEASE_REPOSITORY_PASSWORD否release 专用密码
MAVEN_SNAPSHOT_REPOSITORY_USERNAME否snapshot 专用用户名
MAVEN_SNAPSHOT_REPOSITORY_PASSWORD否snapshot 专用密码
GITLAB_RELEASE_TOKEN否某些 GitLab release 场景下可选的额外 token

当你用 sync-vars 把这些值同步到 GitLab 时，敏感值会被写成 masked + protected 变量。

3.2 GitLab release 分支 / MR 自动化额外依赖的变量 ​

gitlab-release-plan 还依赖这些运行时变量：

变量来源
CI_PROJECT_IDGitLab 内置 CI 变量，或显式传 --project-id
CI_DEFAULT_BRANCHGitLab 内置 CI 变量
CI_SERVER_HOSTGitLab 内置 CI 变量
CI_SERVER_URLGitLab 内置 CI 变量
CI_PROJECT_PATHGitLab 内置 CI 变量
GITLAB_RELEASE_BOT_USERNAME你自己提供的项目变量
GITLAB_RELEASE_BOT_TOKEN你自己提供的项目变量

gitlab-tag-from-plan 还需要：

参数或变量含义
--before-sha 或 CI_COMMIT_BEFORE_SHA上一个提交的 SHA
--current-sha 或 CI_COMMIT_SHA当前提交的 SHA

4. 本地准备 ​

4.1 构建 CLI ​

bash
mvn -q test

4.2 初始化本地 env 文件 ​

bash
mvn -q -DskipTests compile exec:java -Dexec.args="init-env --target env/release.env.local"

4.3 预览 GitLab 变量 ​

bash
mvn -q -DskipTests compile exec:java -Dexec.args="render-vars --env-file env/release.env.local --platform gitlab"

4.4 检查本地就绪状态 ​

bash
mvn -q -DskipTests compile exec:java -Dexec.args="doctor-local --env-file env/release.env.local --gitlab-repo group/project"

4.5 使用 glab 同步 GitLab 变量 ​

Dry-run：

bash
mvn -q -DskipTests compile exec:java -Dexec.args="sync-vars --env-file env/release.env.local --platform gitlab --repo group/project"

真正写入：

bash
mvn -q -DskipTests compile exec:java -Dexec.args="sync-vars --env-file env/release.env.local --platform gitlab --repo group/project --execute true"

回读审计：

bash
mvn -q -DskipTests compile exec:java -Dexec.args="audit-vars --env-file env/release.env.local --platform gitlab --gitlab-repo group/project"

5. 推荐的 GitLab CI/CD Pipeline 拓扑 ​

推荐 stage 顺序：

  1. verify
  2. release-plan
  3. tag
  4. publish

6. .gitlab-ci.yml 示例 ​

yaml
stages:
  - verify
  - release-plan
  - tag
  - publish

default:
  image: maven:3.9.9-eclipse-temurin-8
  cache:
    key:
      files:
        - pom.xml
    paths:
      - .m2/repository

variables:
  MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"

verify:
  stage: verify
  script:
    - mvn -B verify
    - mvn -B -DskipTests compile exec:java -Dexec.args="status --directory $CI_PROJECT_DIR"
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH

release_plan_mr:
  stage: release-plan
  script:
    - mvn -B -DskipTests compile
    - mvn -B -DskipTests compile exec:java -Dexec.args="gitlab-release-plan --directory $CI_PROJECT_DIR --execute true"
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

release_tag:
  stage: tag
  script:
    - mvn -B -DskipTests compile
    - >
      mvn -B -DskipTests compile exec:java
      -Dexec.args="gitlab-tag-from-plan --directory $CI_PROJECT_DIR --before-sha $CI_COMMIT_BEFORE_SHA --current-sha $CI_COMMIT_SHA --execute true"
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

publish_release:
  stage: publish
  script:
    - mvn -B -DskipTests compile
    - >
      mvn -B -DskipTests compile exec:java
      -Dexec.args="publish --directory $CI_PROJECT_DIR --tag $CI_COMMIT_TAG --execute true"
  rules:
    - if: $CI_COMMIT_TAG

这个示例的分工如下：

Job作用
verify校验仓库并输出当前发布状态
release_plan_mr创建或更新 release 分支和 merge request
release_tag在默认分支上的 release plan manifest 发生变化后创建正式 tag
publish_release基于正式 Git tag 执行发布

7. GitLab 专用命令的行为说明 ​

7.1 gitlab-release-plan ​

默认行为：

输入默认值
--project-idCI_PROJECT_ID
--target-branchCI_DEFAULT_BRANCH，如果拿不到则回退到 main
--release-branchchangeset-release/<target-branch>

关键行为：

条件结果
没有 pending changesets跳过 release MR
没有传 --execute true只做 dry-run
生成 release plan 后没有任何 staged 变更跳过 MR 更新
已经存在打开中的 release MR更新它，而不是新建一个

7.2 gitlab-tag-from-plan ​

关键行为：

条件结果
beforeSha 缺失或全 0跳过打 tag
.changesets/release-plan.json 在两个提交之间没有变化跳过打 tag
远端 tag 已经存在跳过打 tag
没有传 --execute true只做 dry-run

8. 在 GitLab CI/CD 中做通用 Maven 发布 ​

通用 publish 辅助命令会负责：

  1. 复用 preflight 逻辑校验版本、tag 和凭据
  2. 生成 .m2/settings.xml
  3. 读取 release / snapshot 仓库地址
  4. 用 CI/CD variables 中的凭据执行 Maven deploy

典型的 tag pipeline 拆分方式：

yaml
publish_preflight:
  stage: publish
  script:
    - mvn -B -DskipTests compile
    - >
      mvn -B -DskipTests compile exec:java
      -Dexec.args="preflight --directory $CI_PROJECT_DIR --tag $CI_COMMIT_TAG"
  rules:
    - if: $CI_COMMIT_TAG

publish_execute:
  stage: publish
  script:
    - mvn -B -DskipTests compile
    - >
      mvn -B -DskipTests compile exec:java
      -Dexec.args="publish --directory $CI_PROJECT_DIR --tag $CI_COMMIT_TAG --execute true"
  rules:
    - if: $CI_COMMIT_TAG

9. GitLab CI/CD 中的 Maven Cache 行为 ​

推荐缓存配置：

yaml
cache:
  key:
    files:
      - pom.xml
  paths:
    - .m2/repository

推荐搭配这个运行时参数：

yaml
variables:
  MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"

它主要改善的是：

可以较好缓存不能单靠 GitLab cache 解决
Maven 依赖Git clone / fetch 开销
Maven pluginJDK / Docker image 拉取时间
相同 pom.xml 下的重复 pipelineGitLab API 调用，例如创建 release MR
在共享 cache 后端上的跨 job / 跨 runner 复用远端仓库发布与等待时间

需要注意的行为：

场景结果
新 cache key 首次出现第一次 pipeline 仍然会下载依赖
pom.xml 变化可能触发新的 cache key
不同 runner 且没有共享 cache缓存复用会比较弱
GitLab 配置了共享 / 分布式 cache跨 runner 复用会更好

10. 常见错误 ​

问题原因修复方式
release MR job 无法 push缺少 GITLAB_RELEASE_BOT_TOKEN 或 GITLAB_RELEASE_BOT_USERNAME把 bot 凭据加成项目变量
release tag job 一直不打 tagrelease-plan.json 没变化，或 CI_COMMIT_BEFORE_SHA 不可用检查默认分支 pipeline 和 release plan 产物
sync-vars 没有任何效果env 文件里还是占位值先把 replace-me 替换成真实值
audit-vars 报 MISMATCH本地 env 与远端项目变量已经不一致重新同步，或明确选择以哪一边为准
publish job 提示 Maven 凭据缺失项目变量没有配置完整先用 glab 同步变量，再重跑 pipeline

11. 推荐与哪些文档配合阅读 ​

建议把下面这些文档配合起来看：

需求文档
通用发布命令与本地准备Development Guide
当前仓库自己的 GitHub release 流程GitHub Actions Release Flow
Maven Central 专用发布Publish To Maven Central

12. 总结 ​

GitLab CI/CD 中最实用的路径通常是：

  1. 用 status 做基础校验
  2. 用 gitlab-release-plan 生成或更新 release MR
  3. 用 gitlab-tag-from-plan 创建正式 tag
  4. 用 sync-vars 和 audit-vars 管理 GitLab 项目变量
  5. 在 tag pipeline 中用 preflight 和 publish 做正式发布

13. 参考资料 ​

基于 Apache-2.0 License 发布。

Copyright © 2026 sonofmagic