glab 教學：GitLab 官方 CLI 從安裝到日常工作流

內容覆蓋上游 gitlab.com/gitlab-org/cli（kaisenlinux/glab 是 Debian 打包鏡像）。適用 GitLab 16.0+ / GitLab.com / Self-Managed / Dedicated。

1. 專案定位

glab 是什麼？

glab 是 GitLab 官方推出的命令列工具，等價於 GitHub 的 gh CLI。它讓你不必離開 terminal 就能完成 GitLab 上 90% 的日常操作：管理 Issues、開 Merge Request、查 CI/CD pipeline、發 Release、操作 cluster agent，甚至跟 GitLab Duo AI 對話。

為什麼要關心 kaisenlinux/glab 這個 GitHub 鏡像？

維度	上游 `gitlab.com/gitlab-org/cli`	本 repo `kaisenlinux/glab`
功能	完整原始碼	完整鏡像 + Debian / Snap 封裝
Release 節奏	持續迭代（v1.62 為最新）	隨上游 release 整版 import
Issue tracker	GitLab.com Issues	GitHub Issues 為 0（轉介上游）
主要消費者	開發者 / 貢獻者	Kaisen Linux / Debian 用戶
何時用本 repo	看 source 不是首選	`apt install glab` 或 `snap install glab` 鏈路追蹤

glab vs gh 對比

操作	GitHub (`gh`)	GitLab (`glab`)
Clone repo	`gh repo clone owner/repo`	`glab repo clone group/project`
開 PR / MR	`gh pr create`	`glab mr create`
List issues	`gh issue list`	`glab issue list`
查 CI 狀態	`gh run list`	`glab ci list` / `glab ci status`
看 release	`gh release list`	`glab release list`
AI 問答	`gh copilot suggest`	`glab duo ask <question>`

核心賣點

多 instance 自動偵測：在 git directory 內，從 remote URL 自動推斷要對哪個 GitLab host 操作（gitlab.com / 自架 / Dedicated）。
多認證方式並存：OAuth web flow（最簡單）/ Personal Access Token / CI Job Token（CI 環境內自動注入）。
CI/CD 第一公民：glab ci trace 可在 terminal 即時跟 pipeline log，glab ci retry 一鍵重跑。
GitLab Duo 整合：glab duo ask 直接在 CLI 問 AI git 怎麼用。

2. 安裝指南

2.1 Homebrew（macOS / Linux / WSL，官方推薦）

1brew install glab
2brew upgrade glab    # 更新

2.2 Debian / Ubuntu（透過 Kaisen Linux repo 或自行下載 .deb）

本 repo 就是這條路徑的源頭：

1# 從 GitLab official releases 直接下載 .deb：
2curl -LO https://gitlab.com/gitlab-org/cli/-/releases/permalink/latest
3sudo dpkg -i glab_*_linux_amd64.deb

2.3 Snap

1sudo snap install glab

2.4 從原始碼編譯

1# Prerequisites: Go 1.22+ 與 make
2go version    # 確認 ≥ 1.22
3
4# 一行裝完：
5go install gitlab.com/gitlab-org/cli/cmd/glab@main
6
7# 確認：
8glab version

如果 $GOPATH/bin 不在 PATH 內：

1export PATH="$(go env GOPATH)/bin:$PATH"

2.5 安裝流程圖


flowchart TD
    A[使用者] --> B{OS / 偏好}
    B -->|macOS / 跨平台| C[brew install glab]
    B -->|Debian / Ubuntu| D[Kaisen .deb / official .deb]
    B -->|有 snap| E[snap install glab]
    B -->|開發者 / 客製| F[go install ......cli/cmd/glab@main]
    C --> G[glab version 驗證]
    D --> G
    E --> G
    F --> G
    G --> H[glab auth login]
    H --> I[可開始日常使用]

3. 核心架構解析

3.1 整體架構（mermaid）


flowchart LR
    subgraph CLI["cmd/glab/main.go"]
        ENTRY[Entry Point
cobra root cmd]
    end

    subgraph Commands["internal/commands/"]
        AUTH[auth login/logout/status]
        REPO[repo clone/create/list]
        MR[mr create/list/approve/merge]
        ISSUE[issue create/list/close]
        CI[ci view/trace/retry/lint]
        RELEASE[release create/list/upload]
        DUO[duo ask  → AI]
    end

    subgraph Core["internal/ 核心模組"]
        API[api/
GitLab REST/GraphQL client]
        OAUTH[oauth2/
web flow 7171 port]
        CONFIG[config/
XDG config.yml]
        GIT[git/
本地 git 命令包裝]
        GLREPO[glrepo/
解析 remote 推斷 host]
        IO[iostreams/
顏色/分頁/TTY]
        RUN[run/
外部命令執行]
    end

    subgraph External["外部依賴"]
        GLAB_SAAS[GitLab.com API]
        GLAB_SM[Self-Managed GitLab]
        BROWSER[本地 browser
OAuth callback]
        GIT_CMD[本地 git 二進位]
    end

    ENTRY --> Commands
    Commands --> API
    Commands --> CONFIG
    Commands --> GIT
    AUTH --> OAUTH
    OAUTH --> BROWSER
    API --> GLREPO
    API --> GLAB_SAAS
    API --> GLAB_SM
    GIT --> GIT_CMD
    Commands --> IO

3.2 模組職責

路徑	職責
`cmd/glab/main.go`	CLI 進入點。負責 cobra root command 註冊、版本字串、debug flag 解析
`internal/commands/`	所有 subcommand 實作。每個 `glab xxx` 對應一個子目錄
`internal/api/`	GitLab REST / GraphQL client；底層用 `github.com/xanzy/go-gitlab`
`internal/auth/` & `internal/oauth2/`	三種認證流程的實作
`internal/config/`	讀寫 `~/.config/glab-cli/config.yml`，遵守 XDG spec
`internal/glrepo/`	從 git remote URL 解析出 hostname、project path
`internal/git/`	包裝本地 `git` 二進位的 subprocess 呼叫
`internal/iostreams/`	terminal color / pager / TTY 偵測，給輸出用
`internal/run/`	安全的外部命令執行（被 git/ 與 prompt/ 引用）

3.3 認證流程（OAuth Web Flow）


sequenceDiagram
    participant U as 使用者
    participant C as glab CLI
    participant B as 本地 browser
    participant G as GitLab.com
    U->>C: glab auth login
    C->>C: 起 HTTP server on 127.0.0.1:7171
    C->>B: open URL with state=xxx
    B->>G: GET /oauth/authorize?...
    G->>U: 顯示授權頁
    U->>G: 點 Authorize
    G->>B: 302 redirect → localhost:7171/auth/redirect?code=&state=
    B->>C: GET callback with code
    C->>G: POST /oauth/token (exchange code)
    G->>C: access_token + refresh_token
    C->>C: 寫入 ~/.config/glab-cli/config.yml
    C->>U: ✅ 認證成功

4. 日常工作流（Helper Scripts 詳細用法）

4.1 初次設定

 1# 1. OAuth 登入（最簡單；瀏覽器自動開啟）
 2glab auth login
 3
 4# 2. 確認認證狀態
 5glab auth status
 6
 7# 3. 設定預設編輯器（影響 mr create / issue create）
 8glab config set --global editor vim
 9
10# 4. 對自架 GitLab：
11glab config set -g host gitlab.example.com
12glab auth login --hostname gitlab.example.com

4.2 Merge Request 流程（最常用）

 1# 建立分支 + 提交（用 git）
 2git switch -c feature/awesome
 3git commit -am "feat: add awesome feature"
 4git push -u origin feature/awesome
 5
 6# 開 MR — 互動式（會跳編輯器要 title / description）
 7glab mr create
 8
 9# 開 MR — 一行搞定
10glab mr create --title "Add awesome feature" --description "見 issue #42" --target-branch main --assignee=@me
11
12# List 自己被 assign 的 MR
13glab mr list --assignee=@me
14
15# Review 別人的 MR
16glab mr view 1234
17glab mr checkout 1234   # 把該 MR 的分支 checkout 到本地
18
19# Approve
20glab mr approve 1234
21
22# Merge
23glab mr merge 1234 --squash

4.3 Issues

1glab issue create -t "Bug: login redirect loop" --label "bug,priority::high"
2glab issue list --assignee=@me --state opened
3glab issue close 567 --comment "Fixed in MR !1234"

4.4 CI/CD Pipelines

 1# 查最近 pipeline
 2glab ci list
 3
 4# 看當前分支的 pipeline 狀態
 5glab ci status
 6
 7# 即時 trace 一個 job 的 log（streaming）
 8glab ci trace <job-id>
 9
10# 重跑失敗的 job
11glab ci retry <pipeline-id>
12
13# 在 push 前 lint .gitlab-ci.yml
14glab ci lint

4.5 Release 管理

1glab release create v1.0.0 --notes "First stable release" --assets-link '{"name":"Linux binary","url":"..."}'
2glab release list
3glab release view v1.0.0

4.6 GitLab Duo AI

1# 忘了某個 git 命令的用法？
2glab duo ask "how do I revert the last 3 commits but keep the changes staged?"
3
4# 直接問
5glab duo ask "explain interactive rebase"

4.7 進階：API 直呼

1# 等價 curl 但自動帶認證 token
2glab api projects/:id/issues
3glab api -X POST projects/123/issues --field title="From CLI"

5. 應用場景

5.1 個人日常開發

開發者每天打開 terminal 第一件事可以是 glab mr list --assignee=@me 看自己被 assign 的 MR；省下打開 GitLab Web UI 的時間。

5.2 CI/CD 整合

在 GitLab CI job 內，CI_JOB_TOKEN 會自動注入；可以這樣做下游 trigger 或 cross-project release upload：

1# .gitlab-ci.yml
2deploy:
3  script:
4    - glab auth login --job-token $CI_JOB_TOKEN --hostname $CI_SERVER_HOST --api-protocol $CI_SERVER_PROTOCOL
5    - glab release create $CI_COMMIT_TAG --notes "Auto-released from CI"

5.3 跨多個 GitLab instance 工作

公司有自架 GitLab + 個人 GitLab.com 帳號的情境，glab 自動從 remote URL 推斷 host。在 ~/work-projects/ 內跑 glab issue list 會打公司 GitLab，在 ~/personal/ 內跑會打 gitlab.com。

5.4 Self-Managed GitLab 維運

DevOps / SRE 在 terminal 內快速建立 Release Notes、檢查 cluster agent 狀態、或從 CI 改設定。

5.5 GitOps 工作流

寫 shell script 把 glab mr create / glab mr merge 串起來做半自動化發布流程，比走 Web UI 容易 audit。

6. 資安掃描報告

掃描方法：對 scripts/、debian/、internal/oauth2/ 做 grep + 人工抽看 SECURITY.md、scripts/security-harness、cmd/glab/main.go。完整 Go source code（483 個 .go）不在掃描範圍（樣本抽看）。

6.1 紅黃綠燈總結

燈號	項目	評估
🟢	License	MIT，乾淨，無 GPL 傳染性
🟢	上游可信度	GitLab 官方專案；本 repo 為 kaisenlinux 鏡像，commit 全為 `Import the X.Y.0 release`，無中間人修改痕跡
🟢	Token 處理	OAuth 走 localhost 7171 callback；token 寫入 `~/.config/glab-cli/config.yml`（XDG spec），未發現 hard-coded secret
🟢	TLS 預設	預設驗證 TLS；`skip_tls_verify` 必須 explicit set 才會關，且文件明示僅供 self-signed CA 場景
🟢	`scripts/security-harness`	Ruby 寫的 pre-push hook，作用是「防止從上游 mirror 推回 public」的保護機制；非攻擊面
🟡	對外網路連線	`glab api` / `glab duo ask` 必然發 HTTPS 出 GitLab.com 或自架 instance — 預期行為，但若內部禁外連需注意
🟡	`scripts/commit-lint/` Node 依賴	含 `package-lock.json`，依賴鏈 50+ 個 npm packages（有 `tinyexec`）；僅在 maintainer 開發時跑 commit lint，不在執行期注入
🟡	`scripts/setup_windows.iss`	Inno Setup 腳本，在 Windows 安裝期會註冊 PATH；標準行為但會修改系統環境變數
🟢	`os/exec` 使用	`cmd/glab/main.go` import `os/exec`，用於呼叫本地 `git`；參數透過 cobra 安全傳遞，非 shell 注入點
🟢	機密提交歷史	grep `secret

6.2 結論

整體燈號：🟢 低風險。

glab 是 GitLab 官方專案，安全責任由 GitLab Security Team 持續維護（見 SECURITY.md 中的 disclosure 流程）。本 kaisenlinux/glab 鏡像不做修改，只重新打包，無 supply-chain 中間人風險。日常使用注意：

glab auth login 跑完後，~/.config/glab-cli/config.yml 含 OAuth refresh token — 視同 SSH key，不要 commit 進 repo、不要分享。
若用 CI Job Token，避免在 script: 區段 echo 出來。
自架 GitLab 用 self-signed CA 時，優先設 ca_cert 路徑，避免用 skip_tls_verify。

7. FAQ

Q1：glab 跟 gh 可以共存嗎？ A：可以。完全不衝突，兩個是不同 binary、設定檔不同位置。

Q2：在自架 GitLab 上 OAuth 一直失敗？ A：90% 是 OAuth application 設定問題。確認：(1) Redirect URI 是 http://localhost:7171/auth/redirect；(2) Confidential 沒勾；(3) Scopes 含 openid、profile、read_user、write_repository、api。詳見 README §Authentication。

Q3：CI 環境裡怎麼快速跑命令？ A：用 --job-token $CI_JOB_TOKEN 參數，不要走 OAuth flow。

Q4：怎麼把 GitLab project clone 到本地？ A：glab repo clone group/project（自動帶認證；可不用先設 SSH key）。

Q5：glab 怎麼跟 git 整合？ A：底層直接呼叫 git 二進位（internal/run/ + internal/git/），所以你既有的 git config / SSH key / GPG sign 設定全部生效。

Q6：為什麼 kaisenlinux/glab star 數那麼少？ A：因為這是「打包用的鏡像」，使用者真正 watch / star 的是 gitlab.com/gitlab-org/cli。

Q7：可以離線使用嗎？ A：基本上不行 — glab 多數命令都要打 GitLab API。但 glab help、glab config get/set、glab alias 可以離線。

Q8：glab duo ask 要錢嗎？ A：要 GitLab Duo subscription（Pro / Enterprise tier）；沒訂閱會被拒。

8. 進階技巧

8.1 自訂 alias

1glab alias set myissues "issue list --assignee=@me"
2glab myissues   # 等同於 glab issue list --assignee=@me

8.2 與 fzf 串接 — interactive MR picker

1glab mr list --output json | jq -r '.[] | "\(.iid) \(.title)"' | fzf | awk '{print $1}' | xargs glab mr view

8.3 用 glab api 寫腳本

當官方子命令還沒覆蓋某 API endpoint 時，直接：

1glab api "projects/:id/protected_branches" --paginate

:id 會自動從當前 git remote 推斷。

8.4 在 shell prompt 顯示 MR 狀態

1function glab_mr_count() {
2    glab mr list --assignee=@me --output json 2>/dev/null | jq 'length'
3}
4PS1='$(glab_mr_count) MRs > '

8.5 多 host 切換

1glab config set host gitlab.com               # repo local
2glab config set --global host gitlab.work.com # 全域
3GITLAB_HOST=gitlab.staging.com glab issue list  # 單次覆蓋

9. 整合進其他工作流

9.1 與 AI-Knowledge Template 整合

用 paper-tutorial skill 整理某 paper 的 GitLab repo 時，可用 glab repo clone 拉 source。
用 gh-tutorial-qd（本 skill）對 mirror 到 GitHub 的 GitLab 專案（如本 repo）做交付。

9.2 與 superpowers / dispatching-parallel-agents 串接

CI/CD 監看可以用 sub-agent 並行跑 glab ci list -R proj1 × N，集合各專案 pipeline 狀態。

9.3 與 gh（GitHub CLI）互補

混合 GitHub + GitLab 的組織：gh pr list（GitHub）與 glab mr list（GitLab）並行查看，alias 起來：

1alias prs='gh pr list --assignee=@me && glab mr list --assignee=@me'

10. 重點摘要 Checklist

glab 是 GitLab 官方 CLI；kaisenlinux/glab 是 Debian 打包鏡像
安裝：brew / apt / snap / go install 四選一
認證：OAuth web flow 最方便（localhost:7171）
配置位置：~/.config/glab-cli/config.yml（XDG）
核心命令：auth / mr / issue / ci / release / repo / duo
CI 內：用 --job-token $CI_JOB_TOKEN
自架 instance：設 GITLAB_HOST 或 glab config set -g host
資安燈號：🟢 低風險，官方專案 + 無 mirror 篡改
License：MIT
上游 issue tracker：gitlab.com/gitlab-org/cli/-/issues（本 GitHub 鏡像不收 issue）

11. 進一步閱讀

上游官方：https://gitlab.com/gitlab-org/cli
官方文件：https://gitlab.com/gitlab-org/cli/-/blob/main/docs/source/index.md
Release page：https://gitlab.com/gitlab-org/cli/-/releases
Vulnerability disclosure：https://gitlab.com/gitlab-org/cli/-/issues/new?issuable_template=Vulnerability%20Disclosure
GitLab Duo 文件：https://docs.gitlab.com/ee/user/gitlab_duo/
Inspiration：本專案 README §Inspiration 段列了 gh (GitHub CLI) 等前作
本 mirror 維護者：Kevin Chevreuil（Kaisen Linux），kaisen@kaisenlinux.org

glab 教學：GitLab 官方 CLI 從安裝到日常工作流

Contents

glab 教學：GitLab 官方 CLI 從安裝到日常工作流

1. 專案定位

2. 安裝指南

2.1 Homebrew（macOS / Linux / WSL，官方推薦）

2.2 Debian / Ubuntu（透過 Kaisen Linux repo 或自行下載 .deb）

2.3 Snap

2.4 從原始碼編譯

2.5 安裝流程圖

3. 核心架構解析

3.1 整體架構（mermaid）

3.2 模組職責

3.3 認證流程（OAuth Web Flow）

4. 日常工作流（Helper Scripts 詳細用法）

4.1 初次設定

4.2 Merge Request 流程（最常用）

4.3 Issues

4.4 CI/CD Pipelines

4.5 Release 管理

4.6 GitLab Duo AI

4.7 進階：API 直呼

5. 應用場景

5.1 個人日常開發

5.2 CI/CD 整合

5.3 跨多個 GitLab instance 工作

5.4 Self-Managed GitLab 維運

5.5 GitOps 工作流

6. 資安掃描報告

6.1 紅黃綠燈總結

6.2 結論

7. FAQ

8. 進階技巧

8.1 自訂 alias

8.2 與 fzf 串接 — interactive MR picker

8.3 用 glab api 寫腳本

8.4 在 shell prompt 顯示 MR 狀態

8.5 多 host 切換

9. 整合進其他工作流

9.1 與 AI-Knowledge Template 整合

9.2 與 superpowers / dispatching-parallel-agents 串接

9.3 與 gh（GitHub CLI）互補

10. 重點摘要 Checklist

11. 進一步閱讀

Comments