GitHub 不僅是程式碼託管平台，更是團隊協作的中心。本章涵蓋 Fork 工作流、Pull Request 機制、Code Review 最佳實踐，以及 Issue 與 Project 管理。

一、Fork 與 Clone#

Fork 工作流#

適用於開源專案貢獻：

# 1. 在 GitHub 上 Fork 原專案

# 2. Clone 你的 Fork
git clone git@github.com:YOUR_USERNAME/project.git

# 3. 新增原專案為 upstream
git remote add upstream git@github.com:ORIGINAL_OWNER/project.git

# 4. 同步原專案更新
git fetch upstream
git merge upstream/main

直接 Clone#

適用於有寫入權限的專案：

git clone git@github.com:organization/project.git

二、Pull Request 工作流#

Pull Request（PR）是 GitHub 的核心協作機制，用於請求將一個分支的變更合併到另一個分支。

標準流程#

# 1. 從最新的 main 建立 feature 分支
git checkout main
git pull origin main
git checkout -b feature/add-login

# 2. 開發並提交
git add .
git commit -m "Add login feature"

# 3. 推送到遠端
git push -u origin feature/add-login

# 4. 在 GitHub 上建立 Pull Request

PR 最佳實踐#

撰寫優質 PR：

• 標題：簡潔描述變更目的
• 描述：說明背景、解決方案、測試方式
• 關聯 Issue：使用 Fixes #123 自動關聯
• 適當大小：單一 PR 不超過 400 行變更

三、分支整合策略#

GitHub 提供三種 Merge 選項，決定專案歷史的樣貌：

1. Create a Merge Commit#

* Merge branch 'feature' into main
|\
| * Feature commit 3
| * Feature commit 2
| * Feature commit 1
|/
* Previous main commit

• 保留完整歷史：可看到分支的分岔與合併
• 適用場景：複雜專案、需追溯開發脈絡

2. Squash and Merge#

* Feature: Add login (squashed)
* Previous main commit

• 壓縮為單一 Commit：所有 feature 分支的變更合併為一個
• 線性歷史：主幹清晰，每個節點代表完整功能
• 適用場景：feature 分支的瑣碎 commit 對歷史無意義

3. Rebase and Merge#

* Feature commit 3
* Feature commit 2
* Feature commit 1
* Previous main commit

• 逐一複製 Commit：保留每個 commit 的訊息
• 線性歷史：無合併節點
• 適用場景：希望保持線性但保留詳細提交紀錄

選擇建議：

• 需要完整歷史脈絡 → Merge Commit
• 追求主幹整潔 → Squash and Merge
• 保留詳細紀錄但線性 → Rebase and Merge

四、Code Review 機制#

設定分支保護規則#

強制 Code Review 是確保程式碼品質的關鍵：

1. 進入 Settings → Branches → Add rule
2. 輸入分支名稱（如 main）
3. 勾選 Require pull request reviews before merging
4. 設定最低審核人數（1-6 人）

設定完畢後，即便是管理員也無法直接 Push 到受保護分支（除非特別設定 bypass 權限）。

審核流程#

flowchart TD
    A[發起者提交 PR] --> B[指定 Reviewer]
    B --> C[Reviewer 收到通知]
    C --> D[Reviewer 審查程式碼]
    D --> E{審查結果}
    E -->|Approve| F[合併 PR]
    E -->|Request Changes| G[發起者修正]
    E -->|Comment| H[討論交流]
    G --> D
    H --> D

審核重點#

• 程式碼邏輯：是否符合需求、有無明顯 bug
• 程式碼風格：是否符合團隊規範
• 測試覆蓋：是否有對應的測試案例
• 效能考量：是否有效能隱患

針對特定程式碼行留言，可以清楚指出問題位置。使用 “Request changes” 而非 “Comment” 可以阻擋合併。

五、衝突處理#

遠端衝突情境#

當本地與遠端都有新的 commit 時：

# 推送被拒絕
git push origin feature
# ! [rejected] feature -> feature (non-fast-forward)

# 解決方案一：Pull 並合併
git pull origin feature
# 解決衝突後
git push origin feature

# 解決方案二：Rebase
git pull --rebase origin feature
# 解決衝突後
git push origin feature

PR 中的衝突#

當 PR 與目標分支產生衝突時：

# 同步目標分支
git fetch origin
git checkout feature
git merge origin/main
# 或
git rebase origin/main

# 解決衝突後推送
git push origin feature

禁止 Force Push 到公共分支：

# 絕對禁止！
git push -f origin main

這會覆蓋遠端歷史，導致其他協作者的工作遺失。

六、Issue 與 Project 管理#

Issue 管理#

GitHub Issue 採用輕量化設計，透過 Label 驅動分類：

建議的 Label 維度#

Issue Templates#

引導回報者提供完整資訊：

## <!-- .github/ISSUE_TEMPLATE/bug_report.md -->

name: Bug Report
about: Report a bug

---

## 問題描述

## 重現步驟

1.
2.
3.

## 預期行為

## 實際行為

## 環境資訊

- OS:
- Browser:
- Version:

參考成熟開源專案（如 Vue.js）的 .github 目錄，可以學到完整的 Issue Template 與 PR Template 設計。

Project Board#

使用看板（Kanban）追蹤任務進度：

七、GitHub Actions 基礎#

GitHub Actions 提供自動化 CI/CD 能力。

基本概念#

• Workflow：自動化流程，定義在 .github/workflows/*.yml
• Event：觸發條件（push、pull_request、schedule）
• Job：工作單元，可並行或串行執行
• Step：Job 中的步驟

範例：基本 CI 流程#

# .github/workflows/ci.yml
name: CI

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

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

      - name: Run linter
        run: npm run lint

常見觸發事件#

on:
  # Push 到指定分支
  push:
    branches: [main, develop]

  # Pull Request
  pull_request:
    branches: [main]

  # 定時執行
  schedule:
    - cron: "0 0 * * *" # 每天 UTC 0:00

  # 手動觸發
  workflow_dispatch:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18, 20, 22]

    steps:
      - uses: actions/checkout@v4

      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}

      - run: npm ci
      - run: npm test

八、團隊工作流選擇#

GitHub Flow（推薦）#

極簡的工作流，適合持續部署：

gitGraph
    commit id: "init"
    commit id: "v1.0"
    branch feature
    commit id: "開發功能"
    commit id: "完成功能"
    checkout main
    merge feature id: "Merge PR"
    commit id: "v1.1"

流程說明：

1. 從 main 建立 feature 分支
2. 開發並提交
3. 發起 Pull Request
4. Code Review 通過後合併
5. 合併即可部署

適用場景：Web 服務、SaaS 產品等可隨時部署的專案。

Git Flow#

完整但繁瑣的工作流：

gitGraph
    commit id: "init" tag: "v1.0"
    branch develop
    commit id: "開發中"
    branch feature/login
    commit id: "實作登入"
    commit id: "完成登入"
    checkout develop
    merge feature/login id: "合併功能"
    branch release/1.1
    commit id: "準備發布"
    checkout main
    merge release/1.1 id: "發布" tag: "v1.1"
    checkout develop
    merge release/1.1 id: "同步"

分支說明：

• main：生產版本
• develop：開發整合
• feature/*：功能開發
• release/*：發布準備
• hotfix/*：緊急修復

Git Flow 較適合發布週期長、版本控管嚴格的傳統軟體開發。對於追求快速迭代的網際網路產品，可能過於繁瑣。

常用操作速查#