feat(cli): add automated build and publish workflow by CheneyH · Pull Request #422 · iflytek/skillhub

CheneyH · 2026-05-12T02:32:38Z

Summary

Add release-cli.yml GitHub Actions workflow: triggered by cli-v* tags, runs build/lint/typecheck/test, publishes to npm, creates GitHub Release with artifacts and checksums
Rewrite scripts/publish-cli.sh: local bump + commit + tag + push flow, enforces main branch, idempotent tag checks, syncs version from latest tag on first run
Add make publish-cli / publish-cli-minor / publish-cli-major targets
Add concurrency group (release-cli-<tag>) and release idempotency check to prevent duplicate runs
Add cli/RELEASE.md documenting the full release process and troubleshooting

How to release

# On main, clean working tree
make publish-cli         # patch bump
make publish-cli-minor   # minor bump
make publish-cli-major   # major bump

Test plan

make publish-cli fails on non-main branch
make publish-cli fails on dirty working tree
Pushing a cli-v* tag triggers release-cli.yml
Duplicate tag push does not create duplicate release (concurrency + idempotency)
cli/RELEASE.md accurately reflects the release process

- Add release-cli.yml GitHub Actions workflow: build, test, npm publish, and GitHub Release triggered by cli-v* tags - Rewrite scripts/publish-cli.sh: local bump + commit + tag + push, enforces main branch, idempotent tag checks - Add concurrency group and release idempotency to workflow - Add make publish-cli / publish-cli-minor / publish-cli-major targets - Add cli/RELEASE.md documenting the full release process

gemini-code-assist

Code Review

This pull request automates the CLI release process by refactoring the publish-cli workflow. Key changes include updating the Makefile to delegate publishing to a dedicated script, adding a comprehensive RELEASE.md guide, and streamlining scripts/publish-cli.sh to handle version bumping and tagging while offloading build and distribution to CI. Feedback focused on improving the robustness of the shell script, specifically regarding safe variable injection in Node.js calls, reliable version parsing from package.json, and ensuring atomic git pushes for branches and tags.

gemini-code-assist · 2026-05-12T02:35:30Z

+    node -e "
+      const fs = require('fs');
+      const pkg = JSON.parse(fs.readFileSync('$PACKAGE_JSON', 'utf8'));
+      pkg.version = '$BASE_VERSION';
+      fs.writeFileSync('$PACKAGE_JSON', JSON.stringify(pkg, null, 2) + '\n');
+    "


Injecting shell variables directly into a Node.js script string is fragile and can break if paths or versions contain special characters (like single quotes). It is safer to pass these values as arguments to the Node.js process to avoid potential syntax errors or command injection issues.

Suggested change

node -e "

const fs = require('fs');

const pkg = JSON.parse(fs.readFileSync('$PACKAGE_JSON', 'utf8'));

pkg.version = '$BASE_VERSION';

fs.writeFileSync('$PACKAGE_JSON', JSON.stringify(pkg, null, 2) + '\n');

"

node -e '

const fs = require("fs");

const [path, version] = process.argv.slice(1);

const pkg = JSON.parse(fs.readFileSync(path, "utf8"));

pkg.version = version;

fs.writeFileSync(path, JSON.stringify(pkg, null, 2) + "\n");

' "$PACKAGE_JSON" "$BASE_VERSION"

The values interpolated here ($PACKAGE_JSON, $BASE_VERSION) are both constructed internally by the script — PACKAGE_JSON is derived from BASH_SOURCE[0], and BASE_VERSION is extracted from a git tag matched by the cli-v* glob. Neither comes from user input or an external boundary, so there's no injection surface.

gemini-code-assist · 2026-05-12T02:35:30Z

+NPM_VERSION_OUTPUT="$(cd "$CLI_DIR" && npm version "$BUMP_TYPE" --no-git-tag-version)"
+NEW_VERSION="${NPM_VERSION_OUTPUT#v}"


Parsing the version from npm version stdout is unreliable as it may contain additional output from lifecycle scripts, global configuration, or different npm versions. It is more robust to read the updated version directly from package.json after the command execution to ensure the tag name is accurate.

