gitlab-commit-guard

一个用于规范 GitLab commit 输入的轻量级工具，同时提供 VS Code 扩展命令。

它提供两类能力：

• commit-msg hook 校验提交信息是否符合团队规范
• prompt 交互式生成 commit message，减少手输出错
• VS Code 命令面板里生成和校验 commit message
• 支持通过 benchamark 关键词触发 benchmark test

默认规范

默认采用以下格式：

<type>(<scope>): <subject>

Refs: [#123](https://github.com/your-account/gitlab-commit-guard/issues/123)

示例：

feat(user): add login audit log

Refs: [#128](https://github.com/your-account/gitlab-commit-guard/issues/128)

或：

fix: resolve null pointer on profile query

Closes: [group/project#245](https://github.com/group/project/issues/245)

如果需要触发 benchmark test，可以追加一行：

benchamark

或者带一个或多个 tag：

benchamark tag: smoke, release

VS Code 用法

安装扩展后，在命令面板中运行：

• GitLab Commit Guard: Generate Commit Message
• GitLab Commit Guard: Validate Commit Message

生成命令会：

• 引导你依次输入 type、scope、subject、issue
• 如果开启了 benchmark 配置，还会询问是否追加 benchamark
• 会在填写前从可配置的后台拉取可选 tag 列表
• 自动生成 commit message
• 自动复制到剪贴板
• 在新的编辑器标签页中打开结果

校验命令会：

• 校验当前编辑器全文
• 如果有选中文本，则只校验选中内容

可用命令

安装 hook：

node ./bin/gitlab-commit-guard.js install

校验单条提交信息：

node ./bin/gitlab-commit-guard.js validate --message "feat(api): add order query"

交互式生成提交信息：

node ./bin/gitlab-commit-guard.js prompt

直接发起 git commit：

node ./bin/gitlab-commit-guard.js prompt --commit

配置

CLI 模式下，可以在仓库根目录放置 .gitlab-commit-guard.json：

{
  "requireScope": false,
  "requireIssue": true,
  "issuePrefixes": ["Refs", "Closes"],
  "benchmark": {
    "enabled": true,
    "keyword": "benchamark",
    "tagLabel": "tag",
    "tagApiUrl": "https://example.com/api/benchmark/tags",
    "tagRequestHeaders": {
      "Authorization": "Bearer <token>"
    },
    "tagResponsePath": "data.tags",
    "tagNameField": "name"
  }
}

接口返回支持两种常见格式：

["smoke", "release", "ios"]

或：

{
  "data": {
    "tags": [
      { "name": "smoke" },
      { "name": "release" }
    ]
  }
}

说明：

• benchmark.enabled 为 true 时才会启用 benchmark 交互和校验
• benchmark.keyword 默认是 benchamark
• benchmark.tagApiUrl 配置后会在生成 commit message 前在线拉取 tags
• benchmark.tagResponsePath 用于从接口返回中找到 tag 数组
• benchmark.tagNameField 用于从对象数组中取 tag 名称

VS Code / Cursor 中给用户配置 benchmark.tagApiUrl

如果是扩展使用者，不需要改仓库文件，可以直接在编辑器设置里配置。

打开 Settings，搜索 GitLab Commit Guard，然后设置：

• gitlabCommitGuard.benchmark.enabled
• gitlabCommitGuard.benchmark.tagApiUrl
• gitlabCommitGuard.benchmark.tagResponsePath
• gitlabCommitGuard.benchmark.tagNameField
• gitlabCommitGuard.benchmark.tagRequestHeaders

也可以直接写进 settings.json：

{
  "gitlabCommitGuard.benchmark.enabled": true,
  "gitlabCommitGuard.benchmark.tagApiUrl": "https://example.com/api/benchmark/tags",
  "gitlabCommitGuard.benchmark.tagResponsePath": "data.tags",
  "gitlabCommitGuard.benchmark.tagNameField": "name",
  "gitlabCommitGuard.benchmark.tagRequestHeaders": {
    "Authorization": "Bearer <token>"
  }
}

这些扩展设置会优先于仓库里的 .gitlab-commit-guard.json。

推荐接入方式

1. 把这个项目发布为内部 npm 包，供团队统一安装。
2. 在业务仓库执行 gitlab-commit-guard install 安装 commit-msg hook。
3. 在团队规范中统一要求使用 prompt 或遵循同一 commit 格式。

发布到 VS Code Marketplace 前需要修改

发布前请先修改 package.json 中这两个字段：

• publisher
• repository.url