git

Git：多 Forge 生产工作流

执行 Git 操作、管理分支、处理多远程仓库设置、创建 PR/MR、发布版本，并在 GitHub、GitLab 和 Forgejo 上维护符合审计要求的变更历史。 目标是打造整洁、经过签名且可追溯的历史记录，同时满足工程标准和合规要求（PCI-DSS 4.0）。

目标版本（2026 年 10 月）：

• git：2.56.0（当前稳定版，2026-09-28）。新增功能包括 git refs 创建/删除/更新/重命名、fetch.followRemoteHEAD 和 git history drop；2.55 新增了 Linux fsmonitor、远程组推送和可并行执行的兼容钩子。
• GitHub CLI (gh)：2.102.0
• GitLab CLI (glab)：1.120.0
• Forgejo CLI (fj)：0.6.0（Codeberg 最新发布版，已于 2026-10-02 重新核实；fj pr merge --help 已于 9 月 25 日确认；源码位于 codeberg.org/forgejo-contrib/forgejo-cli）。使用 Rust 编写的官方社区 CLI。支持 PR（包括 AGit）、议题、仓库、发布版本、标签和 Actions。
• Forgejo：当前版本为 v16.0.5；当前 LTS 版本为 v15.0.9（两者均于 2026-09-17 发布）。严重的远程代码执行漏洞（CVE-2025-68937）已在 v13.0.2+ 中修复。
• prek：0.5.4（Rust，推荐）或 pre-commit：4.6.2（Python，生态最丰富）
• git-filter-repo：2.47.0
• gitleaks：8.30.1（密钥扫描）
• cosign：3.1.3（Sigstore，用于标签/发布签名场景）

此技能根据上下文涵盖五个领域：

• 操作 - 提交、分支、合并、变基、暂存、二分查找、reflog、恢复
• 远程仓库与 Forge - 多远程仓库设置、GitHub/GitLab/Forgejo 差异、镜像
• PR/MR 工作流 - 功能分支、评审流程、合并策略、发布版本
• 安全 - 提交签名、凭据管理、钩子、密钥扫描、历史记录清理
• 合规 - PCI-DSS 4.0 变更管理、审计跟踪、作为控制措施的分支保护

适用场景

• 创建提交（消息风格、签名、作者信息）
• 管理分支（创建、清理、保护、命名）
• 使用远程仓库（推送、拉取、获取、多远程同步）
• 创建 PR/MR（标题、说明、评审流程、合并策略）
• 发布版本（打标签、更新变更日志、发布 GitHub/Forgejo 版本）
• 解决合并冲突或执行变基
• 从错误中恢复（reflog、reset、revert、cherry-pick、bisect）
• 配置 git（别名、钩子、属性、凭据、签名）
• 清理历史记录中的敏感数据（filter-repo）
• 设置分支保护规则或规则集
• 多 Forge 工作流（镜像、令牌管理、SSH 密钥）
• PCI-DSS 变更管理证据

不适用场景

• CI/CD 流水线设计——使用 ci-cd；此技能处理流水线内部的 git 操作，而非流水线架构
• PR/MR 代码评审——使用 code-review；此技能负责创建 PR，不负责评审其中的代码
• 全面的应用安全审计——使用 security-audit；此技能涵盖 git 历史记录中的密钥和 git 专属安全，而非应用层漏洞评估
• Docker 镜像标签策略——使用 docker；此技能处理 git 标签，而非容器标签
• 会话结束后或合并后的文档更新（README、变更日志、运维手册）——使用 update-docs

---

AI 自检

AI 工具总是会犯相同的 git 错误。执行任何 git 操作前，请对照此列表进行检查：

