GitHub CLI 教學：高效的開發工作流程

關於本教學
本教學適合想要透過命令列提升GitHub工作效率的開發者，從基礎功能到進階工作流程都有涵蓋。

## 引言

GitHub命令列工具（GitHub CLI） 是提升開發工作流程效率的絕佳工具。透過命令列介面操作GitHub，您可以更快、更有條理地管理專案，無需頻繁切換至瀏覽器界面。本教學將帶您了解GitHub CLI的主要功能和實用工作流程。

安裝與設置

要開始使用GitHub CLI，首先需要安裝它：

各平台安裝命令
macOS (使用Homebrew):

brew install gh

Windows (使用Scoop):

scoop install gh

Linux (Debian/Ubuntu):

sudo apt install gh

安裝後，您需要進行驗證：

gh auth login

遵照螢幕上的指示，選擇通過瀏覽器或令牌（token）進行身份驗證。

基本命令介紹

GitHub CLI使用gh作為主命令，後接不同的子命令執行各種操作：

常用指令類別
| 指令 | 功能 | | ---- | ---- | | gh repo | 倉庫管理 | | gh issue | 問題追蹤 | | gh pr | 拉取請求操作 | | gh release | 版本發布 | | gh gist | 代碼片段管理 |

每個命令都有自己的子命令和選項，可以通過`gh help [command]`獲取幫助。

實用使用案例

讓我們看一些實際使用案例，幫助您更好地理解GitHub CLI在日常開發中的應用：

以下案例展示了GitHub CLI如何在各種場景中幫助您提高工作效率。

### 案例1：快速複製並參與開源專案

想要貢獻某個開源專案？GitHub CLI可以讓這個過程變得簡單：

快速參與開源專案的命令
```bash

複製倉庫並自動在您的帳號創建fork

gh repo fork cli/cli

自動為您設置遠端倉庫，無需手動配置

如果只想創建fork但不clone到本地

gh repo fork cli/cli --clone=false

創建分支並開始工作

git checkout -b feature-branch

完成工作後，直接從命令行提交PR

gh pr create --title "實現新功能" --body "解決了#123問題"


</div>
這個流程讓您無需在瀏覽器和終端間切換，顯著提高效率。

### 案例2：快速查看和管理專案狀態

需要快速了解專案中的問題和拉取請求？

<div style="background:#f5f5f5;border-left:4px solid #777;color:#333;padding:12px 16px;margin:12px 0;border-radius:4px">

<strong>專案狀態查詢命令</strong><br>```bash
# 列出所有開放的PR
gh pr list

# 查看特定PR的詳細信息
gh pr view 21

# 列出分配給您的issue
gh issue list --assignee @me

# 查看特定issue的詳細信息和評論
gh issue view 13 --comments

### 案例3：團隊協作和代碼審查

GitHub CLI提供強大的代碼審查功能，讓團隊協作更高效！

代碼審查相關命令
```bash

檢出同事的PR到本地，進行審查

gh pr checkout 15

在終端中查看PR的差異

gh pr diff

直接在命令行中批准PR

gh pr review 15 --approve

或者提出評論和修改建議

gh pr review 15 --comment -b "請考慮優化這部分的性能"


</div>
### 案例4：自動化工作流程整合

將GitHub CLI整合到您的自動化腳本中：

<div style="background:#f5f5f5;border-left:4px solid #777;color:#333;padding:12px 16px;margin:12px 0;border-radius:4px">

<strong>自動化工作流程命令</strong><br>```bash
# 創建新版本發布
gh release create v1.0.0 --title "第一個穩定版本" --notes "修復了多個bug和性能優化"

# 監控GitHub Actions工作流程
gh run list

# 等待特定工作流程完成
gh run watch

這些使用案例展示了GitHub CLI如何在各種場景中幫助您提高工作效率。

分支保護設置

在使用GitHub CLI之前，建議先設定分支保護規則，確保工作流程的安全性：

沒有適當的分支保護設置，可能導致團隊成員意外直接推送至主分支。

