Skip to content
海博賽特
HCYTLOG
RSS
← 文章目次 HCYTLOG / 文章與筆記
更新： Gitlab Rust Dev Open Source

兩天、20 個 commit：我怎麼開始貢獻 GitLab Orbit

保留 2026 年 6 月第一次貢獻 GitLab Orbit 的紀錄：兩天、20 個 commit、4 個 MR。補上 2026-10-08 的 glab 1.117 命令入口、本機 SQL、Local MCP 與 Remote 查詢邊界。

For English readers, switch to the English version.EN
本文目錄

先講背景：我是 GitLab 的社群貢獻者（Community Contributor）。這篇記錄 2026 年 6 月透過 community fork 第一次貢獻 Orbit 的經驗。兩天、20 個 commit、28 個 crate 與 MR 審查過程都保留當時的紀錄；2026-10-08 的操作更新放在「如果你也想貢獻」，不把歷史數字改成現在的規模。

Orbit 是什麼

當時我用一句話理解它：GitLab Orbit 是一個把你的程式碼和開發流程資料變成可查詢圖譜的引擎。

具體一點。你的 repo 裡有程式碼，GitLab 上有 MR、issue、pipeline、deployment 記錄。這些東西散落在不同地方，要回答「誰呼叫了這個函式」「改這個檔案會影響哪些 pipeline」「這個模組的測試覆蓋率如何」這類跨領域問題，你得自己串好幾個 API。

Orbit 做的事是把這些全部索引成一個 property graph（程式碼定義、呼叫關係、繼承鏈、import 圖，加上 MR / issue / pipeline 的 SDLC 資料），然後讓你用 SQL 或 Query DSL 查詢。

它有兩種模式：

  • Orbit Local：單機 CLI，把一個 repo 索引到本機的 DuckDB，不需要 GitLab 帳號。跑一次大概幾秒鐘。
  • Orbit Remote：代管服務，索引整個 GitLab group 到 ClickHouse，搭配授權和 API 端點。

主要使用 Rust，單一 workspace 裡 28 個 crate，支援 11 種以上的程式語言解析（Ruby、Java、Python、TypeScript、Rust、Go、C#、C/C++、Kotlin、Elixir、Bash）。用 tree-sitter 做程式碼解析，OXC 處理 JavaScript/TypeScript。

聽起來很龐大。確實是。但這不代表你不能貢獻。

怎麼找到切入點

我會開始貢獻 Orbit，起因是黑客松。GitLab Transcend Hackathon 有一個 track 是圍繞 Orbit 做應用，我的隊伍做了一個用 Orbit 圖查詢讓 AI code review 變可稽核的工具。做的過程中我一直在翻 Orbit 的原始碼和文件，發現了好幾個可以改善的地方。

第一個切入點通常不是寫 code，是文件。

我在本機跑 Orbit Local 的時候，發現 quickstart 文件假設你已經裝好 GDK（GitLab Development Kit），但其實跑 Local 根本不需要 GDK。很多想貢獻的人可能在這一步就放棄了。所以我寫了一份不需要 GDK 的開發者快速入門指南。

這就是我的第一個 MR。

我的四個 MR

兩天之內我送出了 4 個 MR，類型各不相同：

1. docs/690：Orbit Local 開發者快速入門

最簡單的一個：寫一份從零開始的 quickstart，不假設你有 GDK。涵蓋 protoc 安裝（Linux / macOS / Windows）、build 指令、跑測試、常見問題。

後來 review 的時候 maintainer 提醒我加上 Windows 的 protoc 安裝路徑和 ontology E2E 測試的注意事項。這就是送 MR 的好處：review 過程本身就是學習。

2. feat/847：Java sealed type 的 permits clause 萃取

這個是 Rust 功能開發。Java 17 引入了 sealed class（JEP 409），允許用 permits 關鍵字限制哪些子類別可以繼承。但 Orbit 的 Java indexer 從來沒讀過這個欄位，所以 sealed type 的繼承階層在圖譜裡是斷的。

我做的事：

  • 在 tree-sitter-java 的 AST 裡找到 permits 欄位，寫一個 java_permitted_types() extractor
  • 在 code graph 裡加一個新的 EdgeKind::Permits
  • 在 ontology schema 註冊新的 edge kind
  • 重用既有的 link_extends 名稱解析邏輯（抽成 resolve_disambiguated_targets）
  • 補測試 fixture

改了 13 個檔案、+237/-36 行。聽起來很多，但其實大部分是沿著既有的 pattern 做，Orbit 的 code graph pipeline 設計得很好，加新的 edge kind 有清楚的路徑可以跟。

3. fix/741：Indexer 遇到超長行檔案的 log 修復

這個是典型的「用的時候踩到的 bug」。Orbit 索引 repo 時如果遇到某些行超過限制的檔案會直接跳過，但只在 DEBUG level 記 log。你在 INFO level 跑完，完全不知道有檔案被跳過了。

修法很簡單：在 INFO level 記一行「N 個檔案因為 line_too_long 被跳過」，細節留在 DEBUG。Review 之後 maintainer 建議把 aggregate 拿掉，改成每次跳過時各記一行 DEBUG。很合理的簡化。

4. docs/850：把前置條件整理成隨查即用的參考頁

原本 Orbit 的前置條件散落在好幾份文件裡。我把它們整理成一個獨立的參考頁面，需要的時候查就好，不用在 quickstart 裡塞一大段。

其他零散貢獻

除了這四個主要 MR，我還順手做了幾件事：

  • 幫 Gemini CLI 接 Orbit MCP 端點寫了認證設定文件（原來需要額外指定 mcp_orbit OAuth scope）
  • 加了 Kotlin suspend function 的測試 fixture
  • 更新 v0.74.0 CLI 的文件
  • 寫了 production runbook 的骨架
  • 修了 troubleshooting 頁面的 redirect

總計 20 個 commit，+1,260/-235 行。

上手一個 2,800+ commits 的 Rust 專案沒有想像中難

講幾個我覺得降低門檻的因素：

Orbit 的 code graph pipeline 很模組化。 加一種新的 edge kind，你就跟著 EXTENDS 或 CALLS 的 pattern 走：加 extractor、加 edge kind enum、加 ontology config、加 fixture。每一步都有現成的範例可以照抄。我做 Java permits 的時候，大概 80% 的時間花在搞清楚「現在的 pattern 是什麼」，只有 20% 在寫新的東西。

Orbit Local 不需要複雜的基礎設施。 不用裝 ClickHouse、不用設定 NATS、不用跑 GDK。一個 cargo build 就可以開始。在本機跑一次索引只要幾秒鐘，改 code → 跑測試的迴圈很快。

文件貢獻是真正的貢獻。 不要覺得「只是寫文件」不算什麼。我的 quickstart MR 收到的 review 回饋跟 Rust code MR 一樣認真。對一個還在快速成長的專案來說，降低新人門檻的文件很有價值。

Maintainer 的 review 很有建設性。 每個 MR 我都學到東西。feat/847 的 review 讓我把 permits edge 從獨立方向改成跟 EXTENDS 反向對齊（更符合圖的語意）。fix/741 的 review 讓我理解 log level 設計的取捨。這種 review 品質是你自己寫 side project 拿不到的。

如果你也想貢獻

幾個建議：

  1. 先跑 Orbit Local。 原文的 glab orbit local index . 與 glab orbit local sql 是六月使用的命令形狀。現在照下面的版本與指令先索引自己的 repo，再查幾個 query。碰到的問題可能就是第一個 MR。

  2. 從 issue 列表開始。 Orbit 的 issue tracker 有標 good first issue 的項目，通常是文件、小修復、或加新語言的 test fixture。

  3. 文件永遠缺人寫。 特別是安裝步驟、平台差異、常見錯誤處理。你踩過的坑就是別人的 MR。

  4. 用 community fork 提交。 GitLab 社群貢獻者透過 community fork 送 MR，流程跟一般的 GitLab MR 一樣。

  5. 不要怕 Rust。 如果你有其他語言的經驗，Orbit 的 Rust code 讀起來沒有想像中可怕。特別是 code graph 那塊，大部分是 tree-sitter AST 操作和 pattern matching，不需要深入 lifetime 或 async 的黑魔法。

2026-10-08 更新：安裝與本機查詢

現在的官方 glab 文件使用一層命令樹：glab orbit index、glab orbit sql，需要 glab 1.117 以上。下面是依文件調整的步驟；這次補充沒有重新安裝 binary 或實跑索引。

# 先確認 glab >= 1.117，再安裝由 glab 管理的 Orbit binary
glab version
glab orbit --install
glab orbit version

# 換到你的 repo，索引目前工作目錄，再查本機圖譜
cd /path/to/your/repo
glab orbit index .
glab orbit schema
glab orbit sql 'SELECT count(*) FROM gl_definition'

binary 安裝完成後，Local 的 index、sql 等命令在本機處理，不需要 GitLab 帳號或網路，也不消耗 GitLab Credits。它索引目前工作樹；換 branch 後要重新索引，不能把舊圖當成新分支的結果。預設 DuckDB 在 ~/.gitlab/orbit/graph.duckdb。從已索引的 repo 執行 SQL 會限定到該 checkout；在 repo 外查則涵蓋所有已索引的 commit。工作樹與索引行為有完整說明。

2026-10-08 更新：接 agent 時分清 Local 與 Remote

要讓 agent 查本機圖譜，可以依官方 Local MCP 文件使用 glab orbit mcp serve。它是 stdio server，不是貼一條遠端 URL 就能連線；提供 index、get_graph_schema 與唯讀的 run_sql。Local MCP 目前仍標示 experiment，Local 本身則是 beta，不能把兩者都當成正式穩定介面。

glab orbit setup 可以協助整合 agent，但會寫入 agent 的指令檔並安裝 Orbit skill。先看 glab orbit setup --help，確認要設定的 agent 與專案／使用者範圍，再執行；單純想試 SQL，不需要先改這些設定。

Remote 查詢仍需要 GitLab 認證與網路，glab orbit query 用的是 hosted graph 的 Query DSL，也會消耗 Credits。本機 SQL 查到的程式碼關係不等於已經取得整個 GitLab group 的 issue、MR 與 pipeline 資料。六月的貢獻故事可以照讀，要開始操作就以這組新入口和實際安裝版本為準。

最後

兩天、20 個 commit、4 個 MR。回頭看，門檻真的沒有我想像中高。

Orbit 是一個很有意思的專案：把程式碼分析和 SDLC 資料統一成可查詢的圖譜，這個方向對 AI 輔助開發來說會越來越重要。而且它還在快速成長中（支援的語言一直在加、query 能力一直在擴充），現在加入剛好。

如果你對程式碼分析、知識圖譜、或 Rust 有興趣，GitLab Orbit 是一個很好的貢獻目標。歡迎在社群裡碰面。