Suggested change

NPM_VERSION_OUTPUT="$(cd "$CLI_DIR" && npm version "$BUMP_TYPE" --no-git-tag-version)"

NEW_VERSION="${NPM_VERSION_OUTPUT#v}"

(cd "$CLI_DIR" && npm version "$BUMP_TYPE" --no-git-tag-version) >/dev/null

NEW_VERSION=$(node -p 'require(process.argv[1]).version' "$PACKAGE_JSON")

npm version outputs a stable vX.Y.Z format (documented behavior), and we strip the v prefix on the next line. There's also an explicit empty-string guard that reverts package.json and exits if parsing fails.

gemini-code-assist · 2026-05-12T02:35:30Z

+git -C "$REPO_ROOT" push origin "$CURRENT_BRANCH"
+git -C "$REPO_ROOT" push origin "$TAG"


Pushing the branch and the tag in separate commands is not atomic and can leave the remote in an inconsistent state if the second push fails (e.g., due to network issues or remote tag restrictions). Pushing them together ensures that the release trigger (the tag) is only available on the remote if the corresponding commit is also successfully pushed.

Suggested change

git -C "$REPO_ROOT" push origin "$CURRENT_BRANCH"

git -C "$REPO_ROOT" push origin "$TAG"

git -C "$REPO_ROOT" push origin "$CURRENT_BRANCH" "$TAG"

Fixed in 490ddfa — merged the two git push calls into one (git push origin "$CURRENT_BRANCH" "$TAG") so a partial failure can't leave a version bump commit without its tag.

dongmucat · 2026-05-12T06:59:37Z

需要修复两个问题：

.github/workflows/release-cli.yml:176：create-release 目前只依赖 build-and-test，不依赖 publish-npm。如果 npm 发布因为 token、权限或 registry 问题失败，GitHub Release 仍可能被创建，导致出现“Release 已发布但 npm 包不可安装”的半发布状态。建议让 create-release 在 npm 发布成功后再执行；如果 skip_npm=true，也需要在 workflow 里显式区分这个路径。
scripts/tests/publish-cli-test.sh:28：PR 重写了 scripts/publish-cli.sh 的发布流程，但现有测试仍在断言旧行为，例如 .env.local、NPM_TOKEN/NPM_ORG/DRY_RUN、skip、本地 npm publish 等。请同步更新这份测试，覆盖新流程中的 main 分支检查、dirty check、tag baseline、版本 bump、取消回滚、commit/tag/push 成功路径，以及 push/tag 冲突等关键失败路径。

dongmucat · 2026-05-12T07:17:40Z

还需要修复一个发布脚本的恢复问题：

scripts/publish-cli.sh:107-115 现在是先 commit、再 tag、最后 push。如果 git commit 和 git tag 已经成功，但后面的 git push origin "$CURRENT_BRANCH" "$TAG" 因网络、权限或远端拒绝失败，本地会留下一个 release commit 和 cli-vX.Y.Z tag。之后重跑脚本时，本地 tag 会参与 baseline 计算，可能直接 bump 到下一个版本，导致失败的版本被跳过，并且用户需要手动判断该删除 tag、reset commit 还是重新 push。

建议在进入 commit/tag/push 阶段后增加失败恢复逻辑，例如设置 trap 清理本地 tag/commit，或至少在重跑时检测 @{u}..HEAD / 本地 release tag 未推送的状态并给出明确恢复命令。

CheneyH · 2026-05-12T08:01:52Z

已修复这两个问题，见 49726dc：

问题 1 - workflow 依赖链：create-release 现在依赖 [build-and-test, publish-npm]，并添加条件判断：

if: ${{ always() && needs.build-and-test.result == 'success' && 
        (needs.publish-npm.result == 'success' || 
         (inputs.skip_npm && needs.publish-npm.result == 'skipped')) }}

这样确保只有在 npm 发布成功或用户显式跳过时才创建 Release，避免半发布状态。

问题 2 - 测试脚本重写：完全重写了 scripts/tests/publish-cli-test.sh（517 行 → 289 行），覆盖新流程的关键路径：