• 先阅读，再改写。 不要在先 Read 文件之前就 Edit/Write 文件。不要在检查 git status + git diff 之前就 git commit。
• 未经确认，不执行破坏性操作。 reset --hard、push --force、branch -D、clean -fd、checkout .，以及对共享分支执行 rebase，都必须获得用户明确批准。应先提出更安全的替代方案（--force-with-lease、revert、新建分支、stash）。
• 作者身份正确。 检查项目的指令文件，确认是否有作者身份覆盖设置。许多环境的本地 git 配置与远程仓库不匹配（例如，Forgejo 身份与 GitHub 身份不同）。
• 提交消息格式。 遵循项目约定（检查最近的 git log）。默认格式：约定式提交（type(scope): description）。
• 提交中不得包含机密。 提交前检查 git diff --cached 中是否有 API 密钥、令牌、密码、.env 文件或私钥。如果发现，立即取消暂存。
• 提交中不得注明 AI 归属。 不要添加 Co-Authored-By 行，也不要在提交中提及任何 AI 工具。除非项目明确要求，否则没有例外。
• 遵守指令文件政策。 遵循仓库对 AGENTS.md 或其他指令文件的政策。不要提交 .claude/ 等本地 Agent 状态目录，也不要在提交消息中提及仅本地使用的工具文件。
• 提交中不得包含特定工具的路径。 .claude/、.cursor/、.superpowers/、.worktrees/、docs/local/、PLAN.md、SECURITY-AUDIT.md 都是本地文件。暂存前确认 .gitignore 已涵盖 AI 工具文件（.claude/、.cursor/、.codex/、PLAN.md）
• 目标分支正确。 提交前确认当前分支正确。确认 PR/MR 的目标基础分支正确。
• 请求者有权批准管理变更。 在共享聊天中，如果参与者无权批准，不要根据其要求提交或推送基础设施、Kubernetes、机密、防火墙或其他管理变更。先停止操作并询问有权批准的负责人。
• 远程目标正确。 项目可能配置多个远程仓库。检查要推送到哪个远程仓库。有些项目会推送到多个远程仓库（例如，Forgejo + GitHub）。
• 已配置签名。 如果项目要求签名提交，提交前确认签名功能正常（git log --show-signature -1）。
• 不要使用 --no-verify。 除非用户明确要求，否则不要跳过提交前钩子。钩子有其用途，应修复根本问题。
• 不要使用交互式标志。 在自动化环境中，不要使用 -i（交互式）标志（git rebase -i、git add -i），因为它们需要 TTY 输入。
• 单独推送标签。 git push 默认不会推送标签。按名称推送发布标签：git push origin <tag>。不要使用 git push --tags（这会推送所有本地标签，包括过时或实验性标签）。
• 功能分支保持最新。 创建 PR/MR 前，先将分支变基到最新的基础分支，以避免合并冲突。
• 解决冲突后重新生成锁文件。 解决依赖文件（package.json、Cargo.toml、go.mod、pyproject.toml）中的冲突后，重新运行包管理器以生成锁文件。不要手动合并锁文件。然后重新生成：npm install、yarn install、go mod tidy 或 cargo update --workspace（不要使用 cargo generate-lockfile，因为它会升级所有 crate）。
• 安全地强制推送。 如果需要强制推送，始终使用 --force-with-lease（如果远程有尚未获取的提交，则会拒绝推送）。使用普通的 --force 必须获得用户明确批准并与团队协调。
• 标注版本信息日期。 引用工具版本时，应注明日期，以便读者知道何时需要重新检查。过时的版本号可能导致问题在不知不觉中出现。
• 验证 Forge-CLI 子命令。 在运行手册、钩子或 CI 中编写 fj/gh/glab/tea 命令脚本前，确认目标版本支持相应子命令和标志（<cli> <cmd> --help）。这些 CLI 会在小版本更新中添加、重命名和移除子命令，文档可能落后于二进制程序。
• 已检查引用安全性：修改历史记录前，确认分支、远程仓库、上游和工作树路径
• 已知恢复方式：执行破坏性历史记录操作前，确保存在 reflog、备份分支或 bundle
• 落实跨领域 Agent 卫生规范——参见 references/agent-hygiene.md

---

性能

• 在扫描完整历史记录之前，先使用受路径限制的 git log、git diff 和 git grep。
• 在大型仓库中，如果不需要完整 prune，只获取所需的远程仓库／分支。
• 让提交足够小，便于审查和二分定位，但不要小到把同一行为拆分到多个提交中。

---

工作流

步骤 1：识别代码托管平台和项目背景

信号	代码托管平台
.github/ 目录、gh CLI	GitHub
.gitlab-ci.yml、glab CLI，用户说“工作”	GitLab
.forgejo/ 目录，用户说“家”	Forgejo
git remote -v 中有多个远程仓库	多平台

