w wyl123ly 的博客
MD

工具-05-GitHub与GitLab协作

54 KB 2026.10.11 原文件

工具-05-GitHub与GitLab协作

这篇笔记讲什么

Git 是本地的版本控制工具,而团队协作发生在托管平台上。本篇讲清托管平台在协作中的真实位置(不只是存代码),对比 GitHub / GitLab / Gitee 的定位与访问现实,给出仓库结构与分支策略的取舍,把 Pull Request(PR)/ Merge Request(MR)的完整流程、三种合并方式、Code Review 方法论、Issue 管理、开源协作礼仪,以及「误提交密钥」「强推公共分支」这两类高危事故讲透。

前置:工具-01-Git版本控制(暂存区、分支、合并与变基)。本篇不再重复 Git 命令原理。

是什么

代码托管平台(code hosting platform)是运行 Git 服务的网站,在裸仓库之上加了一整套协作层:

层次裸 Git 仓库(git init --bare)托管平台额外提供
代码存储✅✅
权限控制靠 SSH/文件权限细粒度角色(Read / Triage / Write / Maintain / Admin)
代码评审❌Pull Request / Merge Request + 行内评论
任务管理❌Issue、标签、里程碑、看板、Projects
自动化❌CI/CD 流水线、分支保护、必需检查
发布手动打 tagReleases、制品仓库、Pages
协作发现❌Fork、Star、搜索、讨论区、安全公告

一句话:平台把「一群人改同一份代码」从技术问题变成了流程问题。

为什么需要它

如果只有 Git 而没有平台,团队协作会退回成三种原始形态,各自都有致命问题:

原始形态具体做法问题
直接推主干所有人 git push 到 main无评审、无 CI,任何人一个笔误污染所有人
邮件发补丁git format-patch + 邮件列表门槛高,讨论与代码分离(Linux 内核至今如此,但普通人学不动)
共享目录捞代码各自提交到自己的分支再口头通知谁改了什么无人知晓,无法追溯

平台解决的核心问题是把「代码变更」变成一个有状态、可讨论、可自动校验的对象——也就是 PR/MR。它的价值在于:

  1. 变更可被拒绝:合并前就拦住错误,而不是上线后回滚;
  2. 讨论与代码绑定:三个月后还能查到「这行为什么这么写」;
  3. 责任可追溯:谁批准、谁合并、什么时候,全有记录;
  4. 自动化有挂载点:CI 在 PR 上跑,绿了才允许合并(见 工具-08-CICD入门)。

一句话记住

PR/MR 是团队协作的基本单元,不是「把代码推上去」的附属步骤。学会用 GitHub/GitLab 的本质是学会如何让一次变更被安全地接受。

核心内容

平台对比

维度GitHubGitLabGitee(码云)
定位全球最大开源社区 + 商业托管一体化 DevOps 平台,可自托管国内托管平台
中文界面有(docs.github.com/zh,站点可切换语言)部分中文文档原生中文
私有仓库免费账号可建无限私有仓库免费账号可建,自托管社区版功能完整免费账号私有仓库数量有限制
CI 能力GitHub Actions(.github/workflows/)GitLab CI/CD(.gitlab-ci.yml,能力更强,含环境、审批、Review App)Gitee Go(能力相对基础)
自托管GitHub Enterprise Server(商业授权)GitLab Self-Managed(社区版免费)企业版/私有部署
生态Actions 市场、Codespaces、Packages内置 Container Registry、Pages、安全扫描、Issue 看板国内生态、与国内云服务集成
中国大陆访问可能不稳定(时快时慢、偶发超时甚至不可达)国际站(gitlab.com)同样可能不稳定;自托管不受影响国内访问快且稳定
典型用法开源项目、国际协作企业内部一体化研发平台国内团队、教学、个人项目

如实说明:国内访问 GitHub 的现实

在中国大陆访问 github.com 可能出现:网页加载慢、git clone 卡在 Receiving objects、CI Runner 拉取超时、图片(头像/徽章)加载失败。这些是网络链路问题,不是账号或仓库问题。

实务上的应对(按推荐度排序):

1. 代码走 SSH 而非 HTTPS,并配置 ~/.ssh/config 使用 443 端口的 ssh.github.com;

2. 配置 Git 代理(仅在你自己的合规网络环境下);

3. 用镜像或自建 GitLab(Gitee 导入、GitLab 自托管)在国内做日常开发,GitHub 只作为上游同步点;

4. CI 上优先用 actions/checkout 等官方 Action(走 CDN),减少对源码站点的直接依赖。

教学与团队内训场景,建议先确认网络可达性再选平台,否则「环境问题」会吃掉大半学习时间。

仓库结构规范

一个「看起来专业、新人能上手」的仓库,文件布局大致如下:

my-project/
├── README.md                  # 门面:是什么、怎么跑起来
├── LICENSE                    # 授权条款(不写 = 默认保留所有权利)
├── .gitignore                 # 忽略构建产物、依赖、密钥
├── .editorconfig              # 跨编辑器基础风格(见 [[工具-06-编辑器与IDE]])
├── CONTRIBUTING.md            # 怎么贡献:分支命名、提交规范、跑测试
├── CODE_OF_CONDUCT.md         # 行为准则(开源项目建议有)
├── CHANGELOG.md               # 版本变更记录
├── .github/
│   ├── PULL_REQUEST_TEMPLATE.md          # PR 模板
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug_report.yml                # Bug 报告表单
│   │   ├── feature_request.yml           # 功能请求表单
│   │   └── config.yml                    # 模板选择器配置
│   ├── CODEOWNERS                        # 谁负责哪些路径的评审
│   └── workflows/ci.yml                  # GitHub Actions 流水线
├── docs/                      # 详细文档
├── src/                       # 源码
└── tests/                     # 测试
README 该写什么

README 是唯一「所有人都会看」的文件。推荐的六段结构:

# 项目名

一句话说明:这是一个用 XX 技术做的 YY,解决 ZZ 问题。

![截图或演示 GIF](docs/screenshot.png)

## 快速开始

git clone <repo-url>

cd my-project

npm install

npm run dev # 打开 http://localhost:5173


## 技术栈

- 前端:Vue 3 + TypeScript + Vite
- 后端:FastAPI + PostgreSQL
- 部署:Docker Compose

## 贡献方式

欢迎提交 Issue 与 PR,请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。

## License

MIT © 2026 Your Name

要点:

  • 一句话说明放最前面:读者 5 秒内决定要不要继续看;
  • 截图/动图不可省:对前端与 GUI 项目,一张图胜过三段文字;
  • 快速开始必须能直接复制粘贴成功:写完自己在一台干净机器上验证一遍;
  • 技术栈写清版本:避免「我装的是 Java 8 为什么跑不起来」;
  • 贡献方式给出明确入口:指向 CONTRIBUTING.md 与 Issue 模板。
LICENSE 选择

GitHub 官方文档说明:仓库没有 LICENSE 文件时,默认版权归作者所有,他人没有复制、分发、修改的权利(即使代码公开可见)。

许可证类型他人可商用衍生作品必须开源适用场景
MIT宽松✅❌最常用,最大化传播
Apache-2.0宽松✅❌(但有专利授权与变更声明要求)企业友好,含专利条款
BSD-3-Clause宽松✅❌与 MIT 类似
MPL-2.0弱著佐权✅仅修改的文件需开源库,允许与闭源共存
LGPL-3.0弱著佐权✅库本身修改需开源动态链接库
GPL-3.0强著佐权✅✅(整个衍生作品)追求软件自由
AGPL-3.0强著佐权✅✅(含网络服务)防止「SaaS 白嫖」
Unlicense / CC0放弃权利✅❌公共领域

怎么选(务实版)

- 个人练手、教程代码、想让别人随便用 → MIT;

- 公司开源、担心专利 → Apache-2.0;

- 不想让云厂商闭源拿去卖 → AGPL-3.0;

- 学习笔记、文档、非代码内容 → CC BY 4.0 / CC BY-SA 4.0(知识共享协议,不是软件许可证)。

.gitignore
# ── 依赖 ──────────────────────────────
node_modules/
.venv/
venv/
__pycache__/
*.py[cod]
bin/
obj/

# ── 构建产物 ──────────────────────────
dist/
build/
*.dll
*.exe
.next/
coverage/

# ── 编辑器与系统 ──────────────────────
.vscode/*
!.vscode/settings.json      # 团队共享的配置要保留
!.vscode/extensions.json
.idea/
.DS_Store
Thumbs.db

# ── 密钥与本地配置(最重要!)─────────
.env
.env.local
.env.*.local
*.pem
*.key
secrets.json
appsettings.Development.json

# ── 日志与运行数据 ────────────────────
*.log
logs/
*.sqlite3

.gitignore 不是安全机制

已经被 git add 过的文件,之后再加进 .gitignore 不会让它从历史中消失。密钥一旦提交过,就等于已经泄露——处理方式见下文「常见事故与规避」。

CONTRIBUTING.md

告诉贡献者「怎么参与」,内容清单:

# 贡献指南

## 开发环境
1. 克隆仓库并安装依赖:`npm install`
2. 复制 `.env.example` 为 `.env` 并填入本地配置
3. 启动开发服务:`npm run dev`

## 提交前检查
- `npm run lint` 必须通过
- `npm run test` 必须全绿
- 提交信息遵循 Conventional Commits(`feat:`、`fix:`、`docs:`、`chore:`)

## 分支命名
- 功能:`feature/短描述`
- 修复:`fix/issue编号-短描述`
- 文档:`docs/短描述`

## Pull Request 要求
- 关联对应 Issue(`Closes #编号`)
- 单个 PR 控制在 400 行有效改动以内
- 附上验证方式与截图(UI 变更)
Issue 模板与 PR 模板的作用
模板位置作用
Issue 模板.github/ISSUE_TEMPLATE/*.yml用表单强制收集关键信息(版本、复现步骤、日志),减少来回追问
Issue 模板配置.github/ISSUE_TEMPLATE/config.yml关闭空白 Issue、把「使用问题」引导到讨论区
PR 模板.github/PULL_REQUEST_TEMPLATE.md提醒作者填写「改了什么/为什么/怎么验证」,也用来自查

GitHub 的议题表单(issue forms)用 YAML 定义,支持文本、下拉、复选框、文件上传等字段类型:

# .github/ISSUE_TEMPLATE/bug_report.yml
name: Bug 报告
description: 报告一个可复现的缺陷
title: "[Bug] "
labels: ["bug", "triage"]
body:
  - type: markdown
    attributes:
      value: |
        感谢反馈!请务必填写复现步骤与环境信息。
  - type: textarea
    id: steps
    attributes:
      label: 复现步骤
      description: 请写出最小可复现步骤
      placeholder: |
        1. 打开首页
        2. 点击「登录」
        3. 输入错误的密码并提交
    validations:
      required: true

  - type: textarea
    id: expected
    attributes:
      label: 期望行为
    validations:
      required: true

  - type: input
    id: version
    attributes:
      label: 版本号
      placeholder: v1.2.3
    validations:
      required: true

  - type: dropdown
    id: os
    attributes:
      label: 操作系统
      options:
        - Windows 11
        - macOS
        - Ubuntu 22.04
        - 其他
    validations:
      required: true

  - type: textarea
    id: logs
    attributes:
      label: 相关日志
      render: shell      # 自动按 shell 语法高亮,作者不用加反引号
# .github/ISSUE_TEMPLATE/config.yml
blank_issues_enabled: false     # 关闭空白 Issue,强制走模板
contact_links:
  - name: 使用问题请到 Discussions
    url: https://docs.github.com/zh/discussions
    about: 提问、交流用法请走讨论区,Issue 只用于缺陷与需求

PR 模板(.github/PULL_REQUEST_TEMPLATE.md):

## 改了什么

<!-- 一两句话说清变更内容 -->

## 为什么

<!-- 关联 Issue,说明动机 -->
Closes #

## 怎么验证

- [ ] 本地跑通 `npm run test`
- [ ] 手动验证步骤:1) … 2) …

## 截图(UI 变更必填)

<!-- 改动前 / 改动后 -->

## 自查清单

- [ ] 已自查 diff,无调试代码、无无关格式化
- [ ] 已补充/更新测试
- [ ] 已更新相关文档

分支策略对比

策略结构适用团队规模发布节奏复杂度
Trunk-based(主干开发)只有 main + 生命周期 < 1 天的短分支任意,尤其适合强 CI 团队持续部署,随时可发低
GitHub Flowmain + 功能分支 + PR1~20 人,Web 服务合并即部署很低
GitLab Flowmain + 环境分支(staging、production)或发布分支10~100 人,需要环境隔离按环境推进中
Git Flowmain + develop + feature/ + release/ + hotfix/*50 人以上,版本化交付按版本发布(月/季度)高

GitHub Flow 的完整循环(官方文档描述):

1. 从 main 创建分支        git switch -c feature/login
2. 提交并推送              git push -u origin feature/login
3. 打开 Pull Request       (可先开 Draft PR)
4. 讨论与评审              行内评论、CI 检查
5. 合并到 main             Squash / Merge commit / Rebase
6. 删除分支                本地与远程都删

为什么小团队不该照搬 Git Flow:

  1. develop 分支是纯粹的成本:它引入了「两份主干」,任何合并冲突都要在 develop 和 main 之间同步两次;
  2. 长生命周期分支 = 冲突制造机:release/* 存在两周,期间主干继续前进,最后合并时冲突量陡增;
  3. 它解决的是「盒装软件多版本并行维护」的问题:需要同时维护 v1.2、v1.3、v2.0 三条线时才划算;
  4. 持续部署下没有「发布分支」的概念:Web 服务合并即上线,release/* 无事可做;
  5. 认知负担:新人要记五种分支的命名与流向,而收益在小团队几乎为零。

选择建议

- 个人项目 / 学习仓库:GitHub Flow(main + 功能分支 + PR)足矣;

- 小团队 Web 服务:GitHub Flow 或 trunk-based,配合必需 CI 检查与自动部署;

- 需要 staging 环境验收:GitLab Flow(main → staging → production);

- 有多个对外版本要维护(如 SDK、客户端):才考虑 Git Flow。

Pull Request / Merge Request 工作流

完整流程
# ── 1. 同步主干并创建分支 ────────────────────────────
git switch main
git pull --ff-only origin main
git switch -c feature/add-coupon

# ── 2. 小步提交 ─────────────────────────────────────
git add src/coupon.ts tests/coupon.test.ts
git commit -m "feat(coupon): 支持满减券叠加"

# ── 3. 推送并建立上游跟踪 ───────────────────────────
git push -u origin feature/add-coupon

# ── 4. 用 CLI 创建 PR(GitHub CLI)──────────────────
gh pr create \
  --title "feat(coupon): 支持满减券叠加" \
  --body "Closes #42" \
  --reviewer alice,bob \
  --label "enhancement"

# 想先建草稿(Draft PR):
gh pr create --draft --title "WIP: 优惠券叠加"

# ── 5. 评审期间保持同步(把 main 的更新合进来)──────
git switch main && git pull
git switch feature/add-coupon
git merge main          # 或 git rebase main(见下文合并方式对比)
git push

# ── 6. 合并后清理 ───────────────────────────────────
gh pr merge --squash --delete-branch
git switch main && git pull
git branch -d feature/add-coupon   # 若本地还留着
PR 描述该写什么

评审者拿到 PR 时,最先看到的是标题与描述。四要素缺一不可:

要素回答的问题反例正例
改了什么具体变更「优化代码」「优惠券计算支持多种券叠加,新增 CouponStack 类」
为什么动机与背景(无)「Closes #42:用户反馈一单只能用一张券」
怎么验证评审者如何确认「测试过了」「npm run test:coupon 全绿;手动:下单时选两张券,应看到 8 折」
截图/录屏UI 变更的效果(无)改动前后对比图
Draft PR 的用途

Draft PR(草稿拉取请求)是「已推送、想让人看见、但还没准备好被正式评审」的状态:

  • 提前拿到方向反馈:架构方向错了,早说比晚说便宜;
  • 让 CI 先跑起来:长测试可以在草稿阶段就开始跑;
  • 团队可见性:别人知道你正在做这块,避免重复劳动;
  • 不适合合并:Draft 状态无法合并(分支保护可要求必须先标记为 ready);
  • 转为可评审:GitHub 上点「Ready for review」,GitLab 上把标题前缀 Draft: 去掉。
gh pr ready            # 把草稿标记为可评审
gh pr ready --undo     # 再转回草稿
关联 Issue 的语法

在 PR 描述或提交信息里写关键词 + Issue 编号,合并后自动关闭该 Issue:

语法效果
Closes #12合并时关闭 #12
Fixes #12同上
Resolves #12同上
Closes #12, closes #13一次关多个
Refs #12 / Related to #12只引用不关闭(推荐用于「部分实现」)
Closes owner/repo#12关闭其他仓库的 Issue

别在无关 PR 里写 Closes

一个 PR 关闭十个 Issue,看起来效率很高,实际上破坏了追溯性:出了问题无法判断是哪个变更引入的。一个 PR 对应一个逻辑变更、通常对应一个 Issue。

Review 的三种结果与处理

GitHub 的评审结论有三种:

结果含义作者应做什么
Comment(评论)只留意见,不表态逐条回应;若对方未明确要求改动,判断是否需要改
Approve(批准)认可,可以合并等必需的批准数达标 + CI 绿 → 合并
Request changes(请求修改)有问题,阻塞合并必须处理;处理完请求重新评审(re-request review)

处理流程建议:

  1. 收到 Request changes:先逐条回复(「已改」「同意,已改」「我想讨论一下:…」),不要批量「改了」了事;
  2. 改动后推送到同一分支,PR 会自动更新;不要关掉 PR 重开(会丢失讨论历史);
  3. 用 gh pr review --approve 或网页上的按钮请求复审;
  4. 如果某条意见你不打算改,必须说明理由并达成一致,不要默默忽略后合并。
三种合并方式对比

GitHub 官方文档对三种策略的定位:

方式结果历史何时选择注意
Create a merge commit(合并提交)保留 PR 分支的每一个提交,额外加一个合并点团队重视完整历史,或分支上每个提交本身有意义(如含独立重构)历史呈网状,git log 较吵;本地等价于 git merge --no-ff
Squash and merge(压缩合并)把 PR 的所有提交压成主干上的一个提交PR 代表一个逻辑变更,尤其含大量「修改」「再修一下」的小提交中间提交不保留;不适合长生命周期分支(后续 PR 会包含已压缩的提交,冲突概率上升)
Rebase and merge(变基合并)把 PR 的提交逐个重放到主干,不产生合并提交,历史线性团队要线性历史,且分支上的提交已整理干净(已 squash 过自己的 WIP)会重写提交 SHA;GitHub 上会删掉「空提交」(--allow-empty 创建的那种),与本地 git rebase 略有差异

选择原则(实用版):

问三个问题:
1. 你们需要「按 PR 粒度回滚」吗?         → 是:Squash(一个 PR = 一个可回滚提交)
2. 你们需要 bisect 精确定位到小提交吗?   → 是:Rebase 或 Merge commit
3. 分支上是否有「必须保留」的独立提交?   → 是:Merge commit

90% 的团队最优解:Squash and merge
  - 主干历史一条线:feat: xxx / fix: yyy / docs: zzz
  - 每个提交都可独立回滚
  - 作者在分支上可以随便提交「wip」「fix typo」
合并后删分支
# 网页上合并时勾选「Delete branch」(推荐,最省心)
# CLI :
gh pr merge --squash --delete-branch

# 本地清理已合并的本地分支
git branch -d feature/add-coupon

# 顺手清理「远程已删但本地仍跟踪」的分支引用
git fetch --prune

为什么必须删

分支列表是团队的「当前工作视图」。留着几十个已合并分支,git branch -a 就没法用了,也没人敢批量清理——因为无法一眼看出哪些还有用。

Code Review 方法论

评审者该关注什么

按重要性排序:

优先级关注点具体检查
1正确性逻辑是否满足需求?有没有反了的条件(> vs >=)?
2边界与异常空值、空集合、0、负数、超大值、并发、超时、失败分支
3安全性输入校验、SQL 拼接、越权(水平/垂直)、密钥硬编码、日志泄露敏感数据
4测试覆盖新增逻辑有没有对应测试?测试断言是否足够强?
5可读性命名是否表意?函数是否过长?嵌套是否过深?有没有「聪明但难懂」的技巧
6架构一致性是否复用了已有抽象?有没有引入重复逻辑(DRY)?层次是否被穿透
7性能循环内查询(N+1)、无界集合驻留内存、无索引的查询
8可维护性是否有必要的注释解释「为什么」?错误信息是否可诊断
不该纠结什么

个人风格偏好一律交给自动化工具,人力只用在工具看不到的地方:

不要评论交给谁
缩进、分号、引号、行宽Prettier(见 [[工具-03-包管理器]]、[[前端-09-前端工程化与调试]])
命名 casing、未使用变量、简单的可疑写法ESLint / Ruff / 编译器警告
import 排序ESLint import/order 等规则
文件末尾换行、行尾符.editorconfig
「我喜欢用 A 而不是 B」(无客观差异)不评论

一条硬标准

如果一条评论可以被工具自动检查,就不该由人提。人提这类意见的边际价值接近零,且会让作者觉得被挑刺。

如何给建设性评论

三条原则:

  1. 对事不对人:说「这个函数在并发下会读到脏数据」,不说「你没考虑并发」;
  2. 区分「必须改」与「建议」:用前缀标记(团队约定俗成即可):
[blocking] 这里会 SQL 注入,必须用参数化查询。
[suggestion] 可以考虑把这个判断抽成函数,非必须。
[nit] 变量名 typo:recieve → receive。(不阻塞)
[question] 这里为什么用 Redis 而不是本地缓存?想了解背景。
[praise] 这个边界处理很细,学到了。
  1. 用提问代替命令:「这里如果 items 为空会怎样?」 比 「你没处理空数组」 更容易被接受,也给对方解释的余地(也许上游已保证非空)。

评论要给出可执行的改法或明确的判断依据:

❌ 这个写法不好。
✅ 这里每次循环都查一次数据库,100 个商品就是 100 次查询(N+1)。
   建议先批量查出来再在内存里 map,参考 UserService.listWithRoles 的写法。
作者如何回应
做法说明
不辩护被指出问题时,第一反应是「确实」,而不是「因为当时…」。理由可以补充,但先承认问题
逐条回应每条评论都回复:已改(commit abc1234) / 同意,但我建议单独开 PR / 我理解你的顾虑,但这里是刻意的,因为…
有分歧就拉同步沟通评论区来回超过 3 轮仍未达成一致 → 拉个 15 分钟语音。文字沟通在多轮后成本指数上升
不要默默改掉再合并评论线程不回复会让评审者不知道你是否看到了
推动 PR 前进主动 @ 评审者、设置截止时间。PR 挂着不开工是团队吞吐量的最大杀手
接受「不完美的合并」如果意见属于「可以更好但不必现在做」,主动建一个 follow-up Issue,而不是让 PR 无限期挂着
小 PR 原则

GitHub 官方文档明确建议写小而聚焦的 PR:更容易审查、更安全地合并,也更容易让评审者理解意图、更快发现问题。

为什么 200~400 行是评审质量的分水岭:

  • 评审是注意力有限的活动。研究表明评审者在单次评审超过约 400 行后,缺陷发现率显著下降;
  • 大 PR 里,重要改动会被无关的格式化、重命名淹没;
  • 大 PR 的评论区会变成「多线程聊天」,作者容易漏掉意见;
  • 大 PR 一旦方向错了,回退成本极高。

拆分方法:

拆法做法示例
按层次一个 PR 只动一层:数据库 → 服务 → API → 前端PR1: 加表与迁移;PR2: 服务层逻辑;PR3: 暴露 API;PR4: 前端接入
按功能一个 PR 只交付一个可独立描述的能力「支持优惠券」拆成「创建券」「应用券」「券列表页」
先重构后加功能第一个 PR 只做无行为变化的重构(测试全绿即安全),第二个 PR 加功能PR1: 抽 PriceCalculator;PR2: 在它里面加折扣逻辑
按机械改动分离格式化、重命名、依赖升级单独成 PRPR: chore: prettier 全仓库格式化

拆分不等于碎片化

每个拆出来的 PR 应能独立通过 CI 与评审,并且合并后系统仍是可工作的(可用 feature flag 隐藏未完成功能)。

自动化介入

分支保护规则

在 GitHub 上,受保护分支(protected branch)可以强制以下规则:

规则作用
Require a pull request before merging禁止直接推送,必须走 PR
Require approvals(N 人)至少 N 个批准才能合并
Dismiss stale approvals有新推送时,旧批准自动失效(很关键,防止「批准后再偷改」)
Require review from Code Owners改到某目录必须由该目录负责人批准
Require status checks to passCI 必须绿(可指定具体检查项)
Require branches to be up to date合并前必须先同步主干(避免「绿的是旧基线的组合」)
Require conversation resolution所有评论线程必须标记已解决
Require linear history禁止合并提交(强制 squash 或 rebase)
Require signed commits提交必须签名
Restrict who can push只有指定人或团队能推
Do not allow bypassing连管理员也不能绕过(强烈建议开启)
CODEOWNERS

CODEOWNERS 文件声明「哪些路径由谁负责」,配合「Require review from Code Owners」实现自动指派评审人:

# .github/CODEOWNERS
# 语法:路径模式  负责人(用户或 @组织/团队)

# 默认:所有文件由核心团队负责
*                       @myorg/core

# 前端
/frontend/              @myorg/frontend-team
*.vue                   @myorg/frontend-team
*.tsx                   @myorg/frontend-team

# 后端与基础设施
/backend/               @myorg/backend-team
/infra/                 @myorg/devops
Dockerfile              @myorg/devops
*.tf                    @myorg/devops

# 安全敏感路径:必须由安全组评审
/auth/                  @myorg/security
/src/crypto/            @myorg/security
*.pem                   @myorg/security

# 文档
/docs/                  @alice @bob

规则要点:

  • 路径模式支持 *、**、? 等通配;
  • 最后匹配的规则生效(与 .gitignore 相反),所以默认规则 * 要写在最前面;
  • 团队用 @org/team-name,个人用 @username;
  • 文件可放在 .github/、仓库根目录或 docs/ 下。
让自动化成为「守门人」而不是「保姆」
# .github/workflows/ci.yml —— PR 上的必跑检查(示意)
name: CI
on:
  pull_request:
    branches: [main]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run lint          # 风格问题由工具拦,不进 Code Review
      - run: npm run typecheck
      - run: npm run test:unit -- --coverage
      - run: npm run build

深入 CI 配置

流水线语法、矩阵构建、缓存、制品与部署策略见 工具-08-CICD入门。此处只强调一点:凡是能自动检查的,都不要靠人。

Issue 管理

Issue 与 PR 的分工
IssuePull Request
表达「有什么问题 / 想要什么」「我这样改了」
状态Open → ClosedOpen → Draft → Merged / Closed
内容描述、复现、讨论、方案权衡diff、CI 结果、行内评审
关闭方式手动,或被 PR 的关键词自动关闭合并即关闭(未合并关闭需说明原因)
数量关系一个 Issue 可由多个 PR 完成一个 PR 通常对应一个 Issue

常见反模式

- 用 Issue 当聊天室:一个问题拆成几十条评论讨论方案,没有结论。应把结论沉淀回 Issue 描述或转成设计文档。

- PR 里夹带未讨论的大改动:「顺便重构了整个模块」——评审者无法有效评估,正确做法是拆 PR 或先开 Issue 讨论。

- Issue 长期无人处理也不关闭:定期 triage(分类)是维护者的核心工作。

标签体系

用三个维度组织标签,避免「标签爆炸」(几十个含义重叠的标签等于没有标签):

维度标签说明
type(类型)type/bug、type/feature、type/docs、type/refactor、type/chore这是什么性质的变更
priority(优先级)priority/p0(立刻)、p1(本迭代)、p2(计划内)、p3(有空再说)多紧急
status(状态)status/triage、status/confirmed、status/in-progress、status/blocked、status/needs-info现在处于什么环节
辅助good first issue、help wanted、duplicate、wontfix、question面向社区协作

good first issue 的价值

给新贡献者准备一批「范围明确、有指引、不需要深入架构」的任务,是开源项目最有效的留存手段。第一次贡献成功的人,第二次贡献的概率高得多。

里程碑与看板
  • 里程碑(Milestone):把一组 Issue 绑定到一个目标(如 v2.0 或「十月迭代」),可查看完成百分比与剩余时间;
  • 看板(Project / Board):把 Issue 按状态列(Todo / In Progress / Review / Done)展示,用于每日站会同步;
  • 使用纪律:看板列必须少(3~5 列),WIP(进行中)设上限,否则看板会退化成「一堆卡片」;
  • GitHub Projects 支持自定义字段与自动化规则(如「PR 关联后自动移到 Review」),GitLab 侧对应 Issue Board 与 Epic。
可复现 Bug 报告模板

一个高质量的 Bug 报告必须让维护者不追问就能复现:

## 环境
- 版本:v1.4.2(`git rev-parse HEAD` 输出:a1b2c3d)
- 操作系统:Windows 11 23H2
- 浏览器/运行时:Chrome 130 / Node 22.11.0
- 数据库:PostgreSQL 16.1

## 复现步骤
1. 以普通用户登录
2. 打开「我的订单」页
3. 点击第二页
4. 观察结果

## 期望行为
显示第 11~20 条订单。

## 实际行为
显示第 1~10 条订单(页码高亮在「2」)。

## 复现频率
100%(5 次尝试 5 次复现)

## 最小复现
(可选但极有价值)一个最小仓库或 CodePen 链接:
https://example.com/minimal-repro

## 日志 / 报错

TypeError: Cannot read properties of undefined (reading 'slice')

at OrdersList.vue:42


## 补充信息
- 第 1 页正常,第 3 页及以后也正常,只有第 2 页异常
- 已尝试清除缓存,无效

开源协作礼仪

场景该做不该做
提问前先搜 Issue、Discussions、文档;(很多问题已被回答过十次)直接开新 Issue 问「怎么用」
提 Bug给最小可复现示例(Minimal Reproducible Example),附版本与日志只写「不工作了」「有 bug」;贴几百行无关代码
提问措辞描述事实与已尝试的方案;给出自己排查的结论「你们这个项目怎么这么烂」;命令式要求
等待回复维护者多为无偿业余时间工作,等 3~7 天正常24 小时内 @ 三次、连发催促、私信轰炸
提第一个 PR从修文档、改 typo、补测试、处理 good first issue 开始一上来提「重写核心架构」这种巨型 PR
被拒绝询问理由、接受 wontfix;可用于自己的 fork反复争辩、发长文控诉、开小号重提
被合并说句谢谢;按项目规范更新文档提交后消失,不响应后续评审意见

一条底层原则

开源协作是陌生人之间的自愿合作。你的 Issue/PR 是「请求」而非「要求」;你的目标是降低对方处理你的问题的成本——最小复现示例、清晰的标题、完整的模板,都是在替对方省时间。

常见事故与规避

事故一:误提交密钥

错误处理(很多人的第一反应):

# ❌ 只删文件 + 提交 —— 密钥仍在历史里,任何人 clone 都能翻出来
git rm .env
git commit -m "remove env file"
git push

正确认知:只要密钥进过远程仓库,就视为已泄露。原因:

  • 历史提交永久保留(除非重写历史);
  • 可能已被 fork、已被 CI 日志记录、已被镜像站抓取、已被爬虫扫描(GitHub 上的公开仓库密钥常在数分钟内被自动扫描并尝试利用);
  • 删除提交无法撤回已经发生的泄露。

正确处置顺序(顺序不可颠倒):

1. 【立刻轮换/吊销密钥】  ← 最重要,永远先做这一步
   - 云厂商控制台:禁用/删除该 AccessKey,生成新密钥
   - 数据库:改密码并踢掉现有连接
   - 第三方 API:在服务商后台 revoke 旧 Token
   - 证书/私钥:重新签发,旧的加入吊销列表(CRL)

2. 【评估影响面】查看访问日志:有没有被使用过?动了哪些资源?

3. 【清理仓库】
   - 未推送过:git reset / git commit --amend 即可
   - 已推送但只有你自己在开发:用 git filter-repo 重写历史后强推
   - 已推送且有多人协作:通知所有人,约定时间统一处理(否则历史会互相"复活")
   - 联系平台支持:GitHub 支持请求清除缓存的提交

4. 【建立防线】
   - CI 加密钥扫描(GitHub 的 secret scanning、gitleaks、trufflehog)
   - .env.example 代替 .env 提供模板
   - 用平台 Secrets / Vault 管理生产密钥(见 [[后端-08-部署与运维基础]])
   - 开启推送保护(push protection)阻止含密钥的推送

顺序错了等于没做

「先删提交再换密钥」是最危险的错误顺序:你以为处理完了,实际泄露仍在持续,而你不再警惕。

事故二:强推公共分支

git push --force 会把远程分支重写为本地状态,丢弃远程上已有的提交。如果别人已经基于那些提交工作了:

  • 他们的本地分支与远程分叉,下次 git pull 会得到一团混乱;
  • 他们推上来的提交凭空消失(在 reflog 过期后);
  • 更糟的是:别人一 push,你删掉的提交又回来了(因为他们本地还有),历史来回摆荡。
--force 与 --force-with-lease 的区别
命令行为安全性
git push --force / -f无条件用本地覆盖远程❌ 会覆盖任何远程更新,包括你尚未拉取的他人提交
git push --force-with-lease仅当远程分支仍等于你上次拉取时的状态才允许覆盖✅ 若期间有人推送过,直接拒绝,保护他人的提交
git push --force-if-includes在 --force-with-lease 基础上再确认「要覆盖的提交确实是我本地已包含的」✅✅ 最严格
# 场景:你 rebase 了自己的功能分支,需要更新远程
git switch feature/my-work
git fetch origin
git rebase origin/main

# ❌ 危险
git push --force

# ✅ 安全(别人若在此期间推过东西,会被拒绝,你就知道要先 fetch)
git push --force-with-lease

# 更严格
git push --force-with-lease --force-if-includes

规则:

  • **绝不对 main / master / develop / release/* 强推**。这些分支应开启分支保护(禁止强推与删除);
  • 只对自己独占的功能分支强推;
  • 即使在功能分支上,也用 --force-with-lease 而不用 --force;
  • 团队约定:推送前先 git fetch,否则 lease 的保护对象是你过期的认知。

配置成默认行为

```bash

git config --global alias.pushf "push --force-with-lease"

# 或直接改默认:让 --force 也带上 lease 语义

git config --global push.useForceIfIncludes true

```

相关 Git 原理(reflog、rebase、revert 与 reset 的区别)见 工具-01-Git版本控制。

怎么用

完整配置文件

CONTRIBUTING.md(可直接改用)

# 贡献指南

感谢你有兴趣为本项目做贡献!

## 报告问题

请使用 [Issue 模板](../../issues/new/choose)。**不要**在 Issue 中粘贴密钥、token 或真实用户数据。

## 开发环境搭建

git clone <repo-url> && cd <repo>

npm install

cp .env.example .env

npm run dev


## 分支与提交规范

- 从 `main` 切出分支:`feature/<简述>`、`fix/<issue号>-<简述>`、`docs/<简述>`
- 提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/):
  `feat:` `fix:` `docs:` `refactor:` `test:` `chore:`

## 提交 PR 前

npm run lint && npm run typecheck && npm run test


- PR 请关联 Issue:在描述中写 `Closes #<编号>`
- 一个 PR 只做一件事,有效改动建议不超过 400 行
- UI 变更请附截图

## 行为准则

参与本项目即表示同意遵守 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。

.github/PULL_REQUEST_TEMPLATE.md

## 改了什么

<!-- 一句话概括 -->

## 为什么

Closes #

## 怎么验证

- [ ] `npm run test` 全绿
- [ ] 手动验证:
  1.
  2.

## 截图 / 录屏(UI 变更必填)

改动前改动后
## 自查 - [ ] 看过自己的完整 diff,无调试残留、无无关格式化 - [ ] 新增逻辑有对应测试(边界与异常已覆盖) - [ ] 已更新相关文档 / CHANGELOG - [ ] 无密钥、token、真实用户数据被提交

.github/CODEOWNERS

# 默认负责人(必须放最前,最后匹配的规则生效)
*                       @myorg/maintainers

/src/api/               @myorg/backend
/src/web/               @myorg/frontend
/src/auth/              @myorg/security
/infra/                 @myorg/devops
/docs/                  @alice
*.md                    @alice
.github/workflows/      @myorg/devops

.gitignore(Python + Node 混合项目)

# Python
__pycache__/
*.py[cod]
.venv/
venv/
.pytest_cache/
.mypy_cache/
.ruff_cache/
*.egg-info/

# Node
node_modules/
dist/
build/
coverage/
.vitest/
*.tsbuildinfo

# 环境与密钥
.env
.env.*
!.env.example
*.pem
*.key
secrets/

# 编辑器
.vscode/*
!.vscode/settings.json
!.vscode/extensions.json
.idea/

# 系统
.DS_Store
Thumbs.db

# 日志
*.log
logs/

.github/workflows/ci.yml(PR 守门)

name: CI

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

concurrency:                      # 同一 PR 的新推送取消旧运行,省额度
  group: ci-${{ github.ref }}
  cancel-in-progress: true

jobs:
  check:
    runs-on: ubuntu-latest
    permissions:
      contents: read              # 最小权限原则
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0          # 需要 diff 覆盖率时用 0
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - name: Lint(风格问题在工具层拦掉)
        run: npm run lint
      - name: Type check
        run: npm run typecheck
      - name: Unit tests + coverage
        run: npm run test:unit -- --coverage
      - name: Build
        run: npm run build

  secret-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: 扫描提交历史中的密钥
        run: |
          docker run --rm -v "$PWD:/p" zricethezav/gitleaks:latest \
            detect --source=/p --verbose --no-git=false

流水线语法细节

on / jobs / needs / 矩阵与缓存策略见 工具-08-CICD入门;此处关注的是「哪些检查必须挡在合并之前」。

可执行命令清单

# ── 认证与首次配置 ────────────────────────────────────
gh auth login                                  # GitHub CLI 登录
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main
git config --global pull.ff only                # 拉取只允许快进,避免产生意外合并提交

# SSH 走 443 端口(网络受限环境的常用解法)
cat >> ~/.ssh/config <<'EOF'
Host github.com
  HostName ssh.github.com
  Port 443
  User git
EOF
ssh -T git@github.com                           # 验证连通性

# ── 日常 PR 流程 ──────────────────────────────────────
git switch -c feature/coupon
git add -p                                      # 分块暂存,便于原子提交
git commit -m "feat(coupon): 支持满减券叠加"
git push -u origin feature/coupon
gh pr create --fill                             # 用提交信息填充标题与描述
gh pr create --draft --title "WIP: 券叠加"
gh pr list --state open --author "@me"
gh pr view --web
gh pr checks                                    # 查看 CI 状态
gh pr diff                                      # 在终端看 diff

# ── 评审 ─────────────────────────────────────────────
gh pr review 12 --approve
gh pr review 12 --request-changes --body "金额边界未处理,见评论"
gh pr review 12 --comment --body "几个建议,不阻塞合并"
gh pr ready                                     # 草稿转可评审
gh pr checkout 12                               # 把别人的 PR 拉到本地试跑

# ── 合并与清理 ───────────────────────────────────────
gh pr merge 12 --squash --delete-branch         # 最常用
gh pr merge 12 --merge --delete-branch          # 保留完整历史
gh pr merge 12 --rebase --delete-branch         # 线性历史
gh pr close 12                                  # 不合并,关闭
git fetch --prune                               # 清理已删除的远程分支引用

# ── Issue ────────────────────────────────────────────
gh issue create --title "[Bug] 分页第2页数据错误" --label "type/bug,priority/p1"
gh issue list --label "good first issue" --state open
gh issue comment 42 --body "已定位到 OrdersList.vue:42"
gh issue close 42 --reason "completed"

# ── 安全相关 ─────────────────────────────────────────
git push --force-with-lease                     # 只对自己的分支用
git log --all --full-history -- "*.env"         # 检查历史中是否出现过 .env
gitleaks detect --source . --verbose            # 本地扫描密钥(需先安装)

常见坑

高频错误清单

1. 在 main 上直接开发:哪怕只有你一个人,也养成切分支的习惯——否则你永远无法为一个「顺手的小改动」单独开 PR。

2. PR 里混入格式化改动:prettier 全量格式化会把真正的逻辑改动淹没在几千行 diff 里。格式化单独成 PR。

3. 不拉取主干就开 PR:基于一周前的 main 开发,合并时冲突一堆。开始前先 git pull --ff-only。

4. 合并后不删分支:分支列表变成垃圾场。

5. 用 Closes 关掉不相关的 Issue:破坏追溯性。

6. 评审只写「LGTM」:要么真的看过并说明看了什么,要么不批准。

7. 批准后又偷偷推送:开启「Dismiss stale approvals」防止这种情况。

8. 把密钥写进 .env.example:模板文件是要提交的,只放占位值(API_KEY=your-key-here)。

9. Issue 描述里贴生产日志:可能含用户隐私、内部 IP、token。先脱敏。

10. 对公共分支用 --force:见上文,等于删别人的工作。

练习题

  1. 分支策略选择:一个 6 人团队做 B 端 SaaS,每周发布一次,有 staging 验收环境。他们现在用 Git Flow,develop 与 main 频繁冲突。请给出一个更合适的策略,并说明迁移步骤与风险。
  1. 拆 PR:你接到的任务是「支持优惠券功能」,涉及:新增 coupons 表与迁移脚本、CouponService、POST /coupons/apply 接口、结算页选择券的 UI、管理后台建券页面。请把它拆成 3~5 个可独立评审、独立通过 CI 的 PR,并写出每个 PR 的标题与一句话描述。
  1. Code Review 演练:以下评论有什么问题?请改写成建设性版本。

> 「这里你怎么不用 Map?List 查询是 O(n),性能肯定有问题。改一下。」

写出改写后的评论,并说明你会在什么情况下同意原评论的判断。

  1. 密钥泄露处置:同事在周五下午误把一个 AWS AccessKey 推到了公司私有仓库的 main 分支(仓库有 20 人协作)。请按时间顺序列出你的处置步骤,并指出哪一步最容易被做错。
  1. 合并方式选择:项目要求「主干历史一行一个功能、可按功能回滚、能用 git bisect 定位到具体功能但不能定位到功能内部的小提交」。请选择合并方式并说明取舍。若后来团队要求「bisect 必须能定位到功能内部的每个小提交」,需要改变什么前提?

FAQ

GitHub 和 GitLab 到底选哪个?

看三个约束:(1) 网络——国内团队若无法稳定访问 github.com,企业内部协作优先自托管 GitLab 或 Gitee;(2) 是否需要一体化——GitLab 内置 CI、制品库、安全扫描、环境与审批,开箱即用程度更高;GitHub 的生态更大(Actions 市场、社区、开源项目基数);(3) 是否开源/面向社区——开源项目几乎都以 GitHub 为主场,贡献者规模不可比。个人学习建议:代码放 GitHub 练协作,同时会一点 GitLab CI,两者概念高度对应。

小团队真的需要 PR 流程吗?两个人直接推主干不行吗?

「两个人」的场景下,PR 的价值主要不是评审(你们彼此信任),而是:(1) CI 的门禁——PR 上跑测试,绿了才能合,避免把主干搞坏;(2) 变更记录——半年后能查到这行代码为什么改;(3) 回滚粒度——一个功能一个提交。成本很低(多几次点击),收益长期复利。可以省掉「必须有人批准」,但不建议省掉「必须走 PR + 必须 CI 绿」。

Code Review 时同事总挑格式问题,怎么处理?

用工具消灭这类讨论:接入 Prettier / ESLint / Ruff,配 pre-commit 钩子在提交前自动修复,CI 里加 --check 模式。然后在团队内明确一条规则:「凡工具能检查的,不在评审里提」。如果对方仍坚持个人偏好,把它写进 .editorconfig 或 lint 规则里,让规则说话,而不是让资深的人说话。

我的 PR 挂了一周没人评审怎么办?

按顺序做:(1) 确认 PR 小且描述清晰(大 PR 天然被拖延);(2) 在 PR 里 @ 具体的人(@alice 这个改动涉及你负责的支付模块,方便时看一下),而不是发在群里;(3) 主动约 15 分钟同步过一遍(很多「没时间评审」其实是「不知从哪看起」);(4) 找团队确认评审 SLA(如「24 小时内给出首次反馈」)并写进 CONTRIBUTING;(5) 若长期无人评审,说明流程本身有问题——把它提到团队会议,而不是默默继续堆 PR。

相关笔记

  • 工具-01-Git版本控制:分支、合并、变基、冲突解决、reflog 找回误删提交。
  • 工具-08-CICD入门:GitHub Actions 语法、流水线设计、分支保护如何与 CI 配合。
  • 工具-02-命令行与Shell:GitHub CLI(gh)与 Git 命令行效率技巧。
  • 后端-08-部署与运维基础:Secrets 管理、环境变量、灰度发布与回滚。
  • 前端-09-前端工程化与调试:Prettier / ESLint 落地,让风格问题离开评审。
  • 常见问题FAQ:跨方向的协作与工具类常见疑问。

参考来源

关于链接与访问

上述 GitHub 文档均使用 docs.github.com 域名(含中文页面),未引用 github.com 路径。中国大陆访问 GitHub 服务可能不稳定,如遇打不开,可先用 docs.gitlab.com 的对应章节(MR 与分支保护概念基本一一对应)。