Round 2 deepen: github-tech-zh-tw — project-level examples, perf/quality/security, cross-site comparison, checklists

Author: shumingyang-opencode

docs/unit-01-github-intro.html

@@ -220,6 +220,105 @@ <h2>1.12 進階挑戰題</h2>
   <li>研究 GitHub OAuth App 與 GitHub App 的差異（從 Settings → Developer settings），寫一段 150 字說明你會在什麼場景選擇哪一種。</li>
 </ol>
 
+<h2>1.13 專案級端到端 Worked Example：TechCo 公司 GitHub 基礎建設專案</h2>
+<p>把本單元的知識（平台、認證、Organization、安全治理）放大到<strong>整家公司</strong>的規模：所有設定都寫成程式碼（Infrastructure as Code），放進一個 <code>techco-infra</code> repo，讓「公司怎麼用 GitHub」也可以審查、版本化、重現——這是單元 1.9「單一 repo 治理」之上的整站層級。</p>
+<div class="demo-grid">
+  <div class="demo-block"><div class="demo-label">產出檔案樹 · FILE TREE</div><pre>techco-infra/
+├── .github/
+│   ├── CODEOWNERS            <span class="hl-c"># 設定變更需 DevOps 審查</span>
+│   └── workflows/
+│       └── audit.yml         <span class="hl-c"># 每晚稽核「設定有沒有漂移」</span>
+├── scripts/
+│   ├── bootstrap-org.sh      <span class="hl-c"># 一次性初始化（延伸 1.9）</span>
+│   └── apply-policies.sh     <span class="hl-c"># 把策略套到所有 repo</span>
+├── policies/
+│   ├── org.yml               <span class="hl-c"># org 層級規則</span>
+│   └── branch-protection.json<span class="hl-c"># 標準保護分支設定</span>
+└── README.md</pre></div>
+  <div class="demo-block"><div class="demo-label">關鍵檔案 · KEY FILES</div><pre><span class="hl-c"># policies/branch-protection.json（片段）</span>
+{
+  "required_status_checks": {
+    "strict": true,
+    "contexts": ["ci"]
+  },
+  "required_pull_request_reviews": {
+    "required_approving_review_count": 2
+  },
+  "enforce_admins": true
+}
+
+<span class="hl-c"># scripts/apply-policies.sh（核心迴圈）</span>
+for repo in $(gh repo list TechCo \
+  --json name --jq '.[].name'); do
+  gh api --method PUT \
+    "/repos/TechCo/$repo/branches/main/protection" \
+    --input policies/branch-protection.json
+done</pre></div>
+</div>
+<div class="demo-block">
+  <div class="demo-label">驗證命令與輸出 · VERIFY</div>
+  <pre><span class="hl-c"># 1. 驗證所有 repo 的保護分支都生效</span>
+gh api /repos/TechCo/backend/branches/main/protection \
+  --jq '.required_pull_request_reviews.required_approving_review_count'
+<span class="hl-c"># 輸出 → 2</span>
+
+<span class="hl-c"># 2. 稽核成員 2FA 狀態（org 稽核 log）</span>
+gh api "/orgs/TechCo/audit-log" --paginate \
+  --jq '.[] | select(.action=="org.two_factor_requirement_enabled")' | head -1
+<span class="hl-c"># 輸出 → {"action":"org.two_factor_requirement_enabled", ...}</span>
+
+<span class="hl-c"># 3. 全公司 repo 清單與可見性</span>
+gh repo list TechCo --limit 100 --json name,visibility
+<span class="hl-c"># 輸出 → [{"name":"backend","visibility":"PRIVATE"}, ...]</span></pre>
+</div>
+<div class="callout info"><strong>為什麼這是「專案級」：</strong>單元 1.9 只設定單一 repo；這裡把<strong>整間公司</strong>當成一個專案在治理——用程式碼管策略、用 CI 稽核漂移、用 CODEOWNERS 讓重大變更有人把關。規模越大，「人按 UI 慢慢點」越不可行，改成「程式碼 + 自動化」才是正解。</div>
+
+<h2>1.14 效能 / 品質 / 安全深度</h2>
+<div class="demo-grid">
+  <div class="demo-block"><div class="demo-label">效能 · PERFORMANCE</div><pre><span class="hl-c"># 傳輸與 API 面</span>
+- git clone 用 SSH 比 HTTPS 少一層認證往返
+- API rate limit：認證 5,000 次/小時，批次優先
+- 大 repo 用 --filter=blob:none 只拉需要的物件
+- LFS 檔案走獨立 CDN，不卡 Git 傳輸
+<span class="hl-c"># 回報與儀表板</span>
+- github.com/status 查平台可用性
+- gh api /rate_limit 檢查剩餘額度</pre></div>
+  <div class="demo-block"><div class="demo-label">品質 · QUALITY</div><pre>平台層品質由 GitHub 保證（SLA、Status Page），
+你這一層的品質是「設定品質」：
+- 每條規則都有人負責（CODEOWNERS）
+- 設定進 repo：可 diff、可 review
+- 稽核 workflow 每天抓「設定漂移」
+- 新 repo 用預設範本（repo template）
+  自動帶上安全設定，避免「開局就裸奔」</pre></div>
+  <div class="demo-block"><div class="demo-label">安全 · SECURITY</div><pre>安全由上到下三層：
+1. 身份層：SAML SSO + 強制 2FA
+2. 存取層：最小權限 + 保護分支
+3. 內容層：Secret Scanning + push protection
+紅線：PAT 只用最小 scope、不放進 repo、
+失效立刻撤銷；金鑰一律存密碼管理員。</pre></div>
+</div>
+
+<h2>1.15 站際比較：GitHub vs GitLab vs Markdown vs YAML vs JSON</h2>
+<table>
+<tr><th>面向</th><th>github</th><th>gitlab</th><th>markdown</th><th>yaml</th><th>json</th></tr>
+<tr><td>定位</td><td>雲端程式碼託管平台</td><td>雲端 / 自架 DevOps 平台</td><td>輕量排版語法</td><td>人類可讀設定格式</td><td>資料交換格式</td></tr>
+<tr><td>認證</td><td>PAT / SSH / OAuth</td><td>PAT / OAuth / SAML</td><td>—（不涉及）</td><td>—（不涉及）</td><td>—（不涉及）</td></tr>
+<tr><td>組織治理</td><td>Organization + Teams</td><td>Group + Subgroups（權限更細）</td><td>—</td><td>—</td><td>—</td></tr>
+<tr><td>與其他欄的關係</td><td>全站以 Markdown 寫文件、YAML 寫 Actions、JSON 做 API 資料</td><td>同左（CI 也用 YAML）</td><td>GitHub README / Issue 的載體</td><td>GitHub Actions workflow 的載體</td><td>GitHub REST API 的回應格式</td></tr>
+</table>
+
+<h2>1.16 互動式進階檢核清單</h2>
+<div class="demo-render">
+  <ul>
+    <li><label><input type="checkbox"> 我的帳號已開啟 2FA，並把救援碼備份到密碼管理員。</label></li>
+    <li><label><input type="checkbox"> 我已建立 Organization（或至少知道其用途），並啟用 SSO / 強制 2FA。</label></li>
+    <li><label><input type="checkbox"> 至少一個 repo 已套用保護分支（2 人 Approve + CI 通過）。</label></li>
+    <li><label><input type="checkbox"> 我的 PAT 只授予必要 scope，且存放在密碼管理員而非 repo 或程式碼。</label></li>
+    <li><label><input type="checkbox"> 我能從稽核 log 說出「最近一次權限變更」是誰、改什麼。</label></li>
+    <li><label><input type="checkbox"> 我把公司/個人「GitHub 使用規則」寫成了文件（誰可建 repo、token 規則、誰負責）。</label></li>
+  </ul>
+</div>
+
 </div>
 <footer>這是 GitHub 繁體中文教學站 · 由 OpenCode 建置<br>
   <span class="footer-license">本站教學內容（繁體中文解說）為本站原創，採 CC-BY-4.0；技術名詞與操作引用自 <a href="https://docs.github.com/" rel="noopener">GitHub Docs</a>與 <a href="https://git-scm.com/doc" rel="noopener">Git 官方文件</a>。</span></footer>