阅读项目的指令文件（AGENTS.md 或同等文件），了解：

• 提交约定（消息格式、作用域列表、作者身份覆盖规则）
• 分支策略（主干开发、功能分支、发布分支）
• 远程仓库设置（有哪些远程仓库、应推送到哪里、SSH 密钥）
• 发布流程（版本升级文件、标签格式、变更日志）
• 签名要求（GPG、SSH 或不签名）
• 内容限制（Git 历史记录中不得出现的域名、工具名称、路径）

步骤 2：确定操作

• “提交这个”／“保存我的工作” -> 提交工作流（步骤 3a）
• “创建 PR/MR” -> PR/MR 工作流（步骤 3b）
• “发布一个版本” -> 发布工作流（步骤 3c）
• “修复这团乱麻”／“撤销”／“恢复” -> 恢复操作（步骤 3d）
• “拉取失败”／“分支已分叉” -> 分叉分支处理（步骤 3e）
• “拉取／更新某目录下的所有仓库” -> 批量仓库更新工作流（步骤 3f）
• “设置签名”／“配置 git” -> 配置（参阅相关资料）
• “清理历史记录”／“清除密钥” -> 重写历史记录（参阅相关资料）
• “设置分支保护” -> 保护规则（参阅相关资料）

步骤 3a：提交工作流

复制此清单并跟踪进度：

• 检查状态和差异
• 仅暂存选定的文件
• 检查已暂存的差异（机密信息、调试代码、无关更改）
• 按照项目约定编写提交消息
• 按要求设置作者信息并签名后提交
• 推送前验证作者信息和签名

1. 检查状态：运行 git status（大型仓库中绝不使用 -uall）和 git diff（检查已暂存和未暂存的内容）
2. 有选择地暂存：运行 git add <specific files>——检查所含内容之前，绝不运行 git add -A 或 git add .。检查机密信息、二进制文件、生成文件和 AI 工具产物。
3. 检查差异：运行 git diff --cached——仔细查看即将提交的内容。留意调试代码、TODO 注释以及对无关文件的意外更改。如果有任何内容不应包含在内，请将其取消暂存（git restore --staged <file>），然后返回步骤 2。
4. 编写提交消息：遵循项目约定。默认格式：

type(scope): concise description

Optional body explaining *why*, not *what*.

从以下类型中选择 type：feat、fix、docs、refactor、chore、ci、build、revert。 扩展类型（仅在项目约定允许时使用）：test、perf、security。 务必先检查项目的指令文件和最近的 git log——项目可能使用不同的类型列表或命名约定。项目指令优先于这些默认规则。

作用域强烈建议使用，但不强制要求。作用域可增加上下文，让 git log --oneline 更易浏览：fix(auth): token expiry 比 fix: token expiry 更清晰。请使用组件、模块或领域的名称。仅当更改确实涉及多个领域，或项目不使用作用域时，才省略作用域。

破坏性更改：在类型或作用域后加上 !：feat(api)!: drop v1 endpoints。 如需详细说明破坏性更改，请在提交消息正文的页脚中添加 BREAKING CHANGE:。

消息指南：

• 使用祈使语气（“add feature”，而不是“added feature”或“adds feature”）
• 首行不超过 72 个字符
• 正文每行不超过 72 个字符
• 说明进行更改的原因，而不是更改了什么（差异已展示更改内容）
• 适用时注明问题或工单编号
• 语气自然、像真人。 像一位称职的人类撰写的，而不是 AI。 好例子：fix(caddy): self-healing volume permissions、feat(auth): add OIDC login 不佳示例：“fix stuff”、“wip”、“update files”、“enhance the robustness of the authentication module”
• 仅使用纯 ASCII 字符。 提交消息中不得使用破折号、弯引号、连字或花式标点。
• 提交消息或正文中绝不提及本地指令文件或 AI 工具。 如果在更新代码的同时更新了仅本地使用的指令文件，请勿将其纳入提交。
• 绝不添加 Co-Authored-By 或 AI 署名行。 不要添加 Signed-off-by: AI。不要在提交元数据中提及具体的 AI 工具。

5. 提交：根据项目配置，使用所需的作者信息覆盖设置和签名标志。
6. 验证：运行 git log -1 --format="%h %s%n Author: %an <%ae>%n Committer: %cn <%ce>"——推送前检查作者信息是否正确。如果有误且提交尚未推送，请修正身份配置，运行 git commit --amend --reset-author --no-edit，然后重复此步骤。