✅ main 分支检查
✅ dirty working tree 检测
✅ tag baseline 同步（从最新 cli-v* tag）
✅ 版本 bump（patch/minor/major）
✅ 本地和远程 tag 冲突检测
✅ 用户取消时的 package.json 回滚
✅ commit/tag/push 成功路径（原子性推送验证）
✅ push 失败场景

新测试使用真实的 bare git repo 作为 origin，完整验证 pull/fetch/push 流程，移除了旧测试中对 .env.local、NPM_TOKEN、DRY_RUN 等已废弃逻辑的断言。

Add pre-flight check in publish-cli.sh to detect unpushed commits and tags from previous failed pushes. When detected, the script exits with clear recovery instructions: 1. Retry push (for transient network failures) 2. Rollback and re-release (for clean restart) This prevents the baseline sync logic from skipping failed versions when local tags participate in version calculation after a push failure. Addresses feedback from dongmucat in PR #422. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CheneyH · 2026-05-12T08:07:44Z

已修复，见 6957136。

在 git fetch --tags 之后增加了未推送 release 检测逻辑：

UNPUSHED_COMMITS="$(git log --oneline origin/main..HEAD)"
UNPUSHED_RELEASE_TAGS="$(git tag --list 'cli-v*' --no-merged origin/main)"

如果检测到未推送的 commit 或 tag，脚本会立即退出并给出两种恢复方案：

方案 1：重试推送（适用于临时网络故障）

git push origin main cli-v0.1.5

方案 2：回滚重发（适用于需要重新开始）

git tag -d cli-v0.1.5
git reset --hard origin/main
# 然后重新运行 make publish-cli

这样可以防止本地 tag 参与 baseline 计算导致失败版本被跳过的问题。

…blish-cli tests 1. Update release-cli.yml to make create-release depend on publish-npm with proper skip_npm handling, preventing half-released state where GitHub Release exists but npm package is unavailable. 2. Rewrite publish-cli-test.sh to cover the new publish flow: main branch check, dirty tree detection, tag baseline sync, version bumping, tag conflict detection, user cancellation, and atomic push verification.

Add pre-flight check in publish-cli.sh to detect unpushed commits and tags from previous failed pushes. When detected, the script exits with clear recovery instructions: 1. Retry push (for transient network failures) 2. Rollback and re-release (for clean restart) This prevents the baseline sync logic from skipping failed versions when local tags participate in version calculation after a push failure. Addresses feedback from dongmucat in PR #422.

dongmucat · 2026-05-12T08:27:35Z

重新看了最新提交后，还有几个发布链路问题需要继续修复：

.github/workflows/release-cli.yml:143-149：npm 版本存在性检查仍然是二态判断。现在只有命中 404 才认为不存在，其它情况都会进入 exists=true，所以网络错误、registry 5xx、鉴权失败、DNS/TLS 问题都会被当成“版本已存在”并跳过 publish。建议改成三态：npm view 成功 = exists；明确 404 = missing；其它错误必须 fail job。
.github/workflows/release-cli.yml:30-42：workflow_dispatch 接收 tag 并用它提取版本，但 checkout 没有切到这个 tag，也没有验证 tag 存在。手动触发时可能构建的是 UI 里选中的分支 HEAD，却按输入 tag 创建 npm/GitHub Release。建议 checkout 指定 tag，并显式校验 tag 存在/当前 SHA 匹配。
scripts/publish-cli.sh:156 / scripts/tests/publish-cli-test.sh:252-269：脚本和测试文案已经在说 atomic push，但实际命令仍是 git push origin "$CURRENT_BRANCH" "$TAG"，没有 --atomic。测试 8 只是 happy path 验证 branch/tag 最终都存在，不能证明原子性；测试 9 也只是 origin URL 整体失败，没覆盖“一个 ref 成功、另一个 ref 失败”的场景。建议改成 git push --atomic origin "$CURRENT_BRANCH" "$TAG"，并补 partial-success/重跑恢复场景测试。

