tcwlab/semantic-release

semantic-release 镜像文档

镜像概述

tcwlab/semantic-release 是一个基于官方Node镜像和semantic-release项目构建的Docker镜像，专为GitLab CI/CD流水线设计，用于实现基于语义化版本（Semantic Versioning）的自动化发布流程。该镜像封装了semantic-release工具，简化了在GitLab环境中的集成和使用。

基本信息

• 维护者：Sascha Willomitzer（TCWlab项目）
• 支持架构：linux/amd64
• 官方文档：semantic-release官方文档
• 获取帮助：提交issue

核心功能和特性

1. 提交消息分析：自动解析提交消息，识别变更类型（如重大变更、新功能、修复等）
2. 发布说明生成：基于提交分析结果自动生成结构化的发布说明
3. GitLab集成：直接将发布信息推送到GitLab的"发布说明"页面
4. 版本标签管理：根据语义化版本规则自动创建和推送Git版本标签
5. CI/CD友好：专为GitLab流水线设计，配置简单，易于集成

使用场景

• GitLab项目的自动化版本管理和发布流程
• 需要基于提交消息自动确定版本号的项目
• 希望实现发布流程标准化和自动化的团队
• 需生成结构化发布说明的开源或商业项目

使用方法

环境准备

项目需包含以下文件结构：

bash
.
├── .gitlab-ci.yml  # GitLab CI配置文件
├── .releaserc      # semantic-release配置文件
└── 项目源代码文件

Step 1: 配置 .gitlab-ci.yml

在GitLab CI/CD流水线中添加发布阶段，使用该镜像执行semantic-release命令：

yaml
semantic-release:
  stage: release
  image: tcwlab/semantic-release:1
  script:
    - semantic-release
  only:
    refs:
      - main  # 仅在main分支执行发布
  except:
    - tags   # 已打标签的提交不重复执行

Step 2: 配置 .releaserc

创建语义化发布配置文件，定义使用的插件和分支：

yaml
plugins:
  - "@semantic-release/commit-analyzer"       # 分析提交消息
  - "@semantic-release/release-notes-generator" # 生成发布说明
  - "@semantic-release/gitlab"                # 发布到GitLab
branches:
  - "main"  # 针对main分支进行发布

配置说明：

• commit-analyzer：根据提交消息判断变更类型（遵循Angular提交规范）
• release-notes-generator：基于提交内容生成发布说明
• gitlab：将发布信息推送到GitLab
• branches：指定需要执行发布的分支

Step 3: 配置访问令牌

semantic-release需要GitLab访问令牌以执行发布操作，需创建以下类型的令牌之一：

• 项目访问令牌
• 组访问令牌
• 个人访问令牌

注意：令牌需具备api权限，用于创建发布和标签。

将令牌设置为GitLab CI/CD环境变量：

• 变量名：GITLAB_TOKEN
• 保护状态：建议设为"受保护"，仅对受保护分支可见

提交消息格式

semantic-release根据提交消息自动确定版本变更：

• BREAKING CHANGE: ...：创建主版本更新（如1.2.4 → 2.0.0）
• feat(scope): ...：创建次版本更新（如1.2.4 → 1.3.0）
• fix(scope): ...：创建补丁版本更新（如1.2.4 → 1.2.5）

更多提交消息规则请参考semantic-release提交规范。

路线图

项目未来规划和里程碑可查看项目看板。

许可证

本项目采用Apache License v2许可。

项目状态

本项目采用"尽力维护"模式，通过自动化工具进行大部分更新，没有专门的维护团队，不提供任何明示或暗示的担保。