docs/unit-02-first-repo.html

@@ -270,6 +270,112 @@ <h2>2.13 進階挑戰題</h2>
   <li>研究 <code>git push --force</code> 與 <code>git push --force-with-lease</code> 的差異，實際用兩個分支模擬場景：為什麼 force-with-lease 更安全？</li>
 </ol>
 
+<h2>2.14 專案級端到端 Worked Example：全端 Monorepo「從空白到可交付」專案</h2>
+<p>單元 2.9 只推了「一個 README」；這裡建立一個<strong>真的要開工的全端 monorepo</strong>——frontend、backend、docs、assets 一次到位，含 .gitignore、Git LFS、commit 規範。做完它，你的 repo 就是「可以直接交給團隊」的狀態——這是單元 2.10「單一 repo 進階技巧」之上的整站施工標準。</p>
+<div class="demo-grid">
+  <div class="demo-block"><div class="demo-label">產出檔案樹 · FILE TREE</div><pre>techco-app/
+├── frontend/                  <span class="hl-c"># React + Vite</span>
+│   ├── src/
+│   └── package.json
+├── backend/                   <span class="hl-c"># Python FastAPI</span>
+│   ├── app/
+│   ├── requirements.txt
+│   └── .env.example           <span class="hl-c"># 範例，絕不提交 .env</span>
+├── docs/
+│   └── architecture.md
+├── assets/                    <span class="hl-c"># 大檔 → Git LFS</span>
+│   └── demo.mp4
+├── .gitattributes             <span class="hl-c"># LFS 規則（由 LFS 追蹤）</span>
+├── .gitignore
+├── .editorconfig
+└── README.md</pre></div>
+  <div class="demo-block"><div class="demo-label">關鍵檔案 · KEY FILES</div><pre><span class="hl-c"># .gitattributes（LFS 規則）</span>
+*.mp4  filter=lfs diff=lfs merge=lfs -text
+*.zip  filter=lfs diff=lfs merge=lfs -text
+*.psd  filter=lfs diff=lfs merge=lfs -text
+
+<span class="hl-c"># .gitignore 重要段落</span>
+node_modules/
+dist/
+__pycache__/
+.env
+*.log
+
+<span class="hl-c"># README.md（門面）</span>
+# TechCo App
+全端範例：React + FastAPI
+├── 快速開始
+├── 結構說明
+└── 開發規範（commit 格式、分支名）</pre></div>
+</div>
+<div class="demo-block">
+  <div class="demo-label">驗證命令與輸出 · VERIFY</div>
+  <pre><span class="hl-c"># 1. 確認 .env 與 node_modules 不會被追蹤</span>
+git status --porcelain | grep -E '\.env|node_modules'
+<span class="hl-c"># 輸出 →（空，代表沒被追蹤）</span>
+
+<span class="hl-c"># 2. 確認 LFS 生效</span>
+git lfs ls-files
+<span class="hl-c"># 輸出 → 1f8a2b... assets/demo.mp4 (LFS: 24.5 MB)</span>
+
+<span class="hl-c"># 3. 檢查 repo 實體體積（不含 LFS 大檔）</span>
+git count-objects -vH | grep size-pack
+<span class="hl-c"># 輸出 → size-pack: 說明 repo 保持輕量</span>
+
+<span class="hl-c"># 4. 全新機器 clone 驗證（LFS 自動下載）</span>
+git clone git@github.com:TechCo/techco-app.git
+git lfs pull</pre>
+</div>
+<div class="callout info"><strong>為什麼這是「專案級」：</strong>不是「學會 push 一個檔案」，而是把 repo「初始化到可交付」——敏感檔被擋住、大檔走 LFS、新人看 README 就能開工。單元 2.10 是單一 repo 的進階技巧，這裡是<strong>整個產品 repo 的施工標準</strong>。</div>
+
+<h2>2.15 效能 / 品質 / 安全深度</h2>
+<div class="demo-grid">
+  <div class="demo-block"><div class="demo-label">效能 · PERFORMANCE</div><pre>repo 尺寸管理：
+- 大檔走 LFS，避免 repo 肥大
+- GitHub 警示：repo 超過 1GB 應處理
+clone 加速：
+- --depth=1 淺克隆（CI 常用）
+- --filter=blob:none 只抓歷史結構
+- sparse-checkout 只 checkout 需要的目錄
+傳輸：
+- 每次 push 只送 packfile 差異，而非整個檔案</pre></div>
+  <div class="demo-block"><div class="demo-label">品質 · QUALITY</div><pre>repo 就是產品門面：
+- README：一句話說明 + 快速開始
+- .editorconfig：統一縮排與換行
+- commit 訊息規範（feat:/fix:/docs:）
+- 開啟 branch protection 或 repo rulesets
+內務：.gitignore 寫完整 → 別人不小心
+提交 .env 時，檢核與 CI 會擋下。</pre></div>
+  <div class="demo-block"><div class="demo-label">安全 · SECURITY</div><pre>第一道防線在 repo 邊界：
+- .env / 憑證檔 100% 進 .gitignore
+- 提交前用 pre-commit hook 掃 secret
+- 開啟 Secret scanning 與 push protection
+- 已洩漏：先撤銷憑證 &gt; 再清理歷史（filter-repo）
+- 最小權限：只有需要的人能寫入</pre></div>
+</div>
+
+<h2>2.16 站際比較：GitHub vs GitLab vs Markdown vs YAML vs JSON</h2>
+<table>
+<tr><th>面向</th><th>github</th><th>gitlab</th><th>markdown</th><th>yaml</th><th>json</th></tr>
+<tr><td>repo 建立</td><td>gh repo create / 網頁按鈕</td><td>GitLab 專案創建 / API</td><td>—（不涉及）</td><td>—（不涉及）</td><td>—（不涉及）</td></tr>
+<tr><td>託管與私有</td><td>GitHub.com / Enterprise Server</td><td>SaaS / 自架 GitLab CE/EE</td><td>—</td><td>—</td><td>—</td></tr>
+<tr><td>大型檔案</td><td>Git LFS（單檔上限 2GB）</td><td>Git LFS（額度策略不同）</td><td>—</td><td>—</td><td>—</td></tr>
+<tr><td>檔案內容形式</td><td>以 Markdown 寫 README / 文件</td><td>同左</td><td>README 與文件的主要語法</td><td>CI 設定（.gitlab-ci.yml）</td><td>GitHub / GitLab API 的傳輸格式</td></tr>
+<tr><td>協作入口</td><td>Issue / PR 按鈕</td><td>Issue / MR 按鈕</td><td>—</td><td>—</td><td>—</td></tr>
+</table>
+
+<h2>2.17 互動式進階檢核清單</h2>
+<div class="demo-render">
+  <ul>
+    <li><label><input type="checkbox"> repo 內沒有任何 .env、金鑰或密碼（grep 搜尋過也確認乾淨）。</label></li>
+    <li><label><input type="checkbox"> 所有大檔（&gt;50MB）都已改由 Git LFS 追蹤，clone 速度不受影響。</label></li>
+    <li><label><input type="checkbox"> 在全新機器上 clone 後，依 README 指引一鍵就能把專案跑起來。</label></li>
+    <li><label><input type="checkbox"> commit 訊息統一格式（feat:/fix:/docs:/chore:）。</label></li>
+    <li><label><input type="checkbox"> 已開啟 Secret scanning / push protection，且設有自動檢核。</label></li>
+    <li><label><input type="checkbox"> .editorconfig 與 .gitignore 已提交，且團隊確實遵循。</label></li>
+  </ul>
+</div>
+
 </div>
 <footer>這是 GitHub 繁體中文教學站 · 由 OpenCode 建置<br>
   <span class="footer-license">本站教學內容（繁體中文解說）為本站原創，採 CC-BY-4.0；技術名詞與操作引用自 <a href="https://docs.github.com/" rel="noopener">GitHub Docs</a>與 <a href="https://git-scm.com/doc" rel="noopener">Git 官方文件</a>。</span></footer>