ELI5 · GitHub

issue 裡的 Projects 是什麼?

一塊白板。單子變成卡片貼上去,做到哪就往右邊移一格。

📋
它回答的是「現在做到哪一步」

單子本身還是那張單子。
Projects 只是幫它找一塊白板站著,然後看它站在哪一欄。

它長這樣

我的 3 月工作板
待辦
#24
改文件
#25
加深色模式
進行中
#23
寫測試
完成
#21
登入頁
#22
接 API

你在 issue 右邊看到的 Projects 那一欄,
就是在問:這張單子要貼到哪一塊白板上?

拖動卡片,repo 一個字都不會變

這是最容易誤會的一點。
卡片的位置存在白板裡,不是存在單子裡,更不是存在程式碼裡。

會變的

白板上卡片從「待辦」移到「進行中」
白板的篩選、排序、統計跟著變

不會變的

issue 的標題、內容、留言
repo 裡的任何一個檔案
issue 是開著還是關著

所以「移到完成」不等於「關掉這張單子」。 這兩件事是分開的。不過 GitHub 有一條預設規則幫你補上另一半——下面會講。

跟 milestone 差在哪

你昨天學的 milestone 是飛機,這個是白板
一個管時間,一個管狀態。

✈️
milestone

什麼時候之前要交?

只在同一個 repo 裡
一張單子只能有一個
有到期日、有進度條
長得像一班飛機
📋
Projects

現在做到哪一步?

掛在帳號或組織底下,可以跨 repo
一張單子可以貼在好幾塊板上
沒有到期日這個內建概念
長得像一塊白板,或一張表
兩個可以同時用,而且常常一起用: milestone 說「這批要三月交」,白板說「這批裡面誰已經動工了」。

同一張單子可以貼在好幾塊白板上

#23
寫測試
我的 3 月工作板看個人進度
團隊路線圖看整季規劃

這跟 milestone 剛好相反。
白板是掛在你的帳號底下的,所以同一塊板可以收不同 repo 的單子。

還能加自己的欄位,變成一張表

白板不只有「狀態」一欄。
你可以自己開欄位,然後切換成表格檢視來排序和篩選。

單子狀態 優先度估幾天負責人
#23 寫測試進行中 2
#24 改文件待辦 1
#25 加深色模式待辦 3
後面三欄(優先度、估幾天、負責人)是自己開的,GitHub 沒有內建。 這是白板真正厲害的地方:標籤和 milestone 都做不到這種自訂欄位。

有兩條規則一開始就替你開好了

你不用自己設定,新白板一建立就有這兩條

單子關掉 → 自動移到「完成」

issue 或 PR 被關閉的時候,卡片自己跑到 Done 那一欄。

PR 合併 → 自動移到「完成」

PR 被 merge 的時候也一樣,不用手動拖。

所以只要你在 PR 裡寫了 Closes #23,合併之後會連鎖發生三件事: PR 合併 → issue 自動關閉 → 白板上的卡片自動移到完成。 一次都不用手動。

放回四種分類方式裡看

🏷️
label

這是什麼性質的事?

🧩
sub-issue

這件大事由哪幾件小事組成?

✈️
milestone

什麼時候之前要交?

📋
Projects

現在做到哪個階段了?

你現在打這個指令一定會失敗

✗ gh 的預設權限不包含 Projects

人家剛剛在你這台電腦上實際跑過 gh project list, 回來的是 missing required scopes也就是權限不夠

這不是壞掉,是 GitHub 把 Projects 的權限獨立出來了,要自己加上去:

gh auth refresh -s project

跑完會開瀏覽器讓你按同意,之後下面的指令才會動。

指令

加完權限之後可以用的:

gh project list --owner @me            # 我有哪些白板
gh project create --owner @me --title "3 月工作板"
gh project view 1 --owner @me --web    # 直接用瀏覽器打開
gh project item-add 1 --owner @me --url <issue 網址>
gh project item-list 1 --owner @me     # 這塊板上有哪些卡片
gh project field-list 1 --owner @me    # 這塊板有哪些欄位
指令裡那個 1白板的編號,不是 issue 編號。 每塊板有自己的一組號碼,從 1 開始數。

想再深入一點