二稿核验说明(2026-10-15):本文为“河洛序”教程二稿,已按官方规范与文档修订。旧实验日志单独标为“一稿留存输出”,不代表本次在Windows上的复跑;本次环境与结果见本批核验记录。示例中的“星河笔记”、账号、订单、价格与政策均为虚构教学数据。
一句话定义
GitHub 是在Git仓库上提供代码托管、Pull Request评审、Issue、自动化及权限管理的平台。Git在本地管理版本,GitHub管理围绕仓库的协作服务;两者可以分别使用。
为什么重要
- 开源 AI 生态的集散地:PyTorch、transformers、vLLM、llama.cpp 等项目都在 GitHub 上开发,读 Issue 和 PR 往往是排错最快的途径。
- Pull Request 是现代团队的评审单元:改动先在分支上完成,经过评审(k1.prog.code-review)与自动检查后再合并进主分支。
- GitHub Actions 让“按事件自动测试、评测和部署”可通过工作流表达;仍需项目脚本、依赖和权限配置(k6.swe.ci-cd)。
原理 / 图解
一次 PR 的生命周期(GitHub Flow)https://docs.github.com/en/get-started/using-github/github-flow
| 功能 | 作用 | 文档 |
|---|---|---|
| Pull Request | 分支合并前的讨论、评审、检查 | https://docs.github.com/en/pull-requests |
| 三种合并方式 | merge commit / squash / rebase | https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/about-merge-methods-on-github |
| 分支保护 / 规则集 | 要求评审数、检查通过、禁止强推 | https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets |
| CODEOWNERS | 按路径指定代码所有者;强制批准需另设保护规则 | https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners |
| Actions | 事件驱动的 CI/CD 工作流 | https://docs.github.com/en/actions |
| Secret scanning / Dependabot | 检测泄露的密钥、过期依赖 | https://docs.github.com/en/code-security |
以上均为 GitHub 官方文档。
适用边界与核验要点
CODEOWNERS会按规则请求评审,但必须配合分支保护或规则集中的必审要求,才构成合并门禁;草稿PR也有不同的通知行为。一个job的检出、Python环境和安装依赖不会自动传到另一个job。本地裸仓库只能演示Git传输与合并,解析YAML只能说明能读取结构,不能验证GitHub事件、权限或工作流可执行性。actions标签可能移动,示例中的v4/v5是模板引用而非最新版本承诺。
本次检索核对的主要依据(2026-10-15):
- GitHub:Code owners:自动请求与强制批准是两项设置。
- GitHub flow:分支、PR、评审与合并协作流程。
可运行示例
平台端PR、评审和Actions未在本例中验证。本地裸仓库用于演示Git传输与合并;YAML只做本地结构读取。工作流中的项目文件路径需按真实仓库补齐。
文件:
# 文件:examples/github/ci.yml
# .github/workflows/ci.yml —— 本文示例工作流(未在 GitHub 上实跑,仅本地解析)
name: ci
on:
pull_request:
branches: [main]
push:
branches: [main]
permissions:
contents: read # 默认最小权限
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
python: ["3.11", "3.12"]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python }}
- run: pip install -r requirements.txt
- run: python -m pytest -q
eval:
needs: test
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- run: pip install -r requirements.txt
- run: python eval/run_regression.py --threshold 0.85
# 文件:examples/03_github.sh
#!/usr/bin/env bash
# 在本机模拟 GitHub 的“远程仓库 + 功能分支 + Pull Request + 合并”流程(不访问 github.com)。
set -euo pipefail
export GIT_AUTHOR_NAME=alice GIT_AUTHOR_EMAIL=alice@example.com GIT_COMMITTER_NAME=alice GIT_COMMITTER_EMAIL=alice@example.com
export GIT_AUTHOR_DATE="2026-10-14T10:00:00+08:00" GIT_COMMITTER_DATE="2026-10-14T10:00:00+08:00"
HERE=$(pwd); D=$(mktemp -d); cd "$D"
echo "== ① 一个裸仓库扮演 GitHub 上的 origin"
git init -q --bare -b main origin.git
git clone -q origin.git alice 2>/dev/null; cd alice
printf 'def add(a, b):\n return a + b\n' > calc.py; git add .; git commit -q -m "init"; git push -q origin main
echo "== ② Alice 开功能分支、推送(相当于在 GitHub 上开 PR 之前的准备)"
git switch -q -c feat/mul
printf 'def mul(a, b):\n return a * b\n' >> calc.py; git commit -q -am "feat: 增加乘法"
git push -q -u origin feat/mul 2>&1 | grep -v '^$' || true
git branch -r
echo "== ③ PR 摘要:git request-pull 生成“请把这个分支合进 main”的说明(GitHub PR 页面展示的就是这些信息)"
git request-pull main "$D/origin.git" feat/mul | sed "s#$D#<tmp>#"
echo "== ④ 评审通过后以 merge commit 方式合并(GitHub 的 'Create a merge commit' 按钮)"
git switch -q main
GIT_COMMITTER_DATE="2026-10-14T11:00:00+08:00" git merge -q --no-ff feat/mul -m "Merge pull request #1 from alice/feat/mul"
git push -q origin main; git log --oneline --graph
echo "== ⑤ 本地解析工作流文件(.github/workflows/ci.yml)"
"${PY:-python3}" - "$HERE/github/ci.yml" <<'PY'
import sys, yaml
wf = yaml.safe_load(open(sys.argv[1]))
on = wf.get(True, wf.get("on")) # 注意:YAML 1.1 会把键 on 解析成布尔 True
print("触发事件:", list(on), " 顶层权限:", wf["permissions"])
for name, job in wf["jobs"].items():
m = job.get("strategy", {}).get("matrix", {})
n = 1
for v in m.values(): n *= len(v)
print(f"job {name}: needs={job.get('needs')}, 矩阵组合数={n}, 步骤数={len(job['steps'])}")
print("PyYAML 解析出的顶层键:", list(wf))
PY
rm -rf "$D"
一稿留存输出
以下日志按一稿保留,来自一稿声称的原环境;不是本次复跑结果。二稿代码改动后可产生不同输出,实际复跑状态以本批核验记录为准。
== ① 一个裸仓库扮演 GitHub 上的 origin
== ② Alice 开功能分支、推送(相当于在 GitHub 上开 PR 之前的准备)
origin/feat/mul
origin/main
== ③ PR 摘要:git request-pull 生成“请把这个分支合进 main”的说明(GitHub PR 页面展示的就是这些信息)
The following changes since commit 5bcd1a1ba272eaefd4bf35f2a8cab8f4fd40bc7f:
init (2026-10-14 10:00:00 +0800)
are available in the Git repository at:
<tmp>/origin.git feat/mul
for you to fetch changes up to 23a204e2b64dc2a0135d599ece7c8a163ae39962:
feat: 增加乘法 (2026-10-14 10:00:00 +0800)
----------------------------------------------------------------
alice (1):
feat: 增加乘法
calc.py | 2 ++
1 file changed, 2 insertions(+)
== ④ 评审通过后以 merge commit 方式合并(GitHub 的 'Create a merge commit' 按钮)
* bfbc223 Merge pull request #1 from alice/feat/mul
|\
| * 23a204e feat: 增加乘法
|/
* 5bcd1a1 init
== ⑤ 本地解析工作流文件(.github/workflows/ci.yml)
触发事件: ['pull_request', 'push'] 顶层权限: {'contents': 'read'}
job test: needs=None, 矩阵组合数=2, 步骤数=4
job eval: needs=test, 矩阵组合数=1, 步骤数=2
PyYAML 解析出的顶层键: ['name', True, 'permissions', 'jobs']
- ② 推送后出现
origin/feat/mul,这就是在 GitHub 上能对它“Compare & pull request”的远程分支。 - ③
git request-pull是 Git 自带、比 GitHub 早得多的“拉取请求”:说明从哪个提交开始、去哪里拉、有哪些提交和文件变化。GitHub 的 PR 把同样的信息做成了网页,并加上了评论与检查。 - ④
--no-ff生成一个有两个父提交的合并提交bfbc223,图中|\与|/就是分叉与汇合;GitHub 的 “Create a merge commit” 产生的就是这种历史。 - ⑤ 工作流解析出两个触发事件、
test任务的矩阵组合数 2(两个 Python 版本)、eval依赖test。一稿实验记录:PyYAML 把顶层键on解析成了布尔值True(输出里顶层键列表中的True),因为 YAML 1.1 中on/off/yes/no是布尔字面量;GitHub Actions 自己的解析器能正确处理,但你自己写脚本读工作流文件时要留意YAML 1.1 布尔类型:https://yaml.org/type/bool.html。
自测
问题: 配置CODEOWNERS后,PR能否在无人批准时合并?
参考答案: 如果没有启用要求Code Owner批准的保护规则,仍可能合并。还要检查规则适用分支、例外权限和是否允许绕过。
常见误区
- “Fork 和分支是一回事”:分支在同一仓库内;fork是在平台上创建有关联的独立仓库,用于贡献与后续同步,适合没有写权限的外部贡献者。
- “私有仓库就不用担心密钥泄露”:协作者、CI 日志、日后转公开都可能暴露;GitHub 的 push protection 能在推送时拦截已知格式的密钥,但不能替代密钥管理(k6.sec.secret-management)。
- “工作流默认权限很小”:
GITHUB_TOKEN的默认权限取决于组织/仓库设置;官方建议在工作流里用permissions:显式声明最小权限https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication。 - “
uses: xxx@v4永远是同一份代码”:标签可以被移动;安全要求高的场景官方建议固定到完整提交 SHAhttps://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions。
与 AI 开发的关系
- 在 PR 中加入评测回归检查(本例的
eval任务),让提示词改动和代码改动一样要“过检查才能合并”。 - AI 代码评审机器人、AI 编程 Agent 通常以 PR 的形式提交改动,人类评审仍是最后一道关。
- 对于常见来自fork的pull_request工作流,仓库secrets通常不下发;仍需核对事件类型、仓库设置和例外,这是防止恶意 PR 窃取密钥的设计;
pull_request_target事件会改变这一点,使用时要格外小心见上方 security hardening 文档。
延伸阅读
- GitHub Skills 互动教程:https://skills.github.com/
- GitHub CLI:https://cli.github.com/manual/
尚未验证的范围
- 未在GitHub端创建PR或执行Actions;本地Git过程与YAML读取不能证明平台权限和安全策略生效。
本次示例运行范围
2026-10-15:未复跑。按所列资料及代码审阅修订;未执行完整示例。未在GitHub端创建PR或执行Actions;本地Git过程与YAML读取不能证明平台权限和安全策略生效。。
“一稿留存输出”保留原字,不是二稿代码新生成的结果;其原结论须结合二稿修订与边界阅读。