步骤 3b：PR/MR 工作流

首先检查：项目是否使用功能分支？阅读项目说明文件。有些项目（尤其是个人项目）倾向于直接在 main 上工作。此处的默认流程假设采用带评审的协作开发。请根据项目的实际工作流进行调整。

阅读 references/forge-workflows.md，了解特定代码托管平台的 PR/MR 创建方式（GitHub gh pr create、GitLab glab mr create、Forgejo fj pr create，或 Web UI/API）。 先检测代码托管平台的 CLI（command -v gh、glab 或 fj）；若未安装，请使用该参考文档中的安装表或 REST API 备用方案。

根据差异和仓库策略选择验证方式。仅仅打开 PR 并不足以成为运行完整构建、集成测试套件或发布流水线的理由。运行受影响的检查，并遵守必需的合并门禁；对于相同修订版本和相关输入，复用已通过的结果。如果 CI 做了不必要的工作，请使用 ci-cd 调整其触发条件和任务范围，而不是绕过检查或反复触发完整流水线。

常规流程：

1. 创建功能分支：git checkout -b type/short-description（例如 feat/user-search、fix/auth-bypass）。分支名使用小写字母和连字符，并以类型为前缀。

2. 进行更改：尽早提交，频繁提交。每次提交都应是一个逻辑单元。

3. 变基到基分支：git fetch origin && git rebase origin/main（或实际的基分支）。解决冲突：查找 <<<<<<<、=======、>>>>>>> 标记，保留双方的正确内容（通常双方新增的内容都应保留），然后运行 git add 和 git rebase --continue。解决依赖文件（package.json、Cargo.toml、go.mod 等）中的冲突后，重新运行包管理器以重新生成锁文件。绝不要将基分支合并到功能分支。有关合并策略的指导，请参阅 references/forge-workflows.md。

   依赖文件冲突（package.json、go.mod、pyproject.toml）：保留两个分支新增的内容；当同一依赖的版本固定值冲突时，协调两个分支的约束和意图，然后让包管理器解析出兼容版本，并验证受影响的行为。绝不要手动编辑锁文件——解决清单冲突后，务必运行包管理器（npm install、go mod tidy、uv sync 等）重新生成锁文件。解决依赖清单冲突时，不要使用 --ours 或 --theirs——这会悄无声息地丢弃某个分支新增的内容。

4. 推送：git push -u origin feat/short-description。然后确认远程分支确实已更新：将 git rev-parse HEAD 与代码托管平台 PR/MR 的头 SHA 进行比较（使用 gh pr view ...、glab mr view ... 或代码托管平台 API）。不要仅依赖简略输出或别名推送包装器。如果缺少上游跟踪或配置异常，请明确推送确切的 refspec，并再次检查 PR/MR 的头部，确认更新已生效后再作说明。

5. 创建 PR/MR：标题清晰（少于 70 个字符），正文包含摘要和测试计划。

6. 评审周期：默认通过后续提交处理反馈。只有在获得用户明确确认并重新获取最新信息后，才可在私有功能分支上使用 --force-with-lease 进行变基并推送。绝不要重写共享分支的历史。

7. 合并：为保持历史整洁，默认使用压缩合并；如果提交历史有意义，也可使用变基合并。

8. 清理：合并后删除远程分支。在本地运行 git branch -d feat/short-description。

分支命名约定：

• feat/description - 新功能
• fix/description - 修复错误
• refactor/description - 代码重构
• chore/description - 维护、依赖、配置
• docs/description - 仅文档更改
• ci/description - CI/CD 更改
• security/description - 安全修复（考虑是否应改为私密安全公告）

步骤 3c：发布工作流

阅读 references/forge-workflows.md，了解特定 Forge 的发布创建方式。

版本方案：语义化版本 vMAJOR.MINOR.PATCH，可选预发布后缀。

版本	时机	CI 行为
v0.12.0-alpha.1	新次版本开始，迭代新功能	创建标签并发布（标记为预发布）。是否构建镜像视项目而定。
v0.12.0-alpha.2	继续迭代，尚未稳定	同上。
v0.12.0	功能稳定，可用于生产环境	完整发布：创建标签并发布、构建镜像、部署。
v0.12.1	稳定版本的补丁修复	完整发布。