1. 在GitHub網站上導航至您的倉庫 2. 點擊「Settings」→「Branches」 3. 點擊「Add rule」為主分支（通常是`main`）添加保護規則 4. 建議的設置： - 勾選「Require a pull request before merging」 - 勾選「Require approvals」（團隊協作時） - 勾選「Require status checks to pass before merging」 - 勾選「Do not allow bypassing the above settings」

這些設置將防止直接推送到主分支，確保所有變更都經過PR流程審核。

工作流程教學：從issue到PR到合併

GitHub CLI支持完整的開發工作流程，下面是一個典型範例：

步驟1：創建Issue

每個新功能或修復都從創建issue開始：

Issue創建命令
```bash gh issue create -t "添加新功能：使用者註冊" -b "實現使用者註冊功能，包括表單和驗證"


或者使用交互模式：

```bash
gh issue create

系統會提示您輸入標題、描述和其他詳細信息。

步驟2：從Issue創建開發分支

這是GitHub CLI的強大功能之一，您可以直接從issue創建並切換到新分支：

從Issue創建分支
```bash gh issue develop [issue編號] -c


</div>
這個命令會：

- 創建一個基於issue標題的新分支
- 將分支與issue關聯
- 自動切換到新分支

現在您可以開始編寫代碼了！

### 步驟3：提交更改並推送

完成工作後，提交您的更改：

<div style="background:#f5f5f5;border-left:4px solid #777;color:#333;padding:12px 16px;margin:12px 0;border-radius:4px">

<strong>提交與推送命令</strong><br>```bash
git add .
git commit -m "添加使用者註冊功能"
git push -u origin HEAD

### 步驟4：創建PR

使用GitHub CLI創建PR：

PR創建命令
```bash gh pr create


系統會提示您輸入標題（默認使用提交信息）和描述。您也可以使用`-d`標記創建草稿PR：

```bash
gh pr create -d

草稿PR表示工作仍在進行中，尚未準備好審核。

步驟5：將草稿PR標記為準備就緒

當您的工作完成並準備好審核時：

將PR標記為準備就緒
```bash gh pr ready


</div>
### 步驟6：審核和合併PR

查看PR的狀態：

<div style="background:#f5f5f5;border-left:4px solid #777;color:#333;padding:12px 16px;margin:12px 0;border-radius:4px">

<strong>PR審核與合併命令</strong><br>```bash
gh pr view

合併PR（如果您有權限）：

gh pr merge

您可以選擇合併方式（標準合併、壓縮合併或變基合併）。

GitHub工作流程視覺化指南

以下使用Mermaid圖表視覺化展示GitHub完整工作流程，從初次提交到分支開發、合併與發布：

初始化倉庫與首次提交

[mermaid 圖表 — 原始 HackMD 版本可正常渲染]

