From 2ddaba8a05ab1366d7675f9b00827b330d4efe15 Mon Sep 17 00:00:00 2001 From: cadywang <109458837+cadywang@users.noreply.github.com> Date: Fri, 23 Oct 2026 11:59:29 +0800 Subject: [PATCH 1/6] post: add the GitHub guide, part 1: accounts and repositories Cover the module map, account security (2FA, SSH, PAT), creating a repository, the web editor, and the clone/commit/push loop. Signed-off-by: cadywang <109458837+cadywang@users.noreply.github.com> --- source/_posts/github-guide-01-start.md | 329 +++++++++++++++++++++++++ 1 file changed, 329 insertions(+) create mode 100644 source/_posts/github-guide-01-start.md diff --git a/source/_posts/github-guide-01-start.md b/source/_posts/github-guide-01-start.md new file mode 100644 index 0000000..fd539eb --- /dev/null +++ b/source/_posts/github-guide-01-start.md @@ -0,0 +1,329 @@ +--- +title: GitHub 使用指南（一）：账号、仓库与第一次提交 +date: 2026-10-23 09:00:00 +tags: [GitHub, Git, 版本控制, 新手入门, 教程] +categories: [教程] +description: 从注册账号、配置 SSH、创建仓库，到在网页和命令行里完成第一次提交——把新手最容易卡住的每一步拆开讲。 +--- + +很多人第一次打开 GitHub 会愣住：左边是代码，上面一排 Code / Issues / Pull requests / Actions / Security / Insights / Settings， +右边还有 Watch / Fork / Star。**它不只是一个"放代码的网盘"，而是一整套协作系统。** + +这个系列按模块拆开讲，目标很明确：**没接触过 GitHub 的人，照着做能把自己的代码传上去、能和别人协作、能看懂 CI 的结果。** +本篇只做两件事：认路（模块地图），以及完成第一次提交。 + +> **GitHub 使用指南（6 篇）** +> 1. 入门：账号、仓库与第一次提交（本篇） +> 2. [Issues、Projects、Discussions 与 Wiki](/2026/10/23/github-guide-02-issues-projects/) +> 3. [Pull Request：从分支到合并](/2026/10/23/github-guide-03-pull-requests/) +> 4. [Actions、Releases 与 Packages](/2026/10/23/github-guide-04-actions-releases/) +> 5. [安全、组织与 Pages](/2026/10/23/github-guide-05-security-org/) +> 6. [从 0 到 1 的完整演练与避坑清单](/2026/10/23/github-guide-06-practice-tips/) + +--- + +## 一、Git 和 GitHub 不是一回事 + +先把最容易混淆的概念分开： + +| 概念 | 是什么 | 装在哪 | 负责什么 | +| --- | --- | --- | --- | +| **Git** | 版本控制工具（命令行程序） | 你的电脑 | 记录每次改动、管理分支、合并历史 | +| **GitHub** | 托管 Git 仓库的网站 + 协作平台 | 浏览器 / 云端 | 存代码、开 Issue、做代码审查、跑 CI、发版 | +| **仓库（Repository）** | 一个被 Git 管理的项目目录 | 本地 + 云端各一份 | 代码、文档、Issue、PR、Actions 都在里面 | + +> 关键点：**Git 是工具，GitHub 是服务。** 你可以在没有 GitHub 的情况下用 Git；但 GitHub 的所有协作功能都建立在 Git 之上。 +> 所以本系列会同时讲「网页上点什么」和「命令行敲什么」——两者操作的是同一份数据。 + +--- + +## 二、GitHub 的模块地图 + +右上角头像、仓库顶部页签、个人设置里，藏着十几块功能。先把地图记住： + +| 模块 | 一句话作用 | 入口 | 本系列 | +| --- | --- | --- | --- | +| **Repositories（仓库）** | 存代码与文档 | 头像 → Your repositories | 本篇 | +| **Code（代码）** | 文件树、提交历史、分支 | 仓库 → Code | 本篇 | +| **Issues（议题）** | 记录 bug、需求、待办 | 仓库 → Issues | 第 2 篇 | +| **Projects（项目）** | 跨 Issue/PR 的看板与计划 | 仓库 → Projects | 第 2 篇 | +| **Discussions（讨论）** | 问答、公告、社区交流 | 仓库 → Discussions（需开启） | 第 2 篇 | +| **Wiki** | 轻量知识库 | 仓库 → Wiki（需开启） | 第 2 篇 | +| **Pull requests（PR）** | 提议合并、代码审查 | 仓库 → Pull requests | 第 3 篇 | +| **Actions（自动化）** | CI/CD，跑测试、构建、发布 | 仓库 → Actions | 第 4 篇 | +| **Releases / Tags** | 版本发布与变更说明 | 仓库 → Code → Releases | 第 4 篇 | +| **Packages** | 发布依赖包（npm、容器等） | 个人/组织 → Packages | 第 4 篇 | +| **Security** | 依赖漏洞、代码扫描、密钥扫描 | 仓库 → Security | 第 5 篇 | +| **Insights** | 提交/访问统计、贡献者 | 仓库 → Insights | 第 5 篇 | +| **Pages** | 把仓库发布成网站 | 仓库 → Settings → Pages | 第 5 篇 | +| **Settings** | 仓库设置、权限、分支保护 | 仓库 → Settings | 第 3、5 篇 | + +> 页签会随仓库启用的功能变化：没开 Wiki 就没有 Wiki 页签，没开 Discussions 就没有 Discussions。 +> 这些开关都在 **Settings → General → Features** 里。 + +--- + +## 三、账号与安全：先把「能安全地推代码」准备好 + +### 3.1 注册与基本设置（网页） + +1. 打开 ，点 **Sign up**，填邮箱、密码、用户名。 +2. 用户名会出现在所有仓库地址里（`github.com/<用户名>/<仓库名>`），**改起来很麻烦**，建议用稳定的英文 ID。 +3. 注册后到邮箱点验证链接。 +4. 头像 → **Settings** → **Public profile**：可以填姓名、公司、所在地、个人主页；也可以勾选隐藏邮箱，避免公开真实邮箱。 + +### 3.2 开启两步验证（强烈建议） + +头像 → **Settings** → **Password and authentication** → **Two-factor authentication** → **Enable**。 +可以选择验证器 App（TOTP）或安全密钥。开启后会给你一组**恢复码**，抄下来离线保存—— +手机丢了、验证器没了，就靠它找回账号。 + +### 3.3 配置 SSH（推荐，一次配置长期使用） + +HTTPS 方式推送每次都要认证；SSH 配好之后 `push` 不再问密码。 + +**第一步：在本机生成密钥**（没有再用旧密钥的情况下）： + +```bash +ssh-keygen -t ed25519 -C "你的邮箱@example.com" +# 一路回车即可；想要口令保护就设置一个 passphrase +``` + +生成的公钥在 `~/.ssh/id_ed25519.pub`（Windows 是 `C:\Users\<你>\.ssh\id_ed25519.pub`）。 + +**第二步：把公钥贴到 GitHub** + +1. 头像 → **Settings** → **SSH and GPG keys** → **New SSH key**。 +2. **Title** 填一个能认出机器的名字（例如 `work-laptop`）。 +3. **Key type** 保持 `Authentication Key`，把公钥**整段**粘进去（以 `ssh-ed25519` 开头）。 +4. 点 **Add SSH key**。 + +**第三步：验证** + +```bash +ssh -T git@github.com +# 看到 "Hi <用户名>! You've successfully authenticated..." 就成功了 +``` + +### 3.4 如果只能用 HTTPS：用 PAT，不要用账号密码 + +GitHub 早已不支持用登录密码做 Git 认证。HTTPS 方式需要一个 **Personal Access Token（PAT）**： + +1. 头像 → **Settings** → **Developer settings** → **Personal access tokens**。 +2. 选 **Fine-grained tokens**（推荐）→ **Generate new token**。 +3. 填名称、过期时间，**Repository access** 选具体仓库或全部仓库。 +4. 在 **Permissions** 里按需勾选：只读写代码通常需要 **Contents: Read and write**； + 要发 PR 还需要 **Pull requests: Read and write**。 +5. 生成后**只显示一次**，马上复制保存。 + +> 安全底线：token 等于密码。不要提交进仓库、不要贴进聊天记录、不要写进脚本里的明文变量。 +> 更稳妥的做法是放进系统环境变量或密钥管理工具，并设置较短的有效期。 + +--- + +## 四、创建第一个仓库（网页流程） + +1. 右上角 **+** → **New repository**。 +2. **Repository name**：例如 `hello-github`（建议小写、用 `-` 分隔）。 +3. **Description**：一句话说明它是什么（可选，但建议写）。 +4. **Public / Private**： + - Public：所有人可见，适合开源、作品集； + - Private：只有你和被邀请的人可见，适合公司项目、练习。 +5. **Initialize this repository with**（第一次建仓建议勾上）： + - **Add a README file**：仓库首页会显示它，新手必备； + - **Add .gitignore**：选一个模板（例如 `Node` / `Python` / `VisualStudio`），自动忽略不需要提交的文件； + - **Choose a license**：开源项目建议选 MIT / Apache-2.0。 +6. 点 **Create repository**。 + +创建完成后你会看到仓库主页： + +``` +┌──────────────────────────────────────────────────────────┐ +│ cadywang / hello-github ★ Star ⑂ Fork 👁 Watch │ +├──────────────────────────────────────────────────────────┤ +│ Code Issues Pull requests Actions Projects Wiki ... │ +│ │ +│ main ▾ ← 分支选择器 │ +│ README.md Add file ▾ <> Code ▾ (克隆) │ +└──────────────────────────────────────────────────────────┘ +``` + +### 4.1 完善仓库的「门面」 + +- 点右侧 **About** 旁边的齿轮：填 **Description**、**Website**、**Topics**（用空格分隔的关键词，例如 `python cli tutorial`）。 +- README 是别人对仓库的第一印象：写清楚「它是做什么的、怎么安装、怎么用、怎么贡献」。 +- **Watch / Fork / Star** 的区别： + - **Star**：收藏 + 表达喜欢，出现在你的 Stars 列表； + - **Fork**：把别人的仓库复制一份到你账号下，之后可以自由修改、发 PR； + - **Watch**：订阅这个仓库的通知（参与/全部/忽略），别乱点，否则邮箱会被刷屏。 + +--- + +## 五、网页上改文件（不改代码也能用） + +### 5.1 新建文件 + +1. 进入仓库 → **Add file** → **Create new file**。 +2. 文件名框里可以输 `docs/start.md` 这样的路径，GitHub 会自动建目录。 +3. 在编辑区写内容（支持 Markdown 预览：**Preview** 页签）。 +4. 拉到页面下方 **Commit changes**： + - **Commit message**：写清楚这次改了什么（例如 `docs: add quick start`）； + - **Extended description**：可选； + - 选择 **Commit directly to the `main` branch**，或 **Create a new branch for this commit and start a pull request**。 +5. 点 **Commit changes**。 + +> 新手最容易踩的坑：在网页上直接往 `main` 提交。多人项目里 `main` 通常有分支保护， +> 你会被要求开分支 + 发 PR——这正是第 3 篇的内容。 + +### 5.2 上传文件 + +仓库 → **Add file** → **Upload files** → 把文件拖进去 → 填提交信息 → **Commit changes**。 +适合上传图片、文档、压缩包（注意大文件走 Git LFS，见第 6 篇）。 + +### 5.3 修改与删除 + +- 打开文件，右上角 **铅笔图标** = 编辑；**垃圾桶图标** = 删除。 +- 历史版本：文件页右上角 **History**，可以看到每次提交的 diff； + 单行左侧的 **Blame** 能看出这一行是谁、哪次提交改的。 +- 想下载单个文件：**Raw**；整个仓库：绿色 **Code** 按钮 → **Download ZIP**。 + +### 5.4 网页的边界 + +网页适合：改文档、修错别字、小改动、快速发起 PR。 +不适合：跑测试、批量改文件、处理冲突、管理复杂分支——这些在本地用命令行更稳。 + +--- + +## 六、本地工作流：clone → 改 → commit → push + +### 6.1 装 Git 并做一次性配置 + +```bash +git --version # 确认已安装；没有就装 Git for Windows / Xcode CLT / apt install git +git config --global user.name "你的名字" +git config --global user.email "你的邮箱@example.com" +git config --global init.defaultBranch main +``` + +> `user.name` / `user.email` 会写进每个提交，是「谁改的」的依据。**不要随便填**， +> 它要和你 GitHub 账号的提交记录对得上。 + +### 6.2 克隆仓库 + +仓库页 → 绿色 **Code** 按钮 → 选 **SSH**（推荐）或 **HTTPS** → 复制地址： + +```bash +git clone git@github.com:<用户名>/hello-github.git +cd hello-github +``` + +### 6.3 每天都会用到的五条命令 + +| 命令 | 作用 | 什么时候用 | +| --- | --- | --- | +| `git status` | 看工作区/暂存区状态 | 每次提交前 | +| `git add <文件>` | 把改动放进暂存区 | 准备提交 | +| `git commit -m "..."` | 生成一次提交 | 一小步做完 | +| `git pull` | 把远端更新拉下来 | 开始工作前、推送失败时 | +| `git push` | 把本地提交推到 GitHub | 提交完成后 | + +一个典型循环： + +```bash +git pull # 先同步 +# ……改文件…… +git status # 看清改了什么 +git add README.md +git commit -m "docs: add install steps" +git push +``` + +### 6.4 分支：为什么不能一直在 main 上改 + +`main` 是「随时可发布」的主线。所有改动先放到分支上，做完再合并（PR 流程）： + +```bash +git switch -c docs/install-steps # 新建并切换到分支 +git add . +git commit -m "docs: add install steps" +git push -u origin docs/install-steps +# 推送后终端会打印一个 "Create a pull request" 链接 +``` + +- `git switch -c <名字>`：创建并切换分支（老教程里的 `git checkout -b` 等价）。 +- `git switch main`：回到主线。 +- `git branch -vv`：看本地分支及它们跟踪的远端分支。 + +--- + +## 七、提交信息：写给三个月后的自己 + +GitHub 上每次提交都会永久留在历史里。好的提交信息让 `git log` 和 PR 变得可读： + +``` +docs: add install steps + +Explain the Windows and macOS setup separately; the previous paragraph +assumed a POSIX shell and confused the first-time readers. + +Signed-off-by: cadywang +``` + +| 规则 | 说明 | +| --- | --- | +| 第一行是摘要 | `<范围>: <祈使句>`，例如 `docs: fix broken link`，不超过 72 字符 | +| 空一行再写正文 | 正文说「为什么改」，不是逐行复述 diff | +| 一次提交一件事 | 方便回滚、方便 review、方便 `git bisect` | +| 用祈使语气 | `add` / `fix` / `remove`，不要写 `added` / `fixes` | +| 署名（可选但推荐） | `git commit -s` 会加 `Signed-off-by:`，很多项目据此做 DCO 检查 | + +--- + +## 八、仓库设置：新手也该知道的几个开关 + +仓库 → **Settings**： + +| 位置 | 能做什么 | +| --- | --- | +| **General → Default branch** | 改默认分支（例如从 `master` 改成 `main`） | +| **General → Features** | 开关 Issues / Projects / Wiki / Discussions | +| **General → Danger Zone** | 改可见性、转移仓库、**删除仓库**（不可恢复，慎点） | +| **Branches / Rules** | 分支保护、必需检查（第 3 篇） | +| **Actions → General** | 控制 Actions 权限、允许哪些 Action | +| **Pages** | 把仓库发布成网站（第 5 篇） | +| **Secrets and variables** | 存放 CI 用的密钥（第 4 篇） | + +--- + +## 九、速查：第一次提交的最小路径 + +```bash +# 1) 一次性配置 +git config --global user.name "你的名字" +git config --global user.email "你的邮箱@example.com" +ssh -T git@github.com # 看到 Hi <用户名> 就 OK + +# 2) 克隆 +git clone git@github.com:<用户名>/hello-github.git +cd hello-github + +# 3) 开分支、改、提交、推送 +git switch -c docs/first-change +git add . +git commit -m "docs: add a first change" +git push -u origin docs/first-change +``` + +推送后打开终端里打印的链接，就是第 3 篇要讲的 **Pull Request**。 + +--- + +## 十、小结 + +- Git 管版本，GitHub 管协作；网页和命令行操作的是同一份仓库。 +- 先把账号安全配好：2FA + SSH（或 PAT），不要用密码推代码。 +- 建仓时顺手加 README / .gitignore / License，能省掉以后很多麻烦。 +- 日常循环就五条命令：`status` / `add` / `commit` / `pull` / `push`。 +- 别在 `main` 上直接改：开分支 → 提交 → 推送 → PR。 + +> 下一篇：[Issues、Projects、Discussions 与 Wiki](/2026/10/23/github-guide-02-issues-projects/) \ No newline at end of file From 5764aacc76ecdbbe8f9b7ee08b3a4828b07aa92e Mon Sep 17 00:00:00 2001 From: cadywang <109458837+cadywang@users.noreply.github.com> Date: Fri, 23 Oct 2026 11:59:29 +0800 Subject: [PATCH 2/6] post: add the GitHub guide, part 2: issues and planning Cover Issues (templates, labels, milestones, PR links), Projects views and workflows, Discussions, Wiki, notifications and search. Signed-off-by: cadywang <109458837+cadywang@users.noreply.github.com> --- .../_posts/github-guide-02-issues-projects.md | 217 ++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 source/_posts/github-guide-02-issues-projects.md diff --git a/source/_posts/github-guide-02-issues-projects.md b/source/_posts/github-guide-02-issues-projects.md new file mode 100644 index 0000000..b3b820c --- /dev/null +++ b/source/_posts/github-guide-02-issues-projects.md @@ -0,0 +1,217 @@ +--- +title: GitHub 使用指南（二）：Issues、Projects、Discussions 与 Wiki +date: 2026-10-23 09:30:00 +tags: [GitHub, Issues, Projects, 协作, 新手入门] +categories: [教程] +description: 用 Issues 记录待办、用 Projects 做计划、用 Discussions 做问答、用 Wiki 写知识库——四个协作模块的网页操作流程与使用边界。 +--- + +代码只是协作的一部分。一个项目真正费时间的是：**谁在做什么、问题记在哪、讨论沉淀到哪。** +GitHub 把这部分拆成四个模块：Issues、Projects、Discussions、Wiki。 + +本篇按「什么时候用哪个」来讲，每个模块都给完整的网页操作步骤。 + +> **GitHub 使用指南（6 篇）** +> 1. [入门：账号、仓库与第一次提交](/2026/10/23/github-guide-01-start/) +> 2. Issues、Projects、Discussions 与 Wiki（本篇） +> 3. [Pull Request：从分支到合并](/2026/10/23/github-guide-03-pull-requests/) +> 4. [Actions、Releases 与 Packages](/2026/10/23/github-guide-04-actions-releases/) +> 5. [安全、组织与 Pages](/2026/10/23/github-guide-05-security-org/) +> 6. [从 0 到 1 的完整演练与避坑清单](/2026/10/23/github-guide-06-practice-tips/) + +--- + +## 一、Issues：把「要做的事」变成可追踪的条目 + +### 1.1 它是什么 + +Issue 是仓库里的一条「工单」：bug、需求、文档缺口、讨论都可以是 Issue。 +每条 Issue 有编号（`#12`）、标题、正文、标签、指派人、里程碑、项目归属，以及一条时间线 +（评论、提交引用、状态变化）。Issue 编号和 PR 共用同一个序列，所以 `#12` 既可能是 Issue 也可能是 PR。 + +### 1.2 网页新建 Issue（完整流程） + +1. 进入仓库 → 点 **Issues** 页签。 +2. 点绿色 **New issue**。 + - 如果仓库配置了模板，会先出现模板选择页（例如 `Bug report` / `Feature request`）； + - 选一个模板，正文会自动带出需要填的字段。 +3. 填 **Title**：一句话说清问题，例如 `登录页在 Safari 下白屏`。 +4. 填正文（支持 Markdown）： + - 环境 / 版本 / 复现步骤 / 期望结果 / 实际结果； + - 可以直接 `@用户名` 通知别人、`#12` 引用别的 Issue/PR； + - 用 `- [ ] 待办` 写任务清单，勾选状态会被 GitHub 记住。 +5. 右侧栏（提交前就能设置）： + - **Assignees**：指派给谁； + - **Labels**：分类，例如 `bug`、`docs`、`good first issue`； + - **Projects**：放进项目看板； + - **Milestone**：归到某个版本/迭代。 +6. 点 **Submit new issue**。 + +### 1.3 关闭、重开与「关联 PR」 + +- Issue 底部评论框旁有 **Close issue**；关闭后还能 **Reopen**。 +- 关闭时有 **Close as completed** / **Close as not planned** 两种语义，团队统计时能区分。 +- **在 PR 描述里写 `Fixes #12` / `Closes #12`**，PR 合并时 GitHub 会自动关闭对应 Issue。 + 这是最常用的「代码与问题挂钩」的方式；也可以在提交信息里写。 + +### 1.4 标签、里程碑与模板（维护者视角） + +| 功能 | 网页位置 | 用途 | +| --- | --- | --- | +| **Labels** | Issues → **Labels** → **New label** | 分类：`bug` / `enhancement` / `docs` / `question` | +| **Milestones** | Issues → **Milestones** → **New milestone** | 归到版本或迭代，会显示完成百分比 | +| **Issue templates** | Settings → General → Issues → **Set up templates**，或仓库里加 `.github/ISSUE_TEMPLATE/*.yml` | 让提交者按格式填写 | +| **Pinned issues** | Issues 列表 → 右上 **Pin issue** | 把重要 Issue 固定在列表顶部 | + +### 1.5 搜索与筛选 + +Issues 列表上方的搜索框支持限定符： + +``` +is:open label:bug assignee:@me +is:closed milestone:v1.0 sort:updated-desc +no:assignee label:docs +``` + +常用的可以在搜索后点 **Save** 存成过滤器，下次一键打开。 + +--- + +## 二、Projects：跨 Issue/PR 的计划视图 + +Issue 是「条目」，Projects 是「把这些条目排进计划」。 + +### 2.1 网页新建 Project（完整流程） + +1. 仓库 → **Projects** 页签 → **New project**（个人主页的 Projects 页签也可以建跨仓库项目）。 +2. 选模板： + - **Table**：表格式，适合管理字段； + - **Board**：看板（Todo / In Progress / Done），适合日常推进； + - **Roadmap**：时间线，适合排期。 +3. 填项目名称，点 **Create**。 +4. 项目里点 **+ Add item**，可以： + - 直接输入标题新建草稿 Issue； + - 搜索并添加已有 Issue/PR。 +5. 右侧的 **Fields** 可以加自定义字段：文本、数字、日期、单选（例如 `Priority: P0/P1/P2`）。 +6. **Views** 页签可以保存多个视图（按状态分组、只看我的、只看某标签）。 +7. 项目右上 **⋯ → Workflows** 内置自动化： + - Issue 创建时自动加入项目； + - PR 合并后自动把条目标为 Done； + - 关闭的 Issue 自动归档。 + +### 2.2 什么时候该用 + +| 场景 | 建议 | +| --- | --- | +| 一个人维护的小项目 | Issues + 标签就够，Projects 可选 | +| 多人协作、需要看进度 | Projects 的 Board 或 Table | +| 跨多个仓库排期 | 个人/组织的 Projects（不是在单个仓库里） | + +--- + +## 三、Discussions：问答与公告 + +Discussions 是一个「论坛式」的空间，适合**没有明确交付物**的讨论：使用问题、方案讨论、公告、展示。 + +### 3.1 开启（维护者） + +1. 仓库 → **Settings** → **General** → **Features**。 +2. 勾选 **Discussions**。 +3. 进入 **Discussions** 页签 → 分类（Categories）可以按 `Announcements` / `Q&A` / `Ideas` / `General` 调整。 + +### 3.2 网页发帖（完整流程） + +1. 仓库 → **Discussions** → **New discussion**。 +2. 选一个分类（例如 **Q&A**）。 +3. 填标题与正文，点 **Start discussion**。 +4. 回答者在回复里给出答案；提问者（或维护者）点 **Mark as answer**，该回复会被置顶标记。 +5. 讨论可以按分类、已解决/未解决筛选；也可以固定（Pin）公告。 + +### 3.3 Issue 还是 Discussion？ + +| 判断 | 用 Issue | 用 Discussion | +| --- | --- | --- | +| 有明确的可交付结果（修 bug、加功能） | ✅ | | +| 开放式问题、经验交流、投票 | | ✅ | +| 需要指派、里程碑、被 PR 关闭 | ✅ | | + +> 已经存在的 Issue 可以 **Convert to discussion**；讨论也能转回 Issue。 + +--- + +## 四、Wiki：仓库自带的轻量知识库 + +Wiki 适合放「和代码一起走、但不需要 review」的长文档：环境搭建、值班手册、会议记录。 + +### 4.1 开启与写第一页 + +1. 仓库 → **Settings** → **General** → **Features** → 勾选 **Wiki**。 +2. 回到仓库 → **Wiki** → **Create the first page**。 +3. 填标题与内容（Markdown），点 **Save Page**。 +4. 侧边栏可以加自定义导航：**Add a custom sidebar**。 + +### 4.2 本地编辑 Wiki + +每个 Wiki 本身也是一个 Git 仓库，页面上 **Clone this wiki locally** 会给出地址： + +```bash +git clone git@github.com:<用户名>/<仓库名>.wiki.git +``` + +改完 `push` 即可。适合批量修改或离线编辑。 + +> Wiki 与仓库里的 `docs/` 怎么选：需要 review、需要随版本发布、需要被 CI 校验 → 放 `docs/`； +> 随手维护、不需要 review → Wiki。 + +--- + +## 五、Notifications：别被消息淹没 + +### 5.1 三种关注方式 + +| 操作 | 效果 | +| --- | --- | +| **Watch** 仓库 | 订阅该仓库的动态（可设 Participating and @mentions / All activity / Ignore / Custom） | +| **@提及** | 被 `@` 的人会收到通知 | +| **Subscribe** 单个 Issue/PR | 只关注这一条（评论框下方 **Subscribe**） | + +### 5.2 收件箱 + +右上角铃铛 → ： + +- 左边栏按 **Inbox / Saved / Done** 过滤； +- 顶部可以按 `reason`（mention、review requested、assigned、subscribed）筛选； +- 每条通知可以 **Done**（归档）、**Unsubscribe**（退订）； +- 邮箱通知频率在 **Settings → Notifications** 里调整（建议关掉 "Watching" 的邮件，只留 mention / review）。 + +--- + +## 六、Search：找到那条 Issue 或 PR + +GitHub 顶部搜索框支持限定符，几个最常用的： + +| 限定符 | 例子 | 作用 | +| --- | --- | --- | +| `repo:` | `repo:cadywang/serial-debug-bridge` | 限定仓库 | +| `is:` | `is:issue` / `is:pr` / `is:open` | 类型与状态 | +| `label:` | `label:bug` | 按标签 | +| `author:` | `author:cadywang` | 按作者 | +| `assignee:` | `assignee:@me` | 指派给我 | +| `mentions:` | `mentions:cadywang` | 提到某人 | +| `in:` | `in:title` / `in:body` / `in:comments` | 搜索范围 | +| `language:` | `language:python` | 按语言（代码搜索） | + +代码搜索（仓库页搜索框或 ）还支持 `path:`、`symbol:` 等限定符。 +搜索需要索引，刚推送的代码可能延迟几秒到几分钟才出现。 + +--- + +## 七、小结 + +- **Issue** 记「要做的事」，带编号、可指派、可被 PR 关闭。 +- **Projects** 把 Issue/PR 排成看板或时间线，适合多人协作。 +- **Discussions** 放开放式问答与公告；**Wiki** 放不需要 review 的长文档。 +- 通知只留必要的：Watch 级别 + 邮箱设置，能省掉大量噪音。 +- 搜索用限定符，比翻页快得多。 + +> 下一篇：[Pull Request：从分支到合并](/2026/10/23/github-guide-03-pull-requests/) \ No newline at end of file From e8b59dcd290787f7459197b4eef9e9167734c3b2 Mon Sep 17 00:00:00 2001 From: cadywang <109458837+cadywang@users.noreply.github.com> Date: Fri, 23 Oct 2026 11:59:30 +0800 Subject: [PATCH 3/6] post: add the GitHub guide, part 3: pull requests Cover opening a PR from the web and the CLI, code review, the three merge methods and their effect on history, conflicts, and branch protection. Signed-off-by: cadywang <109458837+cadywang@users.noreply.github.com> --- .../_posts/github-guide-03-pull-requests.md | 235 ++++++++++++++++++ 1 file changed, 235 insertions(+) create mode 100644 source/_posts/github-guide-03-pull-requests.md diff --git a/source/_posts/github-guide-03-pull-requests.md b/source/_posts/github-guide-03-pull-requests.md new file mode 100644 index 0000000..d69bbbb --- /dev/null +++ b/source/_posts/github-guide-03-pull-requests.md @@ -0,0 +1,235 @@ +--- +title: GitHub 使用指南（三）：Pull Request——从分支到合并 +date: 2026-10-23 10:00:00 +tags: [GitHub, Pull Request, 代码审查, 分支, 新手入门] +categories: [教程] +description: 从开分支、发 PR、代码审查，到三种合并方式的取舍、冲突解决与分支保护——把团队协作的核心流程完整走一遍。 +--- + +前两篇讲的是「自己的代码怎么上去」和「事情记在哪」。真正让 GitHub 变成协作平台的，是 **Pull Request（PR）**： +你不再直接改主线，而是把一组改动放进分支，发起一个「请求合并」的提案，让别人看、让 CI 跑、最后再决定怎么合并。 + +PR 也是新手最容易紧张的地方：会不会把别人的代码弄坏？冲突了怎么办？Merge / Squash / Rebase 到底选哪个？ +这篇把整条链路拆开讲，每一步都给出网页和命令行两种做法。 + +> **GitHub 使用指南（6 篇）** +> 1. [入门：账号、仓库与第一次提交](/2026/10/23/github-guide-01-start/) +> 2. [Issues、Projects、Discussions 与 Wiki](/2026/10/23/github-guide-02-issues-projects/) +> 3. Pull Request：从分支到合并（本篇） +> 4. [Actions、Releases 与 Packages](/2026/10/23/github-guide-04-actions-releases/) +> 5. [安全、组织与 Pages](/2026/10/23/github-guide-05-security-org/) +> 6. [从 0 到 1 的完整演练与避坑清单](/2026/10/23/github-guide-06-practice-tips/) + +--- + +## 一、PR 到底在做什么 + +``` +main ──●──────────────●──────────────▶ + \ / +feature ●──●──●─┘ + 开分支 合入 +``` + +- **分支（branch）**：从 `main` 拉出来的一条独立时间线，改动不会影响主线。 +- **PR**：把「我的分支要合进 main」这件事变成一个可见、可讨论、可检查的对象。 +- 合并之后，分支上的提交进入 `main`；分支本身可以删除。 + +PR 页面通常有四个页签： + +| 页签 | 看什么 | +| --- | --- | +| **Conversation** | 描述、评论、审查意见、CI 状态、合并按钮 | +| **Commits** | 这个 PR 包含哪些提交 | +| **Checks** | CI 的每个 job 结果与日志 | +| **Files changed** | 逐文件的 diff，可以在这里写行内评论 | + +--- + +## 二、完整流程（网页 + 命令行） + +### 2.1 方式 A：命令行开分支、推送、发 PR（推荐） + +```bash +git switch main +git pull # 先追上最新 main +git switch -c feature/login-fix # 开分支 +# ……改代码…… +git add . +git commit -m "fix: handle empty token on the login page" +git push -u origin feature/login-fix +``` + +推送后终端会打印： + +``` +remote: Create a pull request for 'feature/login-fix' on GitHub by visiting: +remote: https://github.com/<用户名>/<仓库>/pull/new/feature/login-fix +``` + +打开这个链接，就进入「New pull request」表单。 + +### 2.2 方式 B：纯网页完成 + +1. 仓库 → **Code** → 分支选择器（`main ▾`）→ 输入新分支名 → **Create branch: xxx**。 +2. 在新分支上 **Add file / 编辑文件**，在提交对话框里选 + **Create a new branch for this commit and start a pull request**。 +3. 直接进入 PR 表单，或者去 **Pull requests → New pull request** 手动选 + **base: main** ← **compare: 你的分支**。 + +### 2.3 PR 表单怎么填 + +| 字段 | 建议 | +| --- | --- | +| **Title** | 一句话说清这次改动，例如 `fix: handle empty token on the login page` | +| **Description** | 背景、改了什么、怎么验证、风险点；很多仓库会自动带出 PR 模板 | +| **Reviewers** | 指定审查人（右侧栏） | +| **Assignees** | 谁负责推进 | +| **Labels / Projects / Milestone** | 分类与排期 | +| **Create pull request** | 直接创建；旁边的下拉可以选 **Create draft pull request** | + +**Draft PR（草稿）** 适合「先让大家看看方向」：不会触发「请求审查」，也不会被误合并； +准备好后点 **Ready for review**。 + +> PR 模板的作用：仓库里 `.github/pull_request_template.md` 会自动填进描述。 +> 成熟的仓库会把「跑过哪些测试、勾选哪些检查」做成清单，CI 甚至能强制校验（本博客仓库就是这样）。 + +--- + +## 三、代码审查（Code Review） + +### 3.1 在网页上审查 + +1. 打开 PR → **Files changed**。 +2. 鼠标移到某一行，点左边的 **+** 写行内评论： + - **Single comment**：单独一条评论； + - **Start a review**：先把多条意见攒起来，最后一起提交。 +3. 在评论框里可以直接改建议： + + ````markdown + ```suggestion + const token = value ?? ''; + ``` + ```` + + 作者点 **Commit suggestion** 就能采纳。 +4. 看完后点右上 **Review changes**： + - **Comment**：只评论，不表态； + - **Approve**：同意合并； + - **Request changes**：要求修改后才能合并（很多仓库把它设为必须）。 +5. 每条讨论解决后点 **Resolve conversation**；开了「要求讨论全部 resolve」的仓库，没解决就不能合并。 + +### 3.2 作者怎么响应 + +- 直接推新提交到同一个分支，PR 会自动更新（不需要重开）。 +- 改完后在评论里说明「已按建议修改」，并点 **Re-request review**。 +- 被要求修改时，不要 force-push 覆盖审查历史（除非仓库明确允许）；追加提交更利于对比。 + +> 小技巧：审查时用 **Viewed** 勾选已看过的文件；大 PR 建议拆小，一次看 20 个文件比看 200 个有效得多。 + +--- + +## 四、三种合并方式：Merge / Squash / Rebase + +PR 页面底部的绿色按钮可能是 **Merge pull request**、**Squash and merge** 或 **Rebase and merge**， +取决于仓库开启了哪些方式。它们的区别在历史形状： + +| 方式 | 历史长什么样 | 适合 | 代价 | +| --- | --- | --- | --- | +| **Create a merge commit** | 多一个 merge 提交，分支历史完整保留 | 想保留「什么时候合的、合了哪些提交」 | 历史是网状的，`git log` 较乱 | +| **Squash and merge** | 整个 PR 压成 **一个** 提交 | 分支上有很多「wip」「fix typo」的碎提交 | 原始提交与署名被合并，提交信息变成 PR 标题/描述 | +| **Rebase and merge** | 分支提交逐个重放到 main 上，**没有** merge 提交 | 要求线性历史、保留每个提交原文 | 提交 SHA 会被重写；提交信息必须一开始就写对 | + +> 本博客仓库与我的另外两个仓库都把规则设成 **只允许 Rebase and merge**。 +> 原因很实际：squash 会把 PR 压成一个提交，标题变成 PR 标题、`Signed-off-by:` 也不再是原文； +> 一旦标题不合规范，等发现时历史已经改不回来。 + +不管用哪种方式，合并后都可以点 **Delete branch** 删掉分支（很多仓库设为自动删除）。 + +--- + +## 五、冲突（conflict）：为什么会发生、怎么解 + +冲突发生在「同一个文件的同一区域被两边改了」。GitHub 会在 PR 页面提示 +**This branch has conflicts that must be resolved**。 + +### 5.1 本地解决（推荐） + +```bash +git switch feature/login-fix +git fetch origin +git rebase origin/main # 或 git merge origin/main +# 冲突文件里会出现 <<<<<<< ======= >>>>>>> 标记，手工改成最终内容 +git add <冲突文件> +git rebase --continue # merge 方式则直接 git commit +git push --force-with-lease +``` + +- `rebase` 让历史保持线性，但会重写提交；**推送时必须用 `--force-with-lease`**（比 `--force` 安全， + 别人在你之后推过东西时会拒绝）。 +- `merge` 不重写历史，会多一个合并提交；团队允许 merge commit 时更省事。 + +### 5.2 网页解决（只适合简单冲突） + +PR 页面点 **Resolve conflicts**，网页编辑器会显示冲突标记，改完点 **Mark as resolved** → **Commit merge**。 +文件多、冲突复杂时会提示只能用本地方式。 + +--- + +## 六、分支保护与 CODEOWNERS + +维护者可以在 **Settings → Branches**（经典保护）或 **Settings → Rules → Rulesets**（新版规则集）里限制 `main`： + +| 选项 | 作用 | +| --- | --- | +| **Require a pull request before merging** | 禁止直推，必须走 PR | +| **Require approvals** | 至少 N 人批准 | +| **Dismiss stale approvals** | 有新提交后旧批准作废 | +| **Require review from Code Owners** | 指定目录必须由 CODEOWNERS 里的人审查 | +| **Require status checks to pass** | CI 必须绿（可设「必须追上最新 main」） | +| **Require conversation resolution** | 所有讨论必须 resolve | +| **Require linear history** | 禁止 merge commit，逼你用 squash/rebase | +| **Block force pushes / deletions** | 防止改写历史、误删分支 | +| **Require signed commits** | 只接受 GPG/SSH 签名的提交 | + +**CODEOWNERS** 是一个放在 `.github/CODEOWNERS`（或根目录）的文件： + +``` +# 默认由谁负责 +* @cadywang + +# 特定目录 +/docs/ @cadywang +/agent/ @alice @bob +``` + +开启「Require review from Code Owners」后，改了对应路径就必须由 owner 批准。 + +> 单人维护时通常把批准数设为 0（GitHub 不允许自己批准自己的 PR）， +> 靠「PR + 必需检查 + 自己看一遍 diff」把关。 + +--- + +## 七、常见坑 + +| 现象 | 原因 | 处理 | +| --- | --- | --- | +| 推送被拒：`protected branch` / `GH006` | 直接推了 `main` | 开分支 → 发 PR | +| 推送被拒：`non-fast-forward` | 远端有你没有的提交 | `git pull --rebase` 后再推 | +| PR 里出现了别人的提交 | 分支基于旧 main，或从错误分支拉出 | `git rebase origin/main`；确认 base 分支 | +| 合并后提交作者变了 | 用了 squash | 改用 rebase，或接受这是 squash 的语义 | +| `git push --force` 把同事的提交冲掉 | 强推覆盖 | 用 `--force-with-lease`，并先 `git fetch` | +| PR 太大没人看 | 一次改太多 | 拆成多个小 PR，一个 PR 一件事 | +| 合并后 CI 红了 | 本地没跑检查 | 合并前看 Checks；本地先跑同样的命令 | + +--- + +## 八、小结 + +- PR = 分支 + 提案 + 审查 + CI，是 GitHub 协作的核心。 +- 流程：`开分支 → 提交 → 推送 → 开 PR → 审查/CI → 合并 → 删分支`。 +- 合并方式要跟团队规则一致：保留原始提交用 **rebase**，想要一个干净提交用 **squash**。 +- 冲突优先在本地解决；推送被拒先 `pull --rebase`。 +- 分支保护不是限制，是「让错误在合并前暴露」的机制。 + +> 下一篇：[Actions、Releases 与 Packages](/2026/10/23/github-guide-04-actions-releases/) \ No newline at end of file From a428c7ece8035eec5a62c920927d281fce1b74c0 Mon Sep 17 00:00:00 2001 From: cadywang <109458837+cadywang@users.noreply.github.com> Date: Fri, 23 Oct 2026 11:59:30 +0800 Subject: [PATCH 4/6] post: add the GitHub guide, part 4: actions and releases Cover the five Actions concepts, a minimal workflow, triggers, matrix, cache, artifacts, secrets and environments, then Releases, tags and Packages. Signed-off-by: cadywang <109458837+cadywang@users.noreply.github.com> --- .../github-guide-04-actions-releases.md | 301 ++++++++++++++++++ 1 file changed, 301 insertions(+) create mode 100644 source/_posts/github-guide-04-actions-releases.md diff --git a/source/_posts/github-guide-04-actions-releases.md b/source/_posts/github-guide-04-actions-releases.md new file mode 100644 index 0000000..beb606e --- /dev/null +++ b/source/_posts/github-guide-04-actions-releases.md @@ -0,0 +1,301 @@ +--- +title: GitHub 使用指南（四）：Actions、Releases 与 Packages +date: 2026-10-23 10:30:00 +tags: [GitHub, GitHub Actions, CI/CD, Release, 自动化] +categories: [教程] +description: 从 workflow 的五个概念、第一个 CI 配置，到运行日志、矩阵构建、密钥管理，再到 Release 发版与 Packages 发包。 +--- + +前三篇讲的是「代码怎么协作」。这一篇讲 GitHub 的自动化与发布：**让机器替你跑测试、构建、发版。** + +很多新手对 Actions 的印象是「一堆 yaml」，其实只要抓住五个概念，剩下的都是查文档。 +本篇用本博客仓库里真实在跑的配置举例，每一步都能在网页上对应到具体按钮。 + +> **GitHub 使用指南（6 篇）** +> 1. [入门：账号、仓库与第一次提交](/2026/10/23/github-guide-01-start/) +> 2. [Issues、Projects、Discussions 与 Wiki](/2026/10/23/github-guide-02-issues-projects/) +> 3. [Pull Request：从分支到合并](/2026/10/23/github-guide-03-pull-requests/) +> 4. Actions、Releases 与 Packages（本篇） +> 5. [安全、组织与 Pages](/2026/10/23/github-guide-05-security-org/) +> 6. [从 0 到 1 的完整演练与避坑清单](/2026/10/23/github-guide-06-practice-tips/) + +--- + +## 一、五个概念先认清 + +| 概念 | 是什么 | 例子 | +| --- | --- | --- | +| **Workflow（工作流）** | 一个 YAML 文件，定义「什么时候、做什么」 | `.github/workflows/ci.yml` | +| **Event（事件）** | 触发条件 | `push`、`pull_request`、`workflow_dispatch`、`schedule` | +| **Job（任务）** | 一组在同一个 runner 上顺序执行的步骤 | `hygiene`、`build-check` | +| **Step（步骤）** | job 里的一步，跑命令或调用 Action | `run: python3 tools/check-skills.py` | +| **Runner（运行器）** | 真正执行 job 的机器 | `ubuntu-latest`、`windows-latest`、自托管 runner | + +Action（可复用动作）是别人写好的「步骤包」，比如 `actions/checkout@v4`（把代码拉下来）。 +**Workflow 由 job 组成，job 由 step 组成，step 可以是命令，也可以是 Action。** + +--- + +## 二、第一个 workflow + +在仓库里新建 `.github/workflows/ci.yml`： + +```yaml +name: CI + +on: + push: + branches: [main] + pull_request: + branches: [main] + workflow_dispatch: + +permissions: + contents: read + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.11' + - name: Run tests + run: python3 -m pytest -q +``` + +逐段解释： + +| 片段 | 作用 | +| --- | --- | +| `name` | 显示在 Actions 页面上的名字 | +| `on` | 触发事件；`workflow_dispatch` 让页面出现 **Run workflow** 按钮 | +| `permissions` | 收紧 `GITHUB_TOKEN` 的权限（默认尽量只读） | +| `jobs.` | job 的 ID，可以起多个，默认并行 | +| `needs:` | 让 job 有依赖（B 等 A 成功后再跑） | +| `runs-on` | 用哪种 runner | +| `steps` | 顺序执行的步骤；`uses` 调 Action，`run` 跑命令 | + +> **本博客仓库的 `review-gate.yml` 就是活例子**：`hygiene` 检查编码/行尾/语法与 commit 规范， +> `validate-posts` 校验文章格式，`build-check` 跑 `hexo generate`。三个 job 并行，PR 必须全绿。 + +--- + +## 三、网页上怎么用（完整流程） + +### 3.1 新建 / 修改 workflow + +1. 仓库 → **Actions** 页签。 +2. 第一次进入会看到 **Get started with GitHub Actions**，可以选一个模板； + 也可以直接 **New workflow → set up a workflow yourself**。 +3. 进入网页编辑器，改 `.github/workflows/<名字>.yml`。 +4. 右上 **Commit changes**： + - 直接提交到 `main`，或； + - **Create a new branch and start a pull request**（推荐：CI 的改动也应该被 review）。 + +### 3.2 看一次运行 + +1. **Actions** → 左侧选 workflow → 点某一次运行。 +2. **Summary** 页显示每个 job 的结果；点 job 看每一步的日志。 +3. 右上 **Re-run all jobs** / **Re-run failed jobs** 可以重跑。 +4. job 里上传的 **Artifacts** 可以在 Summary 底部下载（保留期有限）。 + +### 3.3 手动触发 + +配置了 `on: workflow_dispatch` 的 workflow，Actions 页面会出现 **Run workflow** 按钮： +选分支、填 inputs，点运行。**这是发布类 workflow 的常用入口**——手动确认一次才执行。 + +### 3.4 在 PR 上看 CI + +PR 页面底部会显示检查状态：绿色 ✅ / 红色 ❌ / 黄色 🟡。 +点 **Details** 跳到对应 job 日志；分支保护里可以把这些检查设为**必需**，红了就不能合并。 + +--- + +## 四、常用能力 + +### 4.1 矩阵（matrix）：一份配置跑多环境 + +```yaml +jobs: + test: + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, windows-latest] + python: ['3.10', '3.11'] + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python }} + - run: python3 --version +``` + +矩阵会展开成 4 个 job，互不影响。 + +### 4.2 缓存与产物 + +```yaml + - uses: actions/cache@v4 + with: + path: ~/.cache/pip + key: pip-${{ hashFiles('requirements.txt') }} + + - uses: actions/upload-artifact@v4 + with: + name: site + path: public/ +``` + +- **cache**：加速依赖下载；key 一般带依赖文件的哈希。 +- **artifact**：把构建产物保存下来，供下载或给后续 job 用（`actions/download-artifact`）。 + +### 4.3 密钥（Secrets） + +CI 里需要 token、密码时，**不要写进 YAML**： + +1. 仓库 → **Settings** → **Secrets and variables** → **Actions**。 +2. **New repository secret**，填名字（例如 `NPM_TOKEN`）和值。 +3. workflow 里用 `${{ secrets.NPM_TOKEN }}` 引用。 + +组织级密钥在组织 Settings 里配；需要审批的发布可以用 **Environments**： + +1. **Settings → Environments → New environment**，例如 `production`。 +2. 配置 **Required reviewers**（部署前必须有人批准）和 **Deployment branches**。 +3. job 里写 `environment: production`，就会走这套审批。 + +> 安全习惯：密钥只在 job 需要它的那一步用；优先用 `GITHUB_TOKEN`（自动生成、作用域受限）， +> 少用长期 PAT。 + +### 4.4 权限与并发 + +```yaml +permissions: + contents: read + pull-requests: write + +concurrency: + group: ci-${{ github.ref }} + cancel-in-progress: true +``` + +- 默认 `GITHUB_TOKEN` 权限越收紧越好，需要写 PR 评论时再单独给 `pull-requests: write`。 +- `concurrency` 能取消同一分支上过期的运行，省额度也更快出结果。 + +--- + +## 五、Marketplace：不要重复造轮子 + + 里有大量现成 Action： +部署 Pages、发 Release、上传 Docker 镜像、跑 lint、发通知…… + +用法就是 `uses: owner/action@v版本`。选 Action 时看三点： + +1. 是否官方（`actions/...`）或知名维护者； +2. 最近是否还在维护； +3. 需要什么权限、会接触哪些密钥。 + +> 固定版本（`@v4` 或 commit SHA）比 `@main` 稳；对安全敏感的仓库建议固定到 commit SHA。 + +--- + +## 六、Releases：给版本留一份说明 + +Tag 是 Git 的「版本指针」，Release 是 GitHub 在 tag 之上加的一层「发布说明 + 附件」。 + +### 6.1 网页发版（完整流程） + +1. 仓库 → **Code** → 右侧 **Releases** → **Draft a new release**。 +2. **Choose a tag**： + - 已有 tag 直接选； + - 或输入新的版本号（例如 `v1.2.0`）→ **Create new tag on publish**。 +3. **Release title**：例如 `v1.2.0`。 +4. **Describe this release**：写变更说明；可以点 **Generate release notes** 让 GitHub 自动汇总 PR。 +5. 需要的话上传附件（编译好的二进制、压缩包）。 +6. 勾选 **Set as the latest release**，点 **Publish release**。 + +### 6.2 命令行发版 + +```bash +git tag -a v1.2.0 -m "v1.2.0" +git push origin v1.2.0 +``` + +推送 tag 也能触发以 `on: push: tags:` 配置的 workflow（常见于「打 tag 即发布」）。 + +### 6.3 版本号怎么定 + +语义化版本 `MAJOR.MINOR.PATCH`： + +| 变化 | 版本 | +| --- | --- | +| 不兼容的 API 改动 | `MAJOR` +1 | +| 向下兼容的新功能 | `MINOR` +1 | +| 向下兼容的修复 | `PATCH` +1 | + +--- + +## 七、Packages：把「库」也发布出去 + +GitHub Packages 可以托管 npm、Maven、NuGet、RubyGems、Docker 容器等（容器在 `ghcr.io`）。 + +### 7.1 用 Actions 发布（以容器为例） + +```yaml +jobs: + publish: + runs-on: ubuntu-latest + permissions: + contents: read + packages: write + steps: + - uses: actions/checkout@v4 + - uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + - uses: docker/build-push-action@v6 + with: + push: true + tags: ghcr.io/${{ github.repository }}:latest +``` + +发布后的包会出现在个人/组织的 **Packages** 页面，可以设置可见性与关联仓库。 + +### 7.2 什么时候值得用 + +| 场景 | 建议 | +| --- | --- | +| 公司内部共享 Python/npm 包 | 可以用，但先确认团队是否已有私有 registry | +| 开源项目发布 npm 包 | 更常见的是直接发到 npmjs，GitHub Packages 作为备选 | +| 发布 Docker 镜像 | `ghcr.io` 很方便，且与 Actions 集成好 | + +--- + +## 八、排障速查 + +| 现象 | 可能原因 | 处理 | +| --- | --- | --- | +| workflow 不触发 | `on` 的分支/事件不匹配；YAML 缩进错误 | Actions 页面看是否根本没有 run；本地用 YAML 解析器校验 | +| job 一直 queued | runner 不可用、并发限制、组织账单 | 看 job 详情；检查 Actions 设置与额度 | +| `permission denied` | `GITHUB_TOKEN` 权限不够 | 在 workflow 里加 `permissions:`，或改用合适的 secret | +| 拉不到私有仓库 | `actions/checkout` 需要 token | `with: token: ${{ secrets.PAT }}`（谨慎使用长期 PAT） | +| 缓存不生效 | key 每次都变 | key 里用 `hashFiles(...)`，不要带时间戳 | +| 手动运行按钮不见了 | 没有 `workflow_dispatch` | 在 `on:` 里加上它 | +| 想本地复现 | 环境差异 | 用与本机一致的版本；或考虑 `act`（第三方工具，非官方） | + +--- + +## 九、小结 + +- Actions = workflow（YAML）+ event（触发）+ job + step + runner。 +- 先写最小 CI（checkout → 装环境 → 跑测试），再加矩阵、缓存、产物。 +- 密钥放 Secrets，发布走 Environment 审批；`GITHUB_TOKEN` 权限默认收紧。 +- Release = tag + 发布说明 + 附件；版本号用语义化版本。 +- Packages 适合发布容器/库，容器用 `ghcr.io` 最顺。 + +> 下一篇：[安全、组织与 Pages](/2026/10/23/github-guide-05-security-org/) \ No newline at end of file From ea09fea7a4d1f54aad6b5209c4f7d81dcfa54553 Mon Sep 17 00:00:00 2001 From: cadywang <109458837+cadywang@users.noreply.github.com> Date: Fri, 23 Oct 2026 11:59:30 +0800 Subject: [PATCH 5/6] post: add the GitHub guide, part 5: security and pages Cover repository roles and organizations, credential hygiene, Dependabot and code scanning, security advisories, GitHub Pages, Insights and the smaller modules. Signed-off-by: cadywang <109458837+cadywang@users.noreply.github.com> --- source/_posts/github-guide-05-security-org.md | 227 ++++++++++++++++++ 1 file changed, 227 insertions(+) create mode 100644 source/_posts/github-guide-05-security-org.md diff --git a/source/_posts/github-guide-05-security-org.md b/source/_posts/github-guide-05-security-org.md new file mode 100644 index 0000000..1c69570 --- /dev/null +++ b/source/_posts/github-guide-05-security-org.md @@ -0,0 +1,227 @@ +--- +title: GitHub 使用指南（五）：安全、组织与 Pages +date: 2026-10-23 11:00:00 +tags: [GitHub, 安全, 组织, GitHub Pages, 权限] +categories: [教程] +description: 仓库角色与组织权限、2FA/SSH/PAT/签名、依赖与代码安全、组织与团队管理、Pages 发布网站，以及 Insights、Gist、Codespaces 等模块。 +--- + +前四篇讲的是「怎么用」。这一篇讲「怎么用得安全、怎么在团队里管」： +权限模型、账号安全、依赖漏洞、组织与团队、以及用 GitHub Pages 把仓库变成网站。 + +这些模块平时存在感不高，但一旦出问题（token 泄露、误删仓库、依赖被投毒）代价很大。 +建议按顺序把「账号安全」和「仓库安全」两节配置一遍。 + +> **GitHub 使用指南（6 篇）** +> 1. [入门：账号、仓库与第一次提交](/2026/10/23/github-guide-01-start/) +> 2. [Issues、Projects、Discussions 与 Wiki](/2026/10/23/github-guide-02-issues-projects/) +> 3. [Pull Request：从分支到合并](/2026/10/23/github-guide-03-pull-requests/) +> 4. [Actions、Releases 与 Packages](/2026/10/23/github-guide-04-actions-releases/) +> 5. 安全、组织与 Pages（本篇） +> 6. [从 0 到 1 的完整演练与避坑清单](/2026/10/23/github-guide-06-practice-tips/) + +--- + +## 一、权限模型：先搞清楚「谁能做什么」 + +### 1.1 账号类型 + +| 类型 | 适合 | 说明 | +| --- | --- | --- | +| **Personal account** | 个人 | 个人仓库、Gist、Stars、Packages 都挂在它下面 | +| **Organization** | 团队/公司 | 仓库归组织所有，成员按团队授权；可以开审计日志、SSO | +| **Enterprise** | 大型组织 | 多组织管理、企业级策略 | + +个人仓库可以**转移**到组织（Settings → General → Danger Zone → Transfer），转移后权限由组织统一管理。 + +### 1.2 仓库角色（Collaborator 权限） + +邀请某人进仓库时（Settings → Collaborators），要选权限级别： + +| 角色 | 能做什么 | +| --- | --- | +| **Read** | 看代码、开 Issue、看 PR | +| **Triage** | 管理 Issue/PR（打标签、指派、关闭），但不能改代码 | +| **Write** | 推代码、合并 PR、发 Release | +| **Maintain** | 管理仓库设置（不含删除/转移等危险操作） | +| **Admin** | 全部权限，包括删除仓库、改保护规则 | + +> 最小权限原则：只读的人别给 Write；CI 机器人用细粒度 token，别用个人管理员账号。 + +### 1.3 组织与团队 + +| 概念 | 说明 | 网页位置 | +| --- | --- | --- | +| **People** | 组织成员 | 组织页 → People | +| **Teams** | 成员分组，按组授权 | 组织页 → Teams → New team | +| **Base permissions** | 成员对组织仓库的默认权限 | 组织 Settings → Member privileges | +| **Repository roles** | 自定义角色（Enterprise） | 组织 Settings → Repository roles | +| **Audit log** | 谁在什么时候改了什么 | 组织 Settings → Audit log | +| **SSO** | 强制通过公司身份登录 | 组织 Settings → Authentication security | + +团队授权示例：`@cadywang/backend` 这个 team 对某仓库给 Write，团队里加人即自动获得权限。 + +--- + +## 二、账号安全：四件事 + +### 2.1 两步验证（2FA） + +头像 → **Settings** → **Password and authentication** → **Enable two-factor authentication**。 +推荐 TOTP（验证器 App）+ 保存恢复码。组织可以强制成员开启 2FA。 + +### 2.2 SSH 密钥 + +见第 1 篇：`ssh-keygen -t ed25519` → **Settings → SSH and GPG keys → New SSH key** → `ssh -T git@github.com` 验证。 +一个账号可以加多把密钥（每台机器一把），丢了就单独撤销，不要所有机器共用一个。 + +### 2.3 Personal Access Token（PAT） + +| 类型 | 特点 | 什么时候用 | +| --- | --- | --- | +| **Fine-grained** | 可限定到具体仓库 + 具体权限，有有效期 | 首选 | +| **Classic** | 按 scope 授权（`repo`、`workflow` 等），范围较粗 | 老工具只支持 classic 时 | + +网页位置：**Settings → Developer settings → Personal access tokens**。 +生成后只显示一次；用完及时撤销，定期轮换。**不要把 token 写进仓库、日志、截图。** + +### 2.4 提交签名（可选但推荐） + +要求「提交必须签名」时，需要 GPG 或 SSH 签名： + +```bash +# 用现有 SSH 密钥做签名（Git 2.34+） +git config --global gpg.format ssh +git config --global user.signingkey ~/.ssh/id_ed25519.pub +git config --global commit.gpgsign true +``` + +然后把公钥以 **Signing Key** 类型加到 **Settings → SSH and GPG keys**。 +开启分支保护的 **Require signed commits** 后，未签名的提交无法合并。 + +--- + +## 三、仓库安全：依赖、代码与密钥 + +### 3.1 开启安全功能（网页） + +仓库 → **Settings** → **Code security**（不同版本可能叫 Code security and analysis）： + +| 功能 | 作用 | +| --- | --- | +| **Dependency graph** | 识别依赖与版本 | +| **Dependabot alerts** | 依赖有已知漏洞时告警 | +| **Dependabot security updates** | 自动开 PR 升级有漏洞的依赖 | +| **Code scanning** | 用 CodeQL 等工具扫代码漏洞 | +| **Secret scanning** | 检测提交里的密钥/token（公开仓库默认开启） | +| **Private vulnerability reporting** | 让研究者私下报告漏洞 | + +### 3.2 Dependabot 版本更新 + +在 `.github/dependabot.yml` 里声明要更新的生态： + +```yaml +version: 2 +updates: + - package-ecosystem: "npm" + directory: "/" + schedule: + interval: "weekly" + open-pull-requests-limit: 5 + commit-message: + prefix: "build" + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + commit-message: + prefix: "ci" +``` + +Dependabot 会按配置开 PR；**bot 生成的 PR 在 commit 规范门禁里通常需要豁免**， +否则它的 `build: bump ...` 会被判成不合规（本博客与另外两个仓库都做了这个豁免）。 + +### 3.3 安全公告（Security advisories） + +仓库 → **Security** → **Advisories** → **New draft security advisory**： +填受影响版本、描述、修复版本，发布后会生成安全公告，也可以申请 CVE。 +适合「漏洞已经修好、需要通知用户」的场景。 + +### 3.4 发现密钥泄露怎么办 + +1. **立刻撤销**那个 token/密码（GitHub 的 PAT、云厂商的 key）； +2. 从代码里删除，并用环境变量/Secrets 替代； +3. 如果已经推到公开仓库，**改写历史不能挽回**（已被抓取），撤销才是关键； +4. 开启 secret scanning 的 **Push protection**，在推送阶段就拦截。 + +--- + +## 四、GitHub Pages：把仓库变成网站 + +### 4.1 两种发布方式 + +| 方式 | 适合 | 做法 | +| --- | --- | --- | +| **Deploy from a branch** | 纯静态文件 | Settings → Pages → Source 选分支与目录（`/` 或 `/docs`） | +| **GitHub Actions** | 需要构建（Hexo、Vue、Jekyll 等） | Source 选 **GitHub Actions**，用官方 Pages workflow 构建并部署 | + +### 4.2 网页配置（完整流程） + +1. 仓库 → **Settings** → **Pages**。 +2. **Build and deployment → Source**： + - 选 **Deploy from a branch** → 选分支（例如 `gh-pages` 或 `main`）与目录 → **Save**； + - 或选 **GitHub Actions**，然后到 Actions 页面选一个 Pages 模板。 +3. 等一次构建完成，页面顶部会出现站点地址：`https://<用户名>.github.io/<仓库名>/`。 +4. 自定义域名：**Custom domain** 填域名 → **Save**，到 DNS 配 CNAME；勾选 **Enforce HTTPS**。 + +### 4.3 常见问题 + +| 现象 | 原因 | 处理 | +| --- | --- | --- | +| 404 | 发布目录选错、构建还没跑完 | 看 Actions 是否成功；确认目录里有 `index.html` | +| 样式丢失 | 站点部署在子路径，资源用了绝对路径 | 配置 `baseurl` / `publicPath` | +| 自定义域名失效 | DNS 没生效、CNAME 文件被删 | 等 DNS；在仓库里保留 `CNAME` 文件 | +| HTTPS 不可选 | 证书还在签发 / DNS 未验证 | 等几分钟；确认域名解析正确 | + +--- + +## 五、Insights 与其他模块 + +### 5.1 Insights + +仓库 → **Insights**： + +- **Pulse**：近期活跃度； +- **Contributors**：谁贡献了多少提交； +- **Traffic**：访问量、克隆数（需要权限）； +- **Commits / Code frequency**：提交节奏； +- **Dependency graph**：依赖图（安全功能的基础）。 + +### 5.2 Gist + +：分享单文件或代码片段，有 Secret（不公开列出）与 Public 两种。 +适合贴一条命令、一个配置示例；不适合放整个项目。 + +### 5.3 Codespaces / Copilot / Sponsors / Education + +| 模块 | 一句话 | 入口 | +| --- | --- | --- | +| **Codespaces** | 浏览器里的云端开发环境（VS Code 内核），按小时计费/额度 | 绿色 Code → Codespaces | +| **Copilot** | AI 编码助手（需订阅/组织开通） | 个人 Settings → Copilot | +| **Sponsors** | 赞助开源作者 / 接受赞助 | 用户主页 Sponsor 按钮 | +| **Education** | 学生/教师免费 Copilot、Pro 等权益 | | +| **Marketplace** | Actions、Apps、主题 | | + +> 这些模块不影响日常协作，先把前四篇的主流程用熟，再按需开启。 + +--- + +## 六、小结 + +- 权限按最小化给：Read / Triage / Write / Maintain / Admin，组织用 Team 授权。 +- 账号安全四件套：2FA、SSH、PAT（细粒度）、可选签名。 +- 仓库安全：Dependabot + Code scanning + Secret scanning，密钥泄露先撤销再谈清理。 +- Pages 两种发布方式：分支直出 vs Actions 构建；自定义域名记得配 DNS 与 HTTPS。 +- Insights / Gist / Codespaces / Copilot 按需使用，别为了「全开」而全开。 + +> 下一篇：[从 0 到 1 的完整演练与避坑清单](/2026/10/23/github-guide-06-practice-tips/) \ No newline at end of file From 526ac58b9dfe2d51d36e5dd351460058049c0f52 Mon Sep 17 00:00:00 2001 From: cadywang <109458837+cadywang@users.noreply.github.com> Date: Fri, 23 Oct 2026 11:59:30 +0800 Subject: [PATCH 6/6] post: add the GitHub guide, part 6: practice and pitfalls Walk from an empty repository to a published site, list the ten mistakes beginners hit first, and finish with a cheat sheet. Signed-off-by: cadywang <109458837+cadywang@users.noreply.github.com> --- .../_posts/github-guide-06-practice-tips.md | 246 ++++++++++++++++++ 1 file changed, 246 insertions(+) create mode 100644 source/_posts/github-guide-06-practice-tips.md diff --git a/source/_posts/github-guide-06-practice-tips.md b/source/_posts/github-guide-06-practice-tips.md new file mode 100644 index 0000000..a9cb384 --- /dev/null +++ b/source/_posts/github-guide-06-practice-tips.md @@ -0,0 +1,246 @@ +--- +title: GitHub 使用指南（六）：从 0 到 1 的完整演练与避坑清单 +date: 2026-10-23 11:30:00 +tags: [GitHub, 工作流, 新手入门, 避坑, 教程] +categories: [教程] +description: 把前五篇串成一次完整演练：建仓、克隆、开分支、发 PR、等 CI、合并、发版、发布 Pages；再给出新手最常踩的坑与速查表。 +--- + +前五篇按模块拆开讲，这一篇把它们串起来：**假设你从零开始，要在一天内完成「建仓库 → 改代码 → 发 PR → 合并 → 发版 → 上线」的全过程。** +每一步都给出网页与命令行两种做法，最后是新手最容易踩的坑和一张速查表。 + +> **GitHub 使用指南（6 篇）** +> 1. [入门：账号、仓库与第一次提交](/2026/10/23/github-guide-01-start/) +> 2. [Issues、Projects、Discussions 与 Wiki](/2026/10/23/github-guide-02-issues-projects/) +> 3. [Pull Request：从分支到合并](/2026/10/23/github-guide-03-pull-requests/) +> 4. [Actions、Releases 与 Packages](/2026/10/23/github-guide-04-actions-releases/) +> 5. [安全、组织与 Pages](/2026/10/23/github-guide-05-security-org/) +> 6. 从 0 到 1 的完整演练与避坑清单（本篇） + +--- + +## 一、完整演练：从空目录到上线 + +### 第 1 步：建仓库（网页） + +1. 右上 **+** → **New repository**。 +2. 名称 `demo-site`，选 **Public**。 +3. 勾选 **Add a README file**、**Add .gitignore (Node)**、**Choose a license (MIT)**。 +4. **Create repository**。 + +### 第 2 步：配好 SSH 并克隆 + +```bash +ssh -T git@github.com # 第一次要先配公钥，见第 1 篇 +git clone git@github.com:<用户名>/demo-site.git +cd demo-site +git config user.name "你的名字" +git config user.email "你的邮箱@example.com" +``` + +> 只改这个仓库的身份，不加 `--global`，避免影响你其它项目的提交署名。 + +### 第 3 步：开分支，做一次小改动 + +```bash +git switch -c docs/quick-start +cat > QUICKSTART.md <<'EOF' +# Quick start + +1. `npm ci` +2. `npm run build` +EOF +git status +git add QUICKSTART.md +git commit -s -m "docs: add quick start" +git push -u origin docs/quick-start +``` + +推送后终端会打印 `pull/new/docs/quick-start` 链接。 + +### 第 4 步：开 PR（网页） + +1. 打开终端里的链接（或 **Pull requests → New pull request**）。 +2. 确认 **base: main** ← **compare: docs/quick-start**。 +3. 填标题 `docs: add quick start`，描述里写清「改了什么、为什么、怎么验证」。 +4. 点 **Create pull request**。 + +### 第 5 步：等 CI、看结果 + +1. PR 页面底部出现检查列表；点 **Details** 看日志。 +2. 红了就本地修、再 `git commit` + `git push`（PR 会自动更新）。 +3. 全部绿了之后，按仓库规则合并：**Merge pull request** / **Squash and merge** / **Rebase and merge**。 + +### 第 6 步：发版 + +1. **Code → Releases → Draft a new release**。 +2. 新 tag 填 `v0.1.0`，标题 `v0.1.0`。 +3. **Generate release notes** 自动汇总 PR。 +4. **Publish release**。 + +### 第 7 步：发布 Pages（如果这是一个站点） + +1. **Settings → Pages → Source** 选 **GitHub Actions**，按提示加一个 Pages workflow。 +2. 或选 **Deploy from a branch**，指向构建产物所在分支/目录。 +3. 等 Actions 跑完，访问 `https://<用户名>.github.io/demo-site/`。 + +--- + +## 二、纯网页版流程（不装 Git 也能完成） + +1. **建仓**：+ → New repository → 勾 README。 +2. **建分支**：Code → 分支选择器 → 输入 `docs/quick-start` → **Create branch**。 +3. **改文件**：Add file → Create new file → 写完 → **Commit changes**，选 + **Create a new branch for this commit and start a pull request**。 +4. **开 PR**：填标题/描述 → **Create pull request**。 +5. **等 CI**：看底部检查；红了就点文件 → 铅笔改 → 提交到同一分支。 +6. **合并**：绿色按钮 → 确认 → **Delete branch**。 +7. **发版 / Pages**：同上面的第 6、7 步。 + +> 网页版适合文档和小改动；一旦涉及多文件重构、跑测试、解冲突，还是回本地用命令行。 + +--- + +## 三、新手最容易踩的 10 个坑 + +| # | 现象 | 原因 | 正确做法 | +| --- | --- | --- | --- | +| 1 | `fatal: not a git repository` | 不在仓库目录里 | `cd` 到仓库根目录；用 `git rev-parse --show-toplevel` 确认 | +| 2 | 提交后 GitHub 上没有 | 只 `commit` 没 `push` | `git push`；确认分支名与远端一致 | +| 3 | `detached HEAD` | `git checkout ` 而不是分支 | `git switch -c 新分支` 把当前状态接住；或 `git switch main` | +| 4 | 推送被拒（protected branch） | 直接推了 `main` | 开分支 + PR | +| 5 | 推送被拒（non-fast-forward） | 远端有你的本地没有的提交 | `git pull --rebase` 后重推 | +| 6 | 把密码/token 提交了 | 写进了文件或 curl 命令 | 立刻撤销 token；改用环境变量/Secrets；开 push protection | +| 7 | 大文件推不上去 | 超过 GitHub 单文件限制（100 MB 硬限制） | 用 Git LFS：`git lfs install && git lfs track "*.psd"`，或不要把构建产物提交 | +| 8 | Windows 上换行符全变了 | CRLF/LF 混用 | 加 `.gitattributes`：`* text eol=lf`；必要时 `git add --renormalize .` | +| 9 | squash 合并后作者/署名变了 | squash 用一个新提交替代整条分支 | 需要保留原始提交就用 **Rebase and merge** | +| 10 | PR 巨大、没人愿意看 | 一次改太多 | 一个 PR 一件事；重构与功能分开 | + +补充两个高频问题： + +- **`.gitignore` 不生效**：已经被跟踪的文件不会因为加入 `.gitignore` 自动消失， + 需要 `git rm --cached <文件>` 再提交。 +- **误删分支**：如果提交还没被合并，先 `git reflog` 找到 SHA，再 `git switch -c 恢复 `。 + +--- + +## 四、工具：除了网页和 Git 命令行 + +### 4.1 GitHub CLI（`gh`） + +```bash +# 安装后登录一次（浏览器授权） +gh auth login + +# 建仓库并推送 +gh repo create demo-cli --public --source=. --push + +# 发 PR、看检查、合并 +gh pr create --title "docs: add quick start" --body "…" +gh pr checks --watch +gh pr merge --rebase --delete-branch + +# 看 Actions +gh run list +gh run watch +``` + +> `gh` 适合脚本化：把「开 PR → 等 CI → 合并」写成一条流水线，比点网页快。 + +### 4.2 GitHub Desktop + +图形界面，适合不熟命令行的同学：克隆、切换分支、提交、推送、开 PR 都有按钮。 +复杂冲突还是建议命令行或编辑器（VS Code 的 Git 面板也够用）。 + +### 4.3 REST API / GraphQL / Webhooks + +- **REST API**：`https://api.github.com`，用 token 认证； +- **GraphQL**：一次请求取多个对象，适合做仪表盘； +- **Webhook**：仓库 Settings → Webhooks，事件发生时 POST 到你自己的服务，适合做通知/自动化。 + +```bash +curl -s -H "Authorization: Bearer $GITHUB_TOKEN" \ + https://api.github.com/repos/<用户名>/<仓库>/pulls?state=open +``` + +> 用 API 时同样要最小权限；token 只放在环境变量里，不要写进脚本再提交。 + +### 4.4 Codespaces + +仓库 → 绿色 **Code** → **Codespaces** → **Create codespace on main**： +在浏览器里得到一个预装好依赖的 VS Code，改完直接提交/开 PR。 +适合「换机器、不想配环境」的场景；注意免费额度与自动停止时间。 + +--- + +## 五、速查表 + +### 5.1 命令 + +| 目的 | 命令 | +| --- | --- | +| 看状态 | `git status` | +| 看差异 | `git diff` / `git diff --staged` | +| 开分支 | `git switch -c ` | +| 切分支 | `git switch ` | +| 拉取并变基 | `git pull --rebase` | +| 提交（带署名） | `git commit -s -m "scope: summary"` | +| 推送新分支 | `git push -u origin ` | +| 安全强推 | `git push --force-with-lease` | +| 看历史 | `git log --oneline --graph --decorate -20` | +| 撤销未提交改动 | `git restore ` | +| 撤销最近一次提交（保留改动） | `git reset --soft HEAD~1` | +| 找回误删分支 | `git reflog` → `git switch -c ` | + +### 5.2 网页入口 + +| 想做什么 | 路径 | +| --- | --- | +| 建仓库 | 右上 **+** → New repository | +| 改文件 | 仓库 → 文件 → 铅笔 / Add file | +| 开 PR | Pull requests → New pull request | +| 看 CI | Actions / PR 底部 Checks | +| 发版 | Code → Releases → Draft a new release | +| 配 Pages | Settings → Pages | +| 配密钥 | Settings → Secrets and variables → Actions | +| 配分支保护 | Settings → Branches / Rules | +| 配安全扫描 | Settings → Code security | +| 组织管理 | 组织页 → People / Teams / Settings | + +### 5.3 一套「不会出错」的日常流程 + +``` +1. git switch main && git pull +2. git switch -c / +3. 改代码 + 本地跑测试 +4. git add -p（只暂存想提交的部分） +5. git commit -s -m ": " +6. git push -u origin +7. 开 PR，写清背景/改动/验证 +8. 等 CI 绿、处理 review +9. 按仓库规则合并（rebase / squash / merge） +10. 删分支；需要时打 tag 发 Release +``` + +--- + +## 六、学习路径建议 + +1. **第 1 周**：把第 1、3 篇练熟——能独立完成「克隆 → 分支 → 提交 → PR → 合并」。 +2. **第 2 周**：用 Issue 管自己的待办，把一个 PR 的 CI 配起来（第 2、4 篇）。 +3. **第 3 周**：加上分支保护、Dependabot、Secret scanning（第 5 篇），把「规范」变成「门禁」。 +4. 之后再考虑 Projects 自动化、Packages、Codespaces、Copilot。 + +> 记住一句话：**GitHub 的价值不在「能存代码」，而在「让改动可讨论、让错误在合并前暴露、让发布可复现」。** +> 流程看起来比「直接 push」麻烦，但它省下的是回滚、扯皮和半夜救火的时间。 + +--- + +## 七、系列索引 + +1. [入门：账号、仓库与第一次提交](/2026/10/23/github-guide-01-start/) +2. [Issues、Projects、Discussions 与 Wiki](/2026/10/23/github-guide-02-issues-projects/) +3. [Pull Request：从分支到合并](/2026/10/23/github-guide-03-pull-requests/) +4. [Actions、Releases 与 Packages](/2026/10/23/github-guide-04-actions-releases/) +5. [安全、组织与 Pages](/2026/10/23/github-guide-05-security-org/) +6. 从 0 到 1 的完整演练与避坑清单（本篇） \ No newline at end of file