Alpha 工作流：

• 开始新次版本的工作时，标记 vX.Y.0-alpha.1
• 迭代时递增 alpha 编号（-alpha.2、-alpha.3）
• 稳定后，移除 -alpha 后缀并发布 vX.Y.0
• Alpha 标签仍会创建 GitHub/Forgejo 发布（标记为 --prerelease），以便 CI 按需构建镜像
• 项目说明文件会定义 Alpha 标签是否触发镜像构建

复制此清单并跟踪进度：

• 已更新版本文件
• 已创建版本更新提交
• 已创建附注标签
• 已将提交和标签推送到每个发布远程仓库
• 已创建 Forge 发布
• 已确认发布流水线已针对该标签运行

常规流程：

1. 更新版本：更新所有版本文件（查看项目说明文件中的列表——每个项目都不同）。
2. 提交：chore: bump version to X.Y.Z（或 chore: bump version to X.Y.Z-alpha.N）
3. 标记：git tag -a vX.Y.Z -m "vX.Y.Z"（使用附注标签，而非轻量标签）。
4. 推送：推送提交和标签。git push origin main && git push origin vX.Y.Z。如果有多个远程仓库，则全部推送。
5. 创建发布：GitHub（gh release create）、GitLab（glab release create）或 Forgejo（API/网页）。 对于 Alpha/预发布版本：gh release create vX.Y.Z-alpha.N --prerelease --title "vX.Y.Z-alpha.N"
6. 验证：检查 CI/CD 是否识别了该标签并启动发布流水线。如果没有，请确认标签已推送到远程仓库（git ls-remote --tags origin vX.Y.Z）且符合工作流的标签触发条件，然后返回步骤 4。

生成变更日志：默认使用项目已有的工具。如果没有，则在 GitHub 上使用 gh release create --generate-notes（生成自上一个标签以来的 PR 标题）；如果项目维护已提交的 CHANGELOG.md，则使用 git-cliff。! 标记和一致的作用域都能让这两种输出更有用。

步骤 3d：恢复操作

阅读 references/recovery-and-maintenance.md，了解详细的恢复流程 （reflog、bisect、rerere、filter-repo 等）。

Git 几乎不会丢失数据。Reflog 的保留期限可配置：默认情况下，可达条目的保留期限为 90 天，不可达条目为 30 天；过期清理和 GC 可能会删除恢复数据。

快速参考：

• 撤销上一次提交（保留更改）：git reset --soft HEAD~1
• 撤销上一次提交（丢弃更改）：git reset --hard HEAD~1 - 有破坏性，请先确认
• 还原已推送的提交：git revert <sha>（创建新提交，对共享分支安全）
• 查找丢失的提交：git reflog - 显示保留的 HEAD 变更记录；不要假定恢复窗口固定不变
• 查找导致问题的提交：git bisect start && git bisect bad && git bisect good <sha>
• 使用测试脚本自动 bisect：git bisect start HEAD v1.0.0 && git bisect run bun test src/auth.test.ts - 在每个 bisect 步骤自动运行测试。退出代码：0 = 正常，1-127（125 除外）= 异常，125 = 跳过此提交，128-255 = 立即中止 bisect。非常适合与 CI 集成：git bisect run ./scripts/ci-check.sh
• 压缩最近 N 个提交（不使用交互式变基）：git reset --soft HEAD~N && git commit -m "feat: combined change" - 重置 N 个提交，但保留所有已暂存的更改，然后将它们作为一个提交提交。在自动化场景中比 git rebase -i 更安全。
• 恢复已删除的分支：git reflog，找到 SHA，然后执行 git checkout -b branch-name <sha>
• 从历史记录中清除密钥：检查 command -v git-filter-repo >/dev/null || { echo "install git-filter-repo (pipx install git-filter-repo, or the distro package)" >&2; exit 1; }，如果缺少则停止；然后将 GIT_FILTER_REPO_REPLACEMENTS 设置为一个权限为 0600 的临时替换文件，该文件内容从密钥管理器读取，或通过不回显的标准输入填充；随后运行 : "${GIT_FILTER_REPO_REPLACEMENTS:?set a mode-0600 replacement file}"，再运行 git filter-repo --replace-text "$GIT_FILTER_REPO_REPLACEMENTS"。使用后正常删除临时文件。切勿将泄露的值放入 argv、命令文本或 shell 历史记录中。然后与团队协调，在获得明确批准后，使用逐个引用的 --force-with-lease 和重写前的 bundle（参见参考资料），强制推送所有分支和标签。参见参考资料。

---

步骤 3e：解决分歧分支

当 git pull 因“divergent branches”失败，或 git status 显示“have diverged”时：

1. 了解分歧情况：运行 git log --oneline HEAD..origin/branch（远程拥有的提交）和 git log --oneline origin/branch..HEAD（本地拥有的提交）。
2. 根据具体情况选择策略：
   • 你的提交更重要（独自工作时很常见）：git pull --rebase origin branch - 将你的本地提交重新应用到远程提交之上。
   • 远程提交更重要（有人强制推送，或你想丢弃本地更改）：git reset --hard origin/branch - 有破坏性，请先确认。
   • 双方都有实际工作（协作导致的分歧）：git pull --rebase origin branch，逐步解决冲突，然后执行 git rebase --continue。
   • 尚不确定：在选择策略前检查两边的历史记录和仓库策略；不要通过运行依赖配置的 pull 来试探。
3. 解决后：通过 git log --oneline -10 确认历史记录正确。
4. 防止再次发生：如果这是共享分支上的强制推送导致的，请设置分支保护。如果是因为提交前忘记拉取导致的，请考虑设置 git config pull.rebase true，将拉取时变基设为默认行为。

---

步骤 3f：批量更新仓库工作流

当用户要求拉取或更新某个目录下的多个仓库时，应按顺序执行，确保过程可审计且谨慎。逐个仓库跟踪：

• 已记录分支、上游和脏状态
• 已获取并快进（或说明跳过的原因）
• 如有暂存，已重新应用并验证
• 已检查领先/落后状态和 porcelain 状态

1. 首先只查找真正的仓库根目录，通常是指定目录的直接子目录，除非用户明确要求递归扫描。避开供应商代码仓库、工作树、依赖缓存和生成的检出副本。
2. 按顺序处理仓库，不要并行处理。这样可以避免对 SSH 远程服务造成过多请求、触发速率限制或防火墙防护。
3. 对每个仓库，在进行任何更改之前记录分支、上游和脏状态。
4. 运行 git fetch --all --prune，仅当存在上游时再运行 git pull --ff-only --recurse-submodules。批量维护期间不要创建合并提交。存在子模块时，拉取后还要运行 git submodule update --init --recursive——--recurse-submodules 会更新现有子模块检出副本，但不会初始化自上次拉取后新增的子模块。
5. 若获准暂存本地更改，请记录原始暂存区和工作树差异，创建一个命名暂存项，然后快进，接着使用该暂存项的确切对象 ID 执行 git stash apply --index。在验证内容以及暂存/未暂存的划分之前，请保留该暂存项。
6. 如果应用索引时发生冲突，请保留暂存项，并停止更新该仓库。谨慎地根据已保存的暂存区和未暂存差异进行解决；切勿一概取消暂存用户的工作。报告存在未解决问题的仓库，并继续处理其他互不相关的仓库。
7. 使用 git rev-list --left-right --count HEAD...@{u} 和 git status --porcelain 验证每个仓库。报告仍处于脏状态或没有上游的仓库。

---

多 Forge 模式

许多项目会使用多个 git 远程端（例如，用于自托管 CI 的 Forgejo + 用于公开发布的 GitHub，或用于工作的 GitLab + 用于开源镜像的 GitHub）。

• 将 origin 保留为主要开发远程端，并为镜像使用明确的名称。
• 明确推送到多个远程端；不要默认“推送到所有远程端”。
• 每个 Forge 使用单独的 SSH 密钥。
• 请记住，环境变量可能会覆盖 CLI 身份验证，尤其是 GITHUB_TOKEN。

详细的多 Forge 工作流见 references/forge-workflows.md。

---

提交签名

• 为提交签名，因为伪造未签名的提交作者身份很容易。
• 对大多数团队来说，默认建议使用 SSH 签名。
• 对于需要长期密钥生命周期或有策略要求的场景，GPG 仍然重要。
• gitsign 对低管理成本的开源工作流很有吸引力，但它会改变信任模型。