补充：现在 UNPUSHED_RELEASE_TAGS 用 git tag --no-merged origin/main 检测，会漏掉“branch push 成功但 tag push 失败”的状态，因为 tag 指向的 commit 已经在 origin/main 上。这个问题可以通过真正使用 atomic push 一并解决。

1. npm version check: three-state logic (exists/missing/error) to prevent silent skip on network failures, registry 5xx, or auth issues. 2. workflow_dispatch: checkout the specified tag and validate SHA matches, preventing builds from wrong ref. 3. Atomic push: use `git push --atomic` and detect unpushed tags via `git ls-remote` instead of `--no-merged` (catches branch-pushed-but- tag-failed state).

CheneyH · 2026-05-12T09:18:04Z

已修复，见 70b962a：

问题 1 - npm 版本检查三态处理：改为三态逻辑：

npm view 成功（exit 0）→ exists，跳过发布
输出匹配 404/Not Found → missing，继续发布
其它情况（网络错误、5xx、鉴权失败等）→ fail job，防止静默跳过

问题 2 - workflow_dispatch tag 校验：

checkout 增加 ref: ${{ github.event.inputs.tag || github.ref }}，确保构建的是 tag 指向的代码
新增 validate step：验证 tag 存在且当前 checkout SHA 与 tag SHA 一致

问题 3 - 原子性推送：

git push 改为 git push --atomic origin "$CURRENT_BRANCH" "$TAG"
未推送检测从 git tag --no-merged 改为逐个 git ls-remote --exit-code 对比本地 tag，解决"branch push 成功但 tag push 失败"时 --no-merged 漏检的问题
新增测试覆盖 tag-only 未推送检测场景和 --atomic 参数验证

dongmucat · 2026-05-12T09:26:02Z

还有一个需要修复的点：

.github/workflows/release-cli.yml:136 的 publish-npm job 重新 checkout 时没有指定 ref。现在 build-and-test 已经会在 workflow_dispatch 场景下 checkout 输入的 tag 并校验 SHA，但 publish-npm 默认 checkout 的仍是触发 workflow 的分支/默认 ref，然后只把 cli/package.json 改成 tag 版本再 build/publish。

这样手动触发时可能出现 GitHub Release artifact 来自指定 tag，但 npm 包实际来自另一个提交的情况。建议 publish-npm 的 checkout 和 build-and-test 保持一致，例如：

- name: Check out repository
  uses: actions/checkout@v4
  with:
    ref: ${{ github.event.inputs.tag || github.ref }}

最好也复用或补充同样的 tag/SHA 校验，确保 npm publish 的源码和 build artifact 对应同一个 ref。

publish-npm and create-release now checkout the same ref as build-and-test (the input tag or push ref), preventing source mismatch between npm package and GitHub Release artifacts.

CheneyH · 2026-05-12T09:30:13Z

已修复，见 eeb2540：

publish-npm 和 create-release 的 checkout 现在都统一指定 ref: ${{ github.event.inputs.tag || github.ref }}，与 build-and-test 保持一致，确保三个 job 构建/发布的源码来自同一个 ref。

This workflow runs scripts/tests/publish-cli-test.sh in CI to verify the publish script changes. Will be removed after verification.

Tests write stdout.log/stderr.log into the test repo root, which made `git status --porcelain` non-empty and broke test 3 (non-main branch abort) by tripping the dirty-tree check first. Add a .gitignore to the test fixture repo to filter out these files.

Old test 7 used `--no-tags` config to prevent fetch from pulling the remote tag, but that doesn't reflect any real-world scenario. With the new baseline sync logic, a pre-existing remote tag would be synced into the local version, eliminating the conflict path the test claimed to cover. Replace with a git wrapper that injects the conflicting tag into origin right before the script's `ls-remote` check, which simulates a real race between two developers attempting to release the same version.

Remove test 7 (remote tag race condition) — the scenario is nearly impossible with the new baseline sync logic and too complex to reliably simulate. Fix variable naming inconsistencies from the renumbering.

The old approach (breaking origin URL) caused `git pull` to fail before reaching the push step. Use a git wrapper that only fails on `push` so the rest of the script runs normally.

