GitHub CLI 常用命令筆記

📅 2025/07/24 23:34 📁 Git, 介紹好用工具

最近 GitHub CLI 用的很開心，因為用了 GitHub Copilot Coding Agent, OpenAI Codex CLI, Gemini CLI 與 Claude Code 之後，有越來越多專案都開始移往 GitHub 平台，而我在寫 GitHub Actions workflows 的時候，也非常愛用 GitHub CLI 幫我操作 GitHub Issues 與 PRs，超級方便。這篇文章我打算記錄一些比較常用的參數與命令，以備日後快速查找參考。

安裝 GitHub CLI

GitHub CLI 支援 macOS, Linux, BSD 與 Windows 平台，安裝方式參見: https://github.com/cli/cli#installation

以下是 Windows 的安裝方法：

  • WinGet

    # 安裝
winget install --id GitHub.cli

# 升級
winget upgrade --id GitHub.cli

  • scoop

    # 安裝
scoop install gh

# 升級
scoop update gh

  • Chocolatey

    # 安裝
choco install gh

# 升級
choco upgrade gh

初始化登入

GitHub CLI 有兩種認證方式：

  1. 使用 gh auth login 登入，用你的 GitHub 身份進行操作

    這是最常見的使用方式，可以用你的 GitHub 身份執行完整的 GitHub CLI 功能，包含 GitHub Copilot CLI。

  2. 直接讀取 GH_TOKEN 或 GITHUB_TOKEN 環境變數 (免走登入程序)

    你要事先建立 GitHub PAT (personal access tokens) 並將其設定到 GH_TOKEN 或 GITHUB_TOKEN 環境變數中 (二選一即可)。

    💡 注意: 透過環境變數認證是無法使用 GitHub Copilot CLI 的，但是可以在建立 PAT 金鑰時設定較為精細的權限，對於自動化任務來說，是比較適合的授權方式。

    詳見: Managing your personal access tokens

設定好之後，可以用以下命令查看登入狀態：

gh auth status

設定慣用編輯器

由於我們可能會需要在命令列直接建立 Issue，所以偶爾會需要編輯器來編寫文字。

  • 設定 Visual Studio Code 做為預設的文字編輯器

    gh config set editor "code --wait"

  • 設定 vim 做為預設的文字編輯器

    gh config set editor "vim"

你可以用以下命令測試開啟編輯器編輯內容：

gh issue create

或是透過以下命令在 Feature Branch 建立 PR 時，也需要文字編輯器撰寫一些內容：

gh pr create --draft --assignee @me

常見命令整理

💡 提醒: 大部分的 gh 命令都只要在 git 工作目錄執行，就會自動從 git remote 找到 GitHub Repo 的網址。

  • Repos

    查看目前 Repo 的相關資訊

    gh repo view

    查看任意 Repo 的相關資訊

    gh repo view doggy8088/TampermonkeyUserscripts

    直接 Fork 某個 Repo 並直接將這份 Fork 過的 Repo 給 Clone 到本地

    gh repo fork cli/cli

    直接將目前已經 Clone 的 Repo 建立一個 Fork repo 並將 origin 更名為 upstream，然後 origin 會換成 forked remote

    gh repo fork

  • Clone

    # Method 1
gh repo clone cli/cli

# Method 2
gh repo clone https://github.com/cli/cli

    Method 2 就是把 git 換成 gh repo 而已，但可以簡寫 cli/cli。

  • Checkout / PR

    自動取出 PR #12 的分支內容

    gh pr checkout 12

    也可以直接輸入網址來取出 PR 的分支

    gh pr checkout https://github.com/doggy8088/duotify-form-autofill/pull/6

    顯示目前 PR 的狀態

    gh pr status

  • Issues / PRs

    基本上 Issues 與 PRs 用法大多相同，許多命令 gh issue 換成 gh pr 就可以用，不過 PR 會綁定一個分支，通常要 gh pr checkout NN 之後才能查看狀態。

    快速列出跟自己有關的 Issues

    gh issue status

    列出 Issues

    # 列出所有 Open 的 Issues (預設只會傳回 30 筆)
gh issue list
# 列出所有 Closed 的 Issues
gh issue list -s closed
# 列出所有 Issues
gh issue list -s all
# 列出我建立的 Issues
gh issue list --author '@me'
# 列出我建立的 Issues
gh issue list --assignee 'user'
# 列出所有 kind/bug 標籤的 Issues 且要回傳最多 100 筆
gh issue list -l 'kind/bug' -L 100

    查看單一個 Issue 的明細

    # 查看 Issue 主要內容
gh pr view 21
# 查看 Issue 主要內容並列出所有留言
gh pr view 21 --comments
# 直接開啟瀏覽器查看 Issue 內容
gh pr view 21 --web

    建立 Issue

    # 互動式建立 Issue
gh issue create

# 透過瀏覽器建立 Issue
gh issue create --web

# 非互動方式建立 Issue
gh issue create --title "Issue title" --body "Issue body"

    替 Issue 加上表情符號 (需透過 gh api 呼叫)

    # 直接在某個 Issue 的主文 `+1` 按讚
gh api -X POST /repos/doggy8088/plaud-web-uploader/issues/43/reactions -f content='+1'

# 取得某個 Issue 的主文的所有表情符號清單
gh api -X GET /repos/doggy8088/plaud-web-uploader/issues/43/reactions

# 刪除表情符號(Reaction)，這裡 209967036 是當初按讚時的 Reaction ID
gh api -X DELETE /repos/doggy8088/plaud-web-uploader/issues/43/reactions/209967036

    詳細參考: REST API endpoints for reactions

  • 設定 gh 的 alias 命令

    假設你經常需要列出自己的工作

    # 定義名為 mywork 的別名
gh alias set my 'issue list --assignee @me'

# 未來直接執行 gh my 就等於 gh issue list --assignee @me
gh my

    假設你經常需要列出提到自己的 Issues

    # 你可以定義更有語意的 alias 別名
gh alias set 'issue mine' 'issue list --mention @me'

# 未來直接執行 gh issue mine 就等於 gh issue list --mention @me
gh issue mine

    假設你經常需要列出標籤為 bugs 的 Issues

    # 定義名為 bugs 的別名
gh alias set bugs 'issue list --label=kind/bug'
# 定義名為 bugs 的別名並直接覆蓋現有的別名
gh alias set bugs 'issue list --label=kind/bug' --clobber

# 未來直接執行 gh bugs 就等於 gh issue list --label=kind/bug
gh bugs

    列出所有的 gh aliases

    gh alias list

GitHub CLI 的擴充功能

  1. GitHub Copilot in the CLI

    # 一定要用 GitHub CLI OAuth 登入
gh auth login --web

# 安裝或升級 GitHub Copilot CLI
gh extension install github/gh-copilot --force

# 使用 GitHub Copilot 建議一個命令
gh copilot suggest "Install and configure git lfs"

# 使用 GitHub Copilot 解釋一個命令 (僅限英文回應)
gh copilot explain 'git lfs migrate import --everything --include="*.gz,*.png,*.jar"'

  2. gh-dash

    用 TUI 視覺化的方式呈現 Issues 與 PRs，非常美觀，少大很多命令！👍

    gh extension install dlvhdr/gh-dash

gh dash

  3. GitHub Actions Importer

    GitHub Actions Importer 可協助您規劃、測試及自動化從 Azure DevOps、Bamboo、Bitbucket、CircleCI、GitLab、Jenkins、Travis CI 平台遷移至 GitHub Actions！👍

    GitHub Actions Importer 以 Docker 容器形式散佈，並且此擴充功能可與官方 GitHub CLI 互動以操作 Docker 容器。

    # 安裝
gh extension install github/gh-actions-importer

# 更新
gh actions-importer update

# 設定
gh actions-importer configure

  4. GitHub Enterprise Importer CLI

    GitHub Enterprise Importer (GEI，前身為 Octoshift) 是一個高度可自訂的 API 優先遷移方案，旨在協助您將企業遷移至 GitHub Enterprise Cloud。GEI-CLI 將 GEI API 包裝成跨平台的命令列應用程式，以簡化您的遷移體驗自訂。

    # 安裝 Azure DevOps to GitHub 擴充功能
gh extension install github/gh-ado2gh

# 查看用法
gh ado2gh --help

# 詳見 Azure DevOps to GitHub Usage
# https://github.com/github/gh-gei?tab=readme-ov-file#azure-devops-to-github-usage

  5. GitHub Skyline

    可以自動產生你在 GitHub 貢獻圖，會自動輸出 3D 列印專用的 STL 檔案。

    # 安裝
gh extension install github/gh-skyline

# 產生
gh skyline
gh skyline --output my-skyline.stl
gh skyline --full
gh skyline --year 2024
gh skyline --year 2024 --user doggy8088
gh skyline --year 2014-2024 --user doggy8088

相關連結

留言評論