详细的签名设置见 references/security-and-signing.md。

---

安全

• 不要将凭据放入仓库，包括 .env 文件、密钥和嵌入式连接字符串。
• 使用安全的凭据助手，而不是明文存储。
• 使用钩子处理机密信息、代码检查和分支保护，但要将不可信的钩子配置视为代码执行入口。
• 如果机密信息出现在历史记录中，请清除它并轮换密钥。重写历史记录无法撤销泄露。
• 有意识地维护 .gitignore 和 .gitattributes；默认情况下，AI 工具生成的文件应排除在仓库之外。

详细的安全和签名指南见 references/security-and-signing.md。

---

PCI-DSS 4.0 变更证据

对于属于 PCI 范围的代码仓库，请使用受保护分支、必需的审查、关联的测试和安全检查，以及保留或导出的代码托管平台审计证据，以满足组织适用的软件变更控制要求。请与评估人员一起，将每项控制措施对应到当前的 PCI DSS 文本；仅配置 Git 并不能证明已完成培训、实现了环境隔离，或遵循了完整的变更管理流程。 签名提交可根据所选信任模型验证签名密钥的身份，但不能证明签署者完成了安全培训，也不能证明变更经过审查、测试或授权。

---

参考文件

• references/forge-workflows.md - GitHub、GitLab 和 Forgejo 中有关 PR/MR、发布、分支保护、规则集、CLI 用法和 API 调用的特定模式
• references/security-and-signing.md - 提交签名设置（SSH/GPG/gitsign）、凭证管理、机密扫描、CVE 参考、Git 安全加固
• references/recovery-and-maintenance.md - reflog、bisect、rerere、filter-repo、stash、worktree、submodule/subtree、大型代码仓库优化、日常维护

输出约定

完整约定请参阅 references/output-contract.md。

• 技能名称： GIT
• 交付物类别： audits
• 模式： 条件式。当调用以分析、审查、审计或改进现有代码仓库内容时，遵循 references/output-contract.md 中的报告篇幅和证据规则，并将交付物写入 docs/local/audits/git/<YYYY-MM-DD>-<slug>.md。当调用以回答问题、讲解概念、构建新产物或生成内容时，可自由作答，不受此约定限制。
• 严重性级别： P0 | P1 | P2 | P3 | info（参阅共享约定；仅用于审计/审查模式）。

相关技能

• ci-cd - 设计由 Git 事件（push、PR、tag）触发的流水线。本技能处理 Git 操作；ci-cd 负责处理对这些操作作出响应的流水线。
• security-audit - 扫描应用层机密并评估漏洞。本技能涵盖 Git 历史记录中的 机密以及 Git 特有的安全事项（签名、钩子、凭证）。
• code-review - 审查代码质量。本技能创建 PR/MR；code-review 评估其中的代码。
• update-docs - 会话结束后的文档检查。可根据会话中发现的新 Git 注意事项，更新共享指令文件。

规则

上文的 AI 自检列出了每项操作的防护措施（破坏性操作的确认、作者身份、选择性暂存、钩子、标签、强制推送、管理员授权）。此外还需遵循以下规则：

• 清理前列出目标集合。 删除分支、标签或被忽略文件的命令执行前，必须先列出将要删除的内容。
• 共享分支优先使用 revert，而非重写历史。 重写需要强制推送，并会影响其他所有克隆。
• 协作时使用功能分支。 需要他人审查时，请使用带 PR/MR 的功能分支。对于个人项目，如果用户明确倾向于直接操作，则可以直接提交到 main。
• 变基工作流。 将功能分支变基到基础分支上，不要将基础分支合并到功能分支。除非提交历史本身有意义，否则合并时应压缩提交，以保持历史整洁。
• 发布使用附注标签。 使用 git tag -a vX.Y.Z -m "vX.Y.Z"，而不是轻量标签。附注标签包含元数据（标记者、日期、消息），代码托管平台会用它们创建发布。
• PCI-DSS 证据。 在受监管环境中，Git 历史记录就是审计轨迹。请妥善保护：签名提交、分支保护、必需的审查，并且不得重写发布分支的历史。