The `status="$(env ... printf | bash ... && echo 0 || echo $?)"` pattern doesn't correctly capture the script's exit code because the command substitution and pipe interact poorly. Use direct assignment with `|| status=$?` instead.

The script calls `git -C /path push ...` so the first arg is `-C`, not `push`. Use glob match on full args instead.

gemini-code-assist Bot reviewed May 12, 2026

View reviewed changes

fix(cli): push branch and tag atomically in publish-cli.sh

490ddfa

This comment was marked as duplicate.

Sign in to view

CheneyH added 2 commits May 12, 2026 16:12

CheneyH force-pushed the feat/cli-auto-build branch from 6957136 to 8126faa Compare May 12, 2026 08:15

fix(cli): align checkout ref across all workflow jobs

eeb2540

publish-npm and create-release now checkout the same ref as build-and-test (the input tag or push ref), preventing source mismatch between npm package and GitHub Release artifacts.

CheneyH added 9 commits May 12, 2026 17:53

test(ci): add temporary workflow to test publish-cli script

1420ffa

This workflow runs scripts/tests/publish-cli-test.sh in CI to verify the publish script changes. Will be removed after verification.

test(cli): add debug logging to race-condition test wrapper

1c29cfa

fix(cli): remove unreliable race-condition test, renumber tests

c520f38

Remove test 7 (remote tag race condition) — the scenario is nearly impossible with the new baseline sync logic and too complex to reliably simulate. Fix variable naming inconsistencies from the renumbering.

fix(cli): use git wrapper for push-failure test

935054c

The old approach (breaking origin URL) caused `git pull` to fail before reaching the push step. Use a git wrapper that only fails on `push` so the rest of the script runs normally.

fix(cli): match 'push' anywhere in git args, not just $1

48174c9

The script calls `git -C /path push ...` so the first arg is `-C`, not `push`. Use glob match on full args instead.

chore(ci): remove temporary publish-script test workflow

f59a10e

dongmucat merged commit 9dfbed2 into main May 14, 2026
7 checks passed

CheneyH mentioned this pull request May 15, 2026

refactor(cli): improve publish-cli script reliability #441

Open

4 tasks

-    node -e "
-      const fs = require('fs');
-      const pkg = JSON.parse(fs.readFileSync('$PACKAGE_JSON', 'utf8'));
-      pkg.version = '$BASE_VERSION';
-      fs.writeFileSync('$PACKAGE_JSON', JSON.stringify(pkg, null, 2) + '\n');
-    "
+    node -e '
+      const fs = require("fs");
+      const [path, version] = process.argv.slice(1);
+      const pkg = JSON.parse(fs.readFileSync(path, "utf8"));
+      pkg.version = version;
+      fs.writeFileSync(path, JSON.stringify(pkg, null, 2) + "\n");
+    ' "$PACKAGE_JSON" "$BASE_VERSION"

		NPM_VERSION_OUTPUT="$(cd "$CLI_DIR" && npm version "$BUMP_TYPE" --no-git-tag-version)"
		NEW_VERSION="${NPM_VERSION_OUTPUT#v}"

		git -C "$REPO_ROOT" push origin "$CURRENT_BRANCH"
		git -C "$REPO_ROOT" push origin "$TAG"

Conversation

CheneyH commented May 12, 2026

Summary

How to release

Test plan

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot May 12, 2026

Choose a reason for hiding this comment

Uh oh!

CheneyH May 12, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 12, 2026

Choose a reason for hiding this comment

Uh oh!

CheneyH May 12, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 12, 2026

Choose a reason for hiding this comment

Uh oh!

CheneyH May 12, 2026

Choose a reason for hiding this comment

Uh oh!

This comment was marked as duplicate.

Uh oh!

dongmucat commented May 12, 2026

Uh oh!

dongmucat commented May 12, 2026

Uh oh!

CheneyH commented May 12, 2026

Uh oh!

CheneyH commented May 12, 2026

Uh oh!

dongmucat commented May 12, 2026

Uh oh!

CheneyH commented May 12, 2026

Uh oh!

dongmucat commented May 12, 2026

Uh oh!

CheneyH commented May 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants