@cleyrop-org/semantic-release-back-communication (中文(简体) )

最初创建于 马里奥·卢本卡 (@saithodev) 由Jean Humman为种植业组织维护和加强

语义释放 插件以返回到您的开发分支中 图形 仓库.

这是什么插件?

这个插件可以自动从出产/放出分行(例如, main编号 :master发展部门(例如, develop编号 :next)作为你语义释放工作流程的一部分. 这对使用 Git 流量 或类似的分支策略.

何时使用此插件

• 你分别维持生产和开发分支
• 您想要自动同步释放回您的开发分支
• 您使用语义放出自动版本和发布
• 发布后需要保持开发分支的一致性

重要说明

语义释放 在其核心中不为具有稳定和不稳定分支的Git Flow工作流程所设计. 此插件允许这样的工作流程, 但是 不保证 所有情景中无缝操作.

⚠️ 热补版 可能导致与需要人工解决的开发分支的合并冲突. 在这种情况下,发布工作流程会出故障,导致CI/CD管道故障.

安装

npm install @cleyrop-org/semantic-release-backmerge --save-dev

使用量

配置您的插件 语义释放 配置文件数字 :

重要内容: 此插件会重新建立或合并您的开发分支与您的生产分支 。 保证您在工作空间中没有未显示的文件,或者使用 clearWorkspace 选择暂时隐藏它们.

基本配置

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    [
      "@cleyrop-org/semantic-release-backmerge",
      {
        "backmergeBranches": ["develop"],
        "backmergeStrategy": "rebase"
      }
    ]
  ]
}

刻录后置配置

创建多层次后置链( 例如 ), main → staging → develop:

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    [
      "@cleyrop-org/semantic-release-backmerge",
      {
        "backmergeBranches": [
          { "from": "main", "to": "staging" },
          { "from": "staging", "to": "develop" }
        ],
        "backmergeStrategy": "merge"
      }
    ]
  ]
}

当释放时 main,此配置将:

1. 备份 main → staging
2. 备份 staging → develop (从前一步起)

带有插件的高级配置

您可以在后置期间运行额外的插件来修改您的开发分支的文件 :

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    [
      "@cleyrop-org/semantic-release-backmerge",
      {
        "backmergeBranches": ["develop"],
        "plugins": [
          [
            "@semantic-release/exec",
            {
              "successCmd": "echo 'Version in main is ${nextRelease.version}' > VERSION.txt && git add VERSION.txt"
            }
          ]
        ]
      }
    ]
  ]
}

CI/CD 平台实例

GitLab CI 语录

release:
  stage: release
  image: node:24
  script:
    - npm ci
    - npx semantic-release
  only:
    - main

GitHub 动作

- uses: actions/checkout@v4
  with:
    fetch-depth: 0
    persist-credentials: false # Required for backmerging into protected branches

- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: "24"

- name: Install dependencies
  run: npm ci

- name: Release
  env:
    GITHUB_TOKEN: ${{ secrets.GH_TOKEN }} # Use PAT with repo scope
  run: npx semantic-release

GitHub 动作说明 : 要回到受保护的树枝,你需要:

1. 禁用 persist-credentials 退出动作
2. 使用个人访问键 repo 范围 GITHUB_TOKEN
3. 确保令牌拥有者能够访问寄存器

詹金斯(英语:

withCredentials([usernamePassword(credentialsId: JENKINS_GIT_CREDENTIALS_ID,
                                  passwordVariable: 'GIT_PASSWORD',
                                  usernameVariable: 'GIT_USERNAME')]) {
    sh("git config credential.username ${GIT_USERNAME}")
    sh("git config credential.helper '!f() { echo password=$GIT_PASSWORD; }; f'")
}
withCredentials([usernameColonPassword(credentialsId: JENKINS_GIT_CREDENTIALS_ID,
                                        variable: 'GIT_CREDENTIALS')]) {
    nodejs(JENKINS_NODE_JS_INSTALLATION_LABEL) {
        sh("npx semantic-release")
    }
}

配置选项

核心选项

工作空间选项

合并策略选项

插件选项

性能选项

选项细节

backmergeBranches

指定哪个分支应接收后置。 接受 :

• 字符串阵列: 简单的分支名称
• 对象数组: 有条件或连锁反应 {from: "source", to: "target"} 格式。 对象也可以定义 ignorePaths 只有这条路.

实例

简单的后置开发 :

{
  "backmergeBranches": ["develop"]
}

多个分支 :

{
  "backmergeBranches": ["develop", "next"]
}

有条件的后起:

{
  "backmergeBranches": [
    "develop",
    { "from": "main", "to": "staging" },
    { "from": "next", "to": "beta" }
  ]
}

在有条件的例子中:

• 全部释放回原地 develop
• 释放 main 重现为 staging
• 释放 next 重现为 beta

连锁反应:

{
  "backmergeBranches": [
    { "from": "main", "to": "staging" },
    { "from": "staging", "to": "develop" }
  ]
}

在串连的例子中,当释放从 main数字 :

1. 首先, main 重现为 staging
2. 接下来, staging 重现为 develop

这就形成了一个级联: main → staging → develop

串联方式:

在当前发布工作流程中重新出现分支的插件跟踪 。 当它遇到一个 {from: X, to: Y} 配置 :

• 有条件的后置: 如果 from 等同尚未重现的释放分支 OR, 它只有在释放来源于该分支时才继续
• 叠加回流: 如果 from 已经是一个分支 to 目标在之前的后置中,它将会从该分支中合并,而不管释放来源如何

这允许您创建多层次后置链,同时保持与现有配置的后向兼容.

混合配置示例 :

{
  "backmergeBranches": [
    "hotfix",
    { "from": "main", "to": "staging" },
    { "from": "staging", "to": "develop" }
  ]
}

当释放时 main数字 :

• main → hotfix (简单反起)
• main → staging (有条件反相)
• staging → develop (cascing backcomming) (class independence) (笑声) (笑声)

模板变量

你用得着 Lodash 模板 分支名称中的语法 :

{
  "backmergeBranches": ["${branch.name}-develop"]
}

可用变量 :

backmergeStrategy

确定开发分支如何从生产分支接收变化.

选项 :

• rebase (默认):重放开发分支在生产上的承诺
• merge: 创建从生产到发展的合并承诺

示例

{
  "backmergeStrategy": "merge"
}

plugins

在后置阶段运行额外的语义放出插件. 用于修改开发分支的文件(如更新版本文件,添加dev后缀).

重要内容: 插件必须将其更改级为 Git (git add(a) 列入后出现的承诺.

示例

{
  "plugins": [
    [
      "@semantic-release/exec",
      {
        "successCmd": "npm version ${nextRelease.version}-dev --no-git-tag-version && git add package.json"
      }
    ]
  ]
}

message

自定义用于后起后起的承诺信件 Lodash 模板 语法.

可用变量 :

示例

{
  "message": "chore: merge v${nextRelease.version} into develop [skip ci]"
}

提示 : 包含 [skip ci] 防止触发另一个CI构建.

forcePush

强制推后向开发分支.

⚠️ 警告: 这将覆盖开发部门中 不生产的承诺。 用得非常谨慎!

{
  "forcePush": true
}

clearWorkspace

在尝试后退前 将未承诺的改变固定下来.

{
  "clearWorkspace": true
}

restoreWorkspace

返回完成后恢复隐藏的更改 。 只有有意义的 clearWorkspace: true。 。 。 .

{
  "clearWorkspace": true,
  "restoreWorkspace": true
}

ignorePaths

路径列表 排除 从后起而来。 合并/再基后,每个 列表路径恢复为 目标分支 后起后起状态,所以任何 源分支上的更改永远不会被结转。 两人的工作 merge 财务报告和审定财务报表 rebase 战略.

这对于每个分支必须相去甚远的文件有用,否则将是 被后起后起-典型的版本指针或放出矩阵所打碎 持有不同的值 staging 对 develop。 。 。 .

{
  "backmergeBranches": [
    { "from": "main", "to": "staging" },
    {
      "from": "staging",
      "to": "develop",
      "ignorePaths": ["version-matrix.yaml.jinja"]
    }
  ],
  "backmergeStrategy": "merge"
}

在这个例子中, version-matrix.yaml.jinja 仅在 倒计时 staging 输入 develop;它仍然包括在 main 改为 staging 再来一次.

高层 ignorePaths 选项继续支持并适用于每个 再来一次 特定路线 ignorePaths 值优先 路线。 使用空路由特定数组禁用全局排除 一条路线:

{
  "ignorePaths": ["version-matrix.yaml.jinja"],
  "backmergeBranches": [
    {
      "from": "main",
      "to": "staging",
      "ignorePaths": []
    },
    { "from": "staging", "to": "develop" }
  ]
}

行为 :

• 重置每个匹配的文件 整体 转到目标分支的版本(不是线下相接).
• 发布分支上存在的文件, 但是 没有 目标被删除,结果与目标完全吻合.
• 路径规格(包括光谱等). "values/**") 匹配无一被跳出——它们从未中止后起.

mergeMode

使用时 backmergeStrategy: "merge",决定解决冲突的战略.

选项 :

• none (默认):没有自动解决(冲突失败)
• ours: 优先开发分支变化
• theirs: 偏好生产分支变化

{
  "backmergeStrategy": "merge",
  "mergeMode": "theirs"
}

fastForwardMode

使用时 backmergeStrategy: "merge"控制快速前进的行为.

选项 :

• none (默认):与 ff
• ff: 尽可能快速前进, 合并另作承诺
• no-ff: 总是创建合并承诺
• ff-only:只有快前行,如果不可能,则失败

{
  "backmergeStrategy": "merge",
  "fastForwardMode": "no-ff"
}

fetchDelay

在抓取更新本地分支引用前, 推入远程寄存器后延迟( 毫秒) 。 这样可以让远程 git 提供者(GitHub, GitLab, Bitbucket)有更多的时间来充分处理并同步推力操作.

为什么你可能需要这个:

• 远程 git 提供者在按下完成后到这些更改可供后续抓取操作之间可能有一个小的延迟
• 这是 对连锁反应至关重要 其中一个后起之推力必须在下一个后起之取来之前完全可见到远程
• 网络延迟、CDN传播和API处理可造成时间问题
• 没有这一拖延,后起后起可能不包括所有预期的承付款

默认 : 3000 (3秒钟)

实例:

禁用本地寄存器的延迟或更快的 CI :

{
  "fetchDelay": 0
}

增加较慢网络或远程提供者的延迟 :

{
  "fetchDelay": 5000
}

说明: 默认的3秒延迟为大多数远程 git 提供者提供了合理的缓冲. 只有在遇到与时间相关的失败或想要优化本地寄存器的 CI 速度时才调整 .

保护部门

重现为受保护的分支 :

1. 使用有管理员/维护权限的证书
2. 提供适当的访问标志(例如:, GITHUB_TOKEN, (中文(简体) ), GITLAB_TOKEN(中文(简体) )
3. 对于 GitHub 动作, 禁用 persist-credentials 退出动作

解决问题

合并冲突

如果由于冲突而自动后置失败 :

1. 手动解决您的发展分支中的冲突
2. 下一次发布会再次尝试重现

工作空间问题

如果遇到"未实现的更改"错误:

• 设定 clearWorkspace: true 自动隐藏更改
• 设定 restoreWorkspace: true 如果您需要恢复这些更改

CI/CD 管道循环

确保您的承诺消息包含 [skip ci] 或等同防止无限放出回路.

归来问题

若相克相克后起相克相克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克, main → staging → develop不包括所有预期承诺:

症状:

• 来自第一个分支(例如, main)不出现于最终分支(如, develop(中文(简体) )
• 合并信件引用正确的分支但历史不完整
• 综合测试显示级联链中缺少承诺

解决方案 :

1. 增加获取: 默认的3秒延迟可能不足以满足一些远程提供者的需要

   {
     "fetchDelay": 5000
   }
   

2. 用于当地测试设置 fetchDelay: 0 由于本地 git 寄存器没有同步延迟

   {
     "fetchDelay": 0
   }
   

3. 检查远程配置: 确保您的 git 遥控器被正确配置为 origin

   git remote -v
   

技术说明: 该插件使用 git fetch origin 用于更新远程跟踪分支。 如果您的远程程序名称不同, 您可能需要调整您的 git 配置或创建一个 origin 别名.

捐款

欢迎捐款! 请看 捐款额 准则.

许可证

麻省理工学院许可证 - 详情见LICENSE文件

承认

这个项目是原作的叉子和续作 @saithodev/semantic-release-backmerge 创建于 马里奥·卢本卡感谢基础性的工作,并保持了这一分叉,以提供持续的支持和增强.

链接

• GitLab 仓库
• 国家防范机制一揽子计划
• 语义释放文档