Files
eng-standards-main/templates/ci_gate.py
T
姚章浩 7090aafefc fix(template): 通用门禁真执行 Python/前端/安全项,预览先核对报告再发布
ci-gate.py:Python 的依赖/格式/静态/构建/测试改成真的执行(uv sync --frozen / uv run ruff / compileall / uv run pytest),工具缺失即失败,不再空跑成功;前端测试把子进程退出码当判据(报告写 pass 但退出 1 也判红),框架按 test-scope.json 声明而不是写死 vitest;清单新增 security(密钥扫描 + 依赖漏洞)。预览逻辑进 ci_preview.py:先调 ci_report.verify(),核对不过一个 publish 请求都不发。检出进 ci_checkout.sh:协议原样保留并断言不降级、URL 不放凭据、顺带取事件 before。workflow 收成单作业,不再用 /tmp 跨作业传文件。
2026-10-12 11:15:31 +08:00

420 lines
22 KiB
Python
Executable File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#!/usr/bin/env python3
"""提交信息规范校验(CI 侧权威闸门)。
规则与本机 ~/.githooks/commit-msg 完全一致,防止 --no-verify 绕过。
放行:Merge / Revert " / fixup! / squash! / amend! 开头的自动生成提交。
**校验范围必须是"本次这一批"**,按优先级取,取不到就报错 —— 不回退成"最近 N 条":
1. `CI_COMMIT_RANGE=A..B`(显式指定,调试/重放用);
2. Gitea 事件负载:`commits[]`(推送事件自带本次推送的每一条);
并且核对负载里的 `after` 与当前 HEAD 一致 —— 不一致说明事件与检出不是同一批;
3. 本地:`git log --not --remotes`(还没推到任何远端的提交 = 本次要推的范围);
本地**一个远端都没有**时,明确只核 HEAD(`--not --remotes` 在那种情况下会退化成整部历史,
连 Initial commit 都算进来 —— 那不是"本次改动")。
为什么不能退化成 `git log -n 5`:那个范围和"本次改动"没有任何关系。
典型假红/假绿两种情况都会发生 —— 五条里混进一条历史坏记录(假红,且红在别人头上),
或者本次推的第 6 条以后有坏记录(假绿,直接放过去)。两种都不是"检查",是噪声。
用法:
python3 .gitea/scripts/ci_gate.py # 按上面的优先级取范围
python3 .gitea/scripts/ci_gate.py --range HEAD~1..HEAD # 显式指定
python3 .gitea/scripts/ci_gate.py --self-test # 反向自检(临时仓库,四种范围)
"""
import argparse
import json
import os
import re
import shlex
import subprocess
import sys
import tempfile
TYPES = "feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert"
RE = re.compile(r"^(?:" + TYPES + r")(?:\([a-zA-Z0-9._/-]+\))?!?: .{3,}$")
ALLOW = re.compile(r'^(?:Merge |Revert "|fixup! |squash! |amend! )')
HELP = """
❌ 提交信息不合规,已拦截。
规范 : <类型>(<范围>): <简短描述>
类型 : feat 新功能 | fix 修缺陷 | docs 文档 | style 格式(不改逻辑)
refactor 重构 | perf 性能 | test 测试 | build 构建/依赖
ci CI 配置 | chore 杂务 | revert 回滚
示例 : feat(asset): 新增按歌曲生成应援序列
fix(parser): 修复表格解析越界导致的 500
docs: 补充 OSS 短签名接口说明
要点 : 类型小写、冒号后一个空格、描述 ≥3 字符
标题 ≤72 字符、结尾不加句号
破坏性变更类型后加 !,正文写 BREAKING CHANGE:
详见 : docs/提交规范.md
"""
def git(*args, cwd=None):
p = subprocess.run(["git", *args], cwd=cwd, capture_output=True, text=True)
return p.returncode, p.stdout, p.stderr
def subject_of(m: str) -> str:
for line in m.splitlines():
s = line.strip()
if not s or s.startswith("#"):
continue
return s
return ""
def judge(subj: str) -> str:
if not subj:
return "空提交信息"
if ALLOW.match(subj):
return ""
if len(subj) > 72:
return "标题 %d 字符 > 72" % len(subj)
if not RE.match(subj):
return "不符合 <类型>(<范围>): <描述>"
if subj.endswith(".") or subj.endswith("\u3002"):
return "标题结尾不要加句号"
return ""
def _range_commits(spec: str, cwd=None):
# spec 可能是一个 rev 范围(A..B),也可能是带开关的写法(--not --remotes)——
# 必须拆成多个参数,整串当**一个** argv 会被 git 判成"未能识别的参数"(实测踩过)。
rc, out, err = git("log", "--format=%H%x00%B%x00%x00", *shlex.split(spec), cwd=cwd)
if rc != 0:
return None, f"范围 {spec} 取不到提交:{(err or out).strip()[:200]}"
msgs = [x for x in out.split("\x00\x00") if x.strip()]
out_msgs = []
for chunk in msgs:
parts = chunk.split("\x00", 1)
out_msgs.append({"sha": parts[0].strip(), "message": parts[1] if len(parts) > 1 else ""})
return out_msgs, ""
def _payload(env):
"""读事件负载。返回 (payload, 错误)。错误非空 ⇒ 范围无法确定。"""
ev = (env.get("GITHUB_EVENT_PATH") or "").strip()
if not ev or not os.path.exists(ev):
return {}, ""
try:
with open(ev, encoding="utf-8") as fh:
d = json.load(fh)
except Exception as e:
return None, f"事件负载解析失败({e})—— 范围无法确定,不许放行"
if not isinstance(d, dict):
return None, "事件负载不是 JSON 对象 —— 范围无法确定,不许放行"
return d, ""
def resolve_scope(explicit="", env=None, cwd=None):
"""返回 (提交列表, 来源说明, 错误)。错误非空 ⇒ 不许放行。
**范围以 Git 为准,不拿事件负载里那一串当依据**:负载可能是截断的(实测声明 6 条、
列表只给 1 条),而且负载来自事件、代码来自检出,两者本来就可能不是同一批。
"""
env = env if env is not None else os.environ
in_ci = bool(env.get("GITHUB_ACTIONS"))
zero = "0" * 40
spec = (explicit or env.get("CI_COMMIT_RANGE", "") or "").strip()
if spec:
commits, err = _range_commits(spec, cwd)
if err:
return [], "", err
if not commits and in_ci:
return [], f"显式范围 {spec}", (f"显式范围 {spec} 为空 —— 空范围没有可核的提交,"
f"在 CI 里必须显式拒绝,不许静默通过")
return commits, f"显式范围 {spec}", ""
d, err = _payload(env)
if err:
return [], "", err
event = str(d.get("event_name") or env.get("GITHUB_EVENT_NAME") or "").strip()
after = str(d.get("after") or env.get("GITHUB_SHA") or "").strip()
before = str(d.get("before") or "").strip()
listed = [{"sha": str(c.get("id") or c.get("sha") or ""), "message": str(c.get("message") or "")}
for c in (d.get("commits") or []) if isinstance(c, dict)]
declared_raw = d.get("total_commits")
for label, v in (("before", before), ("after", after)):
if v and not set(v) <= set("0123456789abcdef"):
return [], "", f"事件负载的 {label} 不是 SHA:{v[:20]!r}"
if after and after != zero:
rc, head, _ = git("rev-parse", "HEAD", cwd=cwd)
head = head.strip()
if rc != 0 or head != after:
return [], "", (f"事件负载 after={after[:12]} 与当前 HEAD={head[:12]} 不一致 —— "
f"事件与检出不是同一批,范围无法确定")
# ── ① 推送事件:before..after 是权威范围 ─────────────────────────────
if before and after and after != zero:
if before == zero:
spec2 = f"{after} --not --remotes" # 新分支:远端没有这个分支的历史
src = "新分支推送(before 为全 0)⇒ 范围 = after 之后未被远端覆盖的提交"
else:
spec2 = f"{before}..{after}"
src = f"事件 Git 范围 {before[:12]}..{after[:12]}"
commits, gerr = _range_commits(spec2, cwd)
if gerr:
return [], src, (
f"{gerr}。若这是浅克隆(CI 检出默认 `--depth 50`),before 可能根本不在克隆里 —— "
f"**范围不全就是漏查**,不许放行:提高 fetch 深度,或用 --range 显式指定。")
if not commits:
return [], src, ("本次推送的 Git 范围是空的(before == after?)—— 空范围没有可核的提交,"
"不许静默通过")
if declared_raw not in (None, ""):
try:
declared = int(declared_raw)
except (TypeError, ValueError):
return [], src, f"事件负载 total_commits 不是整数:{declared_raw!r}"
if declared != len(commits):
return [], src, (
f"事件声明 {declared} 条提交,但 Git 范围算出 {len(commits)} 条"
f"(负载列表给了 {len(listed)} 条)—— 两边的'本次范围'对不上,"
f"谁也不能采信,不许放行")
if declared != len(listed):
src += (f"(⚠️ 事件列表被截断:声明 {declared} 条、列表只给 {len(listed)} 条"
f" ⇒ 以 Git 范围为准)")
else:
src += "(与事件列表一致)"
elif len(listed) != len(commits):
src += (f"(⚠️ 事件列表 {len(listed)} 条、Git 范围 {len(commits)} 条"
f" ⇒ 以 Git 范围为准)")
return commits, src, ""
# ── ② 负载里有 commits 但没有 before:用列表,但**没有 Git 范围可交叉核对**,要写明 ──
if listed and not before:
bad = [c["sha"][:12] for c in listed
if not c["sha"] or git("cat-file", "-e", c["sha"], cwd=cwd)[0] != 0]
if bad:
return [], "", (f"事件列表里的提交在检出里不存在:{bad[:3]} —— "
f"事件与检出不是同一批,范围无法确定")
if declared_raw not in (None, ""):
try:
declared = int(declared_raw)
except (TypeError, ValueError):
return [], "", f"事件负载 total_commits 不是整数:{declared_raw!r}"
if declared != len(listed):
return [], "", (f"事件声明 {declared} 条提交、列表只给 {len(listed)} 条,"
f"而这次又没有 before 可以算 Git 范围 —— 列表被截断且无法交叉核对,"
f"不许拿截断后的列表去核")
return listed, ("事件列表 commits[](**没有 before,无法用 Git 范围交叉核对**)"
"—— 已逐条确认这些提交在检出里存在"), ""
# ── ② 手工运行 / 没有 before:与远端默认分支比,比不出来就只核 HEAD(写明)──
if in_ci or event == "workflow_dispatch" or after:
base = ""
rc, out, _ = git("symbolic-ref", "--short", "refs/remotes/origin/HEAD", cwd=cwd)
if rc == 0 and out.strip():
base = out.strip()
else:
_, out2, _ = git("for-each-ref", "--format=%(refname:short)", "refs/remotes/origin", cwd=cwd)
cand = [l.strip() for l in out2.splitlines() if l.strip().endswith(("/main", "/master"))]
base = cand[0] if cand else ""
if base:
commits, gerr = _range_commits(f"{base}..HEAD", cwd)
if gerr:
return [], "", gerr
if commits:
return commits, f"手工运行:取 {base}..HEAD(与远端默认分支比)", ""
note = f"手工运行:{base}..HEAD 为空(HEAD 与远端默认分支一致)"
else:
note = "手工运行:取不到远端默认分支(refs/remotes/origin 里没有 main/master)"
rc, head, _ = git("rev-parse", "HEAD", cwd=cwd)
head = head.strip()
if rc != 0 or not head:
return [], "", note + ",而且取不到 HEAD —— 范围无法确定"
rc2, body, _ = git("log", "-1", "--format=%B", cwd=cwd)
return ([{"sha": head, "message": body}],
note + " ⇒ **只核 HEAD 这一条提交**(已写明:这次比不出范围,不是'最近 N 条')", "")
# ── ③ 本地(无事件负载):未推到远端的提交 ───────────────────────────
# ⚠️ 先看有没有远端引用:**一个远端都没有**时,`--not --remotes` 会退化成"整部历史"
# (连 Initial commit 都算进来)—— 那不是"本次改动",而是一条历史坏记录就能让本地门禁常红。
# 这种情况明确只核 HEAD,并写明(要核更多用 --range)。
_, refs, _ = git("for-each-ref", "--format=%(refname)", "refs/remotes", cwd=cwd)
if not refs.strip():
if in_ci:
return [], "", ("在 CI 里既没有事件范围,也没有任何远端引用可以比 —— "
"范围无法确定,不许静默通过")
rc, head, _ = git("rev-parse", "HEAD", cwd=cwd)
head = head.strip()
if rc != 0 or not head:
return [], "", "本地:没有任何远端引用,也取不到 HEAD —— 范围无法确定"
_, body, _ = git("log", "-1", "--format=%B", cwd=cwd)
return ([{"sha": head, "message": body}],
"本地:没有可比远端(refs/remotes 为空)⇒ **只核 HEAD 这一条提交**"
"(要核更多请用 --range A..B)", "")
commits, err = _range_commits("HEAD --not --remotes", cwd)
if err:
return [], "", err
if commits:
return commits, "本地:范围 = 还没推到远端的提交(git log HEAD --not --remotes)", ""
if in_ci:
return [], "", ("在 CI 里范围为空(既没有事件范围,也没有未推送的提交)—— "
"空范围没有可核的提交,不许静默通过")
return [], "本地:本次范围为空(没有未推送的提交)", ""
def main(argv):
ap = argparse.ArgumentParser(add_help=True)
ap.add_argument("--range", default="")
ap.add_argument("--self-test", action="store_true")
args = ap.parse_args(argv)
if args.self_test:
return self_test()
commits, source, err = resolve_scope(explicit=args.range)
if err:
print(f"❌ 提交校验范围无法确定:{err}", file=sys.stderr)
print(" 处理:用 --range A..B 显式指定,或确认事件负载/远端引用可用。"
"(不会退化成'最近 N 条'—— 那个范围与本次改动无关)", file=sys.stderr)
return 1
print(f"校验范围:{source}|{len(commits)} 条提交")
bad = []
for c in commits:
subj = subject_of(c["message"])
why = judge(subj)
if why:
bad.append((subj, why))
print(" ❌ [%s] %s" % (why, subj))
else:
print(" ✅ %s" % subj)
try:
with open("/tmp/ci-gate-status", "w") as fh:
fh.write("failure" if bad else "success")
except OSError:
pass
if bad:
print(HELP)
return 1
print("✅ 本次范围的提交信息全部合规")
return 0
def self_test() -> int:
"""在临时仓库里造"range 准不准",四种情形都要符合预期。"""
problems = []
with tempfile.TemporaryDirectory() as d:
env = {"GIT_AUTHOR_NAME": "t", "GIT_AUTHOR_EMAIL": "t@t", "GIT_COMMITTER_NAME": "t",
"GIT_COMMITTER_EMAIL": "t@t"}
base = {**os.environ, **env}
subprocess.run(["git", "init", "-q", "-b", "main"], cwd=d, env=base, check=True)
# 夹具仓库里**不装**本机提交钩子(core.hooksPath 指到一个空目录):
# 这里要构造一条"违规提交"来验证闸门的范围取法,而本机钩子会先把它拦掉。
# 这不是绕过门禁 —— 沙箱仓本来就没有钩子,而且这条提交永远不会离开临时目录。
empty_hooks = os.path.join(d, "no-hooks")
os.makedirs(empty_hooks, exist_ok=True)
base["GIT_CONFIG_COUNT"] = "1"
base["GIT_CONFIG_KEY_0"] = "core.hooksPath"
base["GIT_CONFIG_VALUE_0"] = empty_hooks
def commit(msg):
subprocess.run(["git", "commit", "-q", "--allow-empty", "-F", "-"], cwd=d, env=base,
input=msg, text=True, check=True)
return subprocess.run(["git", "rev-parse", "HEAD"], cwd=d, capture_output=True,
text=True).stdout.strip()
good1 = commit("feat(a): 第一条合规\n")
bad = commit("update stuff\n") # 违规,但在历史里
good2 = commit("fix(b): 第三条合规\n")
# ① 范围只含最后一条(干净):即使历史里有违规也不许红 —— 证明不是"最近 N 条"
commits, src, err = resolve_scope(explicit=f"{bad}..{good2}", cwd=d)
if err or len(commits) != 1:
problems.append(f"显式范围没有取到恰好 1 条:{err or len(commits)}")
elif any(judge(subject_of(c["message"])) for c in commits):
problems.append("范围只含合规提交,却判成不合规")
# ② 范围含那条违规:必须红(good1..HEAD 覆盖 bad 与 good2)
commits, src, err = resolve_scope(explicit=f"{good1}..HEAD", cwd=d)
flagged = [c for c in commits if judge(subject_of(c["message"]))]
if err or len(commits) != 2 or len(flagged) != 1:
problems.append(f"范围含违规提交时没有恰好判出 1 条:{err or (len(commits), len(flagged))}")
# ③ 本地无事件负载:按"未推到远端的提交"取,且**不是**固定条数
os.environ.pop("GITHUB_EVENT_PATH", None)
os.environ.pop("CI_COMMIT_RANGE", None)
commits, src, err = resolve_scope(env={}, cwd=d)
if err or len(commits) != 1 or "最近" in src:
problems.append(f"无事件负载、无远端时没有按'只核 HEAD'取:{err or (len(commits), src)}")
# ④ 事件负载的 after 与 HEAD 不一致 ⇒ 报错,不许蒙
evf = os.path.join(d, "event.json")
with open(evf, "w", encoding="utf-8") as fh:
json.dump({"after": "f" * 40, "commits": [{"id": good2, "message": "fix(b): 第三条合规"}]}, fh)
commits, src, err = resolve_scope(env={"GITHUB_EVENT_PATH": evf}, cwd=d)
if not err:
problems.append("事件 after 与 HEAD 不一致时竟然没有报错")
# ⑤ 事件负载正常(after == HEAD)⇒ 用负载里的 commits
with open(evf, "w", encoding="utf-8") as fh:
json.dump({"after": good2, "commits": [{"id": good2, "message": "fix(b): 第三条合规"}]}, fh)
commits, src, err = resolve_scope(env={"GITHUB_EVENT_PATH": evf}, cwd=d)
if err or len(commits) != 1 or "commits[]" not in src:
problems.append(f"事件负载正常时没有按 commits[] 取:{err or (len(commits), src)}")
# ⑫ 本地一个远端都没有 ⇒ 只核 HEAD,并写明(不许退化成"整部历史")
commits, src, err = resolve_scope(env={}, cwd=d)
if err or len(commits) != 1 or "只核 HEAD" not in src:
problems.append(f"没有远端引用时没有退成'只核 HEAD 并写明':{err or (len(commits), src)}")
# ⑥ 负载声明 6 条、列表只给 1 条、Git 范围 2 条 ⇒ 对不上,必须报错(不许采信被截断的列表)
with open(evf, "w", encoding="utf-8") as fh:
json.dump({"before": good1, "after": good2, "total_commits": 6,
"commits": [{"id": good2, "message": "fix(b): 第三条合规"}]}, fh)
commits, src, err = resolve_scope(env={"GITHUB_EVENT_PATH": evf, "GITHUB_ACTIONS": "true"}, cwd=d)
if not err:
problems.append("事件声明 6 条、Git 范围 2 条时竟然没有报错(接受了被截断的列表)")
# ⑦ 声明 2 条、列表 1 条、Git 范围 2 条 ⇒ 用 Git 范围,并在来源里写明"列表被截断"
with open(evf, "w", encoding="utf-8") as fh:
json.dump({"before": good1, "after": good2, "total_commits": 2,
"commits": [{"id": good2, "message": "fix(b): 第三条合规"}]}, fh)
commits, src, err = resolve_scope(env={"GITHUB_EVENT_PATH": evf, "GITHUB_ACTIONS": "true"}, cwd=d)
if err or len(commits) != 2 or "截断" not in src:
problems.append(f"列表被截断但 Git 范围可用时没有以 Git 为准:{err or (len(commits), src)}")
# ⑧ 空范围(before == after)⇒ CI 里必须显式拒绝
with open(evf, "w", encoding="utf-8") as fh:
json.dump({"before": good2, "after": good2, "total_commits": 0, "commits": []}, fh)
commits, src, err = resolve_scope(env={"GITHUB_EVENT_PATH": evf, "GITHUB_ACTIONS": "true"}, cwd=d)
if not err:
problems.append("空范围(before == after)竟然没有报错")
# ⑨ 新分支推送(before 全 0)⇒ 用 after --not --remotes 取
with open(evf, "w", encoding="utf-8") as fh:
json.dump({"before": "0" * 40, "after": good2, "total_commits": 3, "commits": []}, fh)
commits, src, err = resolve_scope(env={"GITHUB_EVENT_PATH": evf, "GITHUB_ACTIONS": "true"}, cwd=d)
if err or len(commits) != 3 or "新分支" not in src:
problems.append(f"新分支推送没有按 after --not --remotes 取:{err or (len(commits), src)}")
# ⑩ 手工运行(没有事件负载、也没有远端可比)⇒ 只核 HEAD,并且**写明**这一点
commits, src, err = resolve_scope(env={"GITHUB_ACTIONS": "true"}, cwd=d)
if err or len(commits) != 1 or "只核 HEAD" not in src:
problems.append(f"手工运行没有退成'只核 HEAD 并写明':{err or (len(commits), src)}")
# ⑪ 列表里的提交在检出里不存在 ⇒ 事件与检出不是同一批,必须报错
with open(evf, "w", encoding="utf-8") as fh:
json.dump({"after": good2, "commits": [{"id": "d" * 40, "message": "fix(b): 第三条合规"}]}, fh)
commits, src, err = resolve_scope(env={"GITHUB_EVENT_PATH": evf, "GITHUB_ACTIONS": "true"}, cwd=d)
if not err:
problems.append("事件列表里的提交在检出里不存在,竟然没有报错")
if problems:
print("❌ 提交闸门自检失败:", file=sys.stderr)
for p in problems:
print(f" · {p}", file=sys.stderr)
return 1
print("✅ 提交闸门自检通过:范围取法 12 个分支(显式范围 / Git 范围 before..after / "
"负载声明与列表不一致 / 列表截断仍以 Git 为准 / 空范围拒绝 / 新分支 / 无 before 的列表 / "
"列表提交不在检出里 / after 与 HEAD 核对 / 手工运行只核 HEAD 并写明 / "
"无远端只核 HEAD / 未推送提交)")
return 0
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))