flowchart TB A[開始專案] --> B["初始化本地倉庫
git init"] B --> C["建立必要檔案
echo '# 專案名稱' > README.md
echo '初始版本' > CHANGELOG.md"] C --> D["添加檔案
git add README.md CHANGELOG.md .gitignore"] D --> E["首次提交
git commit -m '初始提交: 建立專案結構'"] E --> F["創建遠端倉庫
gh repo create my-project --public --source=."] F --> G["推送至遠端
git push -u origin main"]

style A fill:#f9f,stroke:#333,stroke-width:2px
style G fill:#bbf,stroke:#333,stroke-width:2px</div>

查看詳細實現代碼
```bash

初始化本地倉庫

git init

建立忽略檔案 (最佳實踐)

cat > .gitignore << 'EOF'

依語言自動生成適合的 .gitignore

可訪問 https://gitignore.io/ 獲取適合您專案的內容

node_modules/ *.log .DS_Store .env EOF

添加文件

echo "# 我的專案" > README.md echo "初始版本" > CHANGELOG.md git add README.md CHANGELOG.md .gitignore

首次提交

git commit -m "初始提交: 建立專案結構"

使用GitHub CLI創建遠端倉庫 (推薦選項)

gh repo create my-project
--public \ # 公開倉庫，使用 --private 創建私有倉庫 --description "我的新專案描述" \ # 添加描述 --homepage "https://myproject.com" \ # 可選的主頁 --source=. \ # 使用當前目錄作為源 --remote=origin \ # 設置遠端名稱 --gitignore Node # 自動添加語言特定的.gitignore (可選)

如果需要添加授權文件

gh repo edit --add-license mit # 添加MIT授權

推送至遠端

git push -u origin main # 或 git push -u origin master 若使用舊版Git

驗證倉庫創建成功

gh repo view --web # 在瀏覽器中打開倉庫

常見問題解決：

如果遇到分支名稱問題 (master 與 main)

git branch -M main # 將當前分支重命名為main


</div>
**建議選項與最佳實踐：**

<div style="background:#d9edf7;border-left:4px solid #31708f;color:#31708f;padding:12px 16px;margin:12px 0;border-radius:4px">

- 使用有意義的倉庫名稱和描述，方便他人理解專案目的
- 建立 `.gitignore` 文件排除不需要版本控制的檔案
- 添加 `LICENSE` 和詳細的 `README.md` 說明專案用途和使用方法

</div>
使用結構化格式獲取倉庫資訊：

```bash
gh repo view --json name,description,visibility,defaultBranchRef

創建私有倉庫時添加協作者：

gh repo create --private my-project
gh repo add-collaborator my-project username --permission admin

開發分支與Bug修復流程

[mermaid 圖表 — 原始 HackMD 版本可正常渲染]

flowchart TB A["主分支
git checkout main
git pull"] --> B["建立問題
gh issue create -t '修復登入問題'"] B --> C["創建分支
gh issue develop issue編號 -c"] C --> D["修改代碼
(編輯相關檔案)"] D --> E["提交修復
git add .
git commit -m '修復登入問題'"] E --> F["推送分支
git push -u origin HEAD"] F --> G["創建PR
gh pr create --title '修復登入問題'"] G --> H{"需要修改?"} H -- 是 --> I["審查反饋
gh pr view --comments"] I --> J["修改代碼
(根據反饋修改)"] J --> K["提交修改
git commit -am '根據審查調整'
git push"] K --> H H -- 否 --> L["合併PR
gh pr merge --squash"] L --> M["清理分支
git checkout main
git pull
git branch -d bugfix-branch"]

style A fill:#bbf,stroke:#333,stroke-width:2px
style M fill:#bbf,stroke:#333,stroke-width:2px</div>

使用GitHub CLI實現完整修復流程
```bash

確保main分支最新

git checkout main git pull

創建並切換到bugfix分支

gh issue create -t "修復登入問題" -b "使用者無法在Safari瀏覽器登入" gh issue develop $(gh issue list --limit 1 --json number --jq '.[0].number') -c

設置分支追踪 (可選，方便後續操作)

git branch --set-upstream-to=origin/main

修復問題並提交

(進行必要的代碼修改)

git add . git commit -m "修復Safari登入問題" -m "詳細描述問題原因和解決方案"

遇到衝突時如何解決

git fetch origin main

git rebase origin/main

(解決衝突後)

git rebase --continue

推送分支到遠端

git push -u origin HEAD

創建PR (完整選項)

gh pr create
--title "修復Safari登入問題"
--body "解決issue #1中描述的Safari登入問題"
--assignee @me \ # 分配給自己 --label "bug,urgent" \ # 添加標籤 --milestone "v1.0" \ # 指定里程碑 --reviewer teammate1,teammate2 # 請求審核

檢查PR狀態

gh pr status

追蹤PR評論

gh pr view --comments

修改PR以回應審查意見

(進行修改後)

git add . git commit -m "根據審查意見調整" git push

等待審查後合併PR (多種選項)

gh pr merge
--squash \ # 壓縮合併，或使用 --merge/--rebase --delete-branch \ # 合併後刪除分支 --body "包含所有必要修復" # 自定義合併信息

同步本地環境

git checkout main git pull git branch -d bugfix-login-issue

如果忘記刪除遠端分支

gh pr list -s merged # 列出已合併的PR

gh pr view # 查看特定PR

git push origin --delete # 手動刪除遠端分支


</div>
**重要提示與最佳實踐：**

- 使用有意義的分支名稱，推薦格式: `<類型>/<描述>`，例如 `bugfix/safari-login`
- 提交詳細的PR描述，使用模板：

<div style="background:#f5f5f5;border-left:4px solid #777;color:#333;padding:12px 16px;margin:12px 0;border-radius:4px">

<strong>PR描述模板</strong><br>```markdown
## 問題描述
簡要說明問題

## 解決方案
如何解決

## 測試方法
如何驗證修復

Fixes #1

- 定期從主分支同步變更，避免大型合併衝突 - 使用 `gh pr ready` 標記草稿PR為可審核狀態 - 利用GitHub CLI監控CI/CD狀態: `gh run list --workflow=ci.yml`

版本發布流程

[mermaid 圖表 — 原始 HackMD 版本可正常渲染]

flowchart TB A["同步最新代碼
git checkout main
git pull"] --> B["確保測試通過
npm test"] B --> C["更新版本號
npm version patch
或手動更新package.json"] C --> D["更新變更日誌
更新CHANGELOG.md"] D --> E["提交版本更新
git add .
git commit -m '版本提升至 v1.0.0'
git push"] E --> F["創建標籤
git tag -a v1.0.0 -m '穩定版發布'
git push origin v1.0.0"] F --> G["發布版本
gh release create v1.0.0
--title 'v1.0.0 穩定版發布'
--notes-file CHANGELOG.md"] G --> H["添加發布資產
gh release upload v1.0.0 ./dist/app.zip"]

style A fill:#f9f,stroke:#333,stroke-width:2px
style H fill:#bbf,stroke:#333,stroke-width:2px</div>

使用GitHub CLI實現發布流程
```bash

確保在main分支上並同步最新變更

git checkout main git pull

建立版本標籤的不同方式

方式1: 使用語義化版本標籤

VERSION="1.0.0" echo "當前版本: $VERSION"

更新版本號（示例：在package.json中）

方式1: 手動編輯

方式2: 使用npm工具 (Node.js項目)

npm version patch --no-git-tag-version # 小版本更新

方式3: 使用jq工具 (通用方法)

jq '.version = "1.0.0"' package.json > tmp && mv tmp package.json

更新CHANGELOG.md (最佳實踐)

cat > CHANGELOG.md << 'EOF'

更新日誌

[1.0.0] - $(date +%Y-%m-%d)

新功能

實現使用者註冊
新增發布通知功能

修復

修復Safari登入問題
解決移動裝置顯示錯誤 EOF

提交版本更新

git add package.json CHANGELOG.md git commit -m "版本提升至 v1.0.0" git push

創建發布標籤

git tag -a v1.0.0 -m "v1.0.0 穩定版發布" git push origin v1.0.0

使用GitHub CLI創建完整發布 (多樣選項)

gh release create v1.0.0
--title "v1.0.0 穩定版發布"
--notes-file CHANGELOG.md \ # 使用CHANGELOG作為發布說明 --discussion-category "公告" \ # 創建討論主題 --target main \ # 指定目標分支 --verify-tag # 驗證標籤存在

可選: 添加發布資產

gh release upload v1.0.0 ./dist/app.zip ./docs/user-guide.pdf

可選: 發布後的維護操作

更新專案依賴

npm update --save

git add package.json package-lock.json

git commit -m "更新專案依賴"

git push

檢視並驗證發布

gh release view v1.0.0 gh release view v1.0.0 --web # 在瀏覽器中查看發布頁面


</div>
**版本發布最佳實踐建議：**

<div style="background:#dff0d8;border-left:4px solid #3c763d;color:#3c763d;padding:12px 16px;margin:12px 0;border-radius:4px">

- 使用[語義化版本控制](https://semver.org/lang/zh-TW/)規範（MAJOR.MINOR.PATCH）
  - MAJOR: 不兼容的API變更
  - MINOR: 向下兼容的功能新增
  - PATCH: 向下兼容的問題修復
- 維護詳細的CHANGELOG文件，記錄每個版本的更改
- 發布前進行完整測試，確保所有CI流程通過

</div>
為發布添加詳細文檔和使用示例:

- 使用預發布版本進行測試：
  ```bash
  gh release create v1.0.0-beta.1 --prerelease --title "v1.0.0 Beta 1"

設置自動化發布流程，利用GitHub Actions：

GitHub Actions發布工作流程
```yaml name: Release on: push: tags: ['v*'] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - run: npm ci - run: npm test - uses: softprops/action-gh-release@v1


</div>
這個視覺化工作流程展示了使用GitHub CLI管理整個軟體開發生命週期的方式，從初始化專案到功能開發、bug修復，再到版本發布。通過遵循這些步驟和使用GitHub CLI，您可以顯著提高團隊協作效率和代碼質量。

## 進階技巧：draft PR和PR驅動開發

### 使用草稿PR進行迭代開發

草稿PR非常適合用於長期持續開發的任務：

<div style="background:#d9edf7;border-left:4px solid #31708f;color:#31708f;padding:12px 16px;margin:12px 0;border-radius:4px">

<strong>草稿PR工作流程</strong><br>1. 創建草稿PR以早期獲取反饋
2. 持續在分支上工作並推送更新
3. 團隊成員可以實時跟踪和評論您的工作
4. 當準備就緒時，將PR標記為可審核

</div>
這種方法的優點：

- 保持工作透明度
- 提早發現潛在問題
- 避免大型PR帶來的審核困難
- 為長期工作保留開發記錄

### 多分支平行開發

當您同時處理多個功能時：

<div style="background:#d9edf7;border-left:4px solid #31708f;color:#31708f;padding:12px 16px;margin:12px 0;border-radius:4px">

<strong>平行開發策略</strong><br>1. 為每個功能創建單獨的issue
2. 從每個issue創建開發分支
3. 使用草稿PR跟踪每個功能的開發進度
4. 在不同分支間切換：`gh pr checkout [PR編號]`

</div>
當某個功能開發完成時，將其PR標記為可審核並合併，而不影響其他正在進行的工作。

## 總結與建議

GitHub CLI是一個強大的工具，能夠顯著提升您的開發工作流程效率：

<div style="background:#dff0d8;border-left:4px solid #3c763d;color:#3c763d;padding:12px 16px;margin:12px 0;border-radius:4px">

- 使用issue追踪任務和功能開發
- 遵循分支保護和PR流程，維護代碼質量
- 利用草稿PR進行透明的迭代開發
- 熟練使用GitHub CLI命令，減少上下文切換

</div>
最佳實踐：

- 為每個任務創建issue
- 保持PR規模小且集中
- 定期提交和推送更改
- 使用有意義的提交信息和PR描述
- 鼓勵團隊成員進行早期和持續的代碼審核

通過熟練運用GitHub CLI和這些工作流程，您可以建立更有組織、更高效的開發過程，無論是個人專案還是團隊協作。

## 常用命令參考

<div style="background:#f5f5f5;border-left:4px solid #777;color:#333;padding:12px 16px;margin:12px 0;border-radius:4px">

<strong>常用命令速查表</strong><br>```bash
# 倉庫操作
gh repo create           # 創建新倉庫
gh repo clone [倉庫]     # 克隆倉庫
gh repo view             # 查看當前倉庫信息

# Issue操作
gh issue list            # 列出issue
gh issue create          # 創建issue
gh issue view [編號]     # 查看issue詳情
gh issue develop [編號]  # 從issue創建開發分支

# PR操作
gh pr create             # 創建PR
gh pr list               # 列出PR
gh pr view [編號]        # 查看PR詳情
gh pr checkout [編號]    # 檢出PR分支
gh pr ready              # 將草稿PR標記為準備就緒
gh pr merge              # 合併PR

# 瀏覽器整合
gh browse                # 在瀏覽器中打開當前倉庫
gh pr view --web         # 在瀏覽器中查看PR

# 其他實用命令
gh run list              # 列出工作流程運行
gh release create        # 創建發布
gh gist create           # 創建代碼片段

## 參考資料

希望本教學能幫助您提升GitHub工作流程效率！

本文最初發布於 HackMD @BASHCAT。