跳轉至

GitHub 整合

介紹

外掛功能：透過簡單的安裝和配置，研發同學可以將GitHub的Branch、commit、PR和Meegle的工作項進行關聯，並可透過merge 事件自動流轉節點/狀態。

名詞解釋

  • 關聯：指將 GitHub 資訊與Meegle資訊進行關聯，關聯成功後，可在需求/缺陷等工作項中看到關聯的 branch/commit/PR；
  • 流轉：在關聯的基礎上，透過MR的狀態變化自動流轉工作項的節點/狀態，無需人工點選；
  • 分端流轉：各端（前端/後端...）只流轉各自端對應的節點/狀態。

安裝/升級

操作人：Meegle空間管理員

安裝新外掛

在【Meegle】中，前往空間配置 → 外掛管理 → 右上角新增外掛；

Y3uiKaPi

選擇對應的外掛「新增外掛」；

to7QR4nb

配置 Webhook

支援配置某個倉庫的Webhook，配置好後，該倉庫可正常使用本外掛，與Meegle聯動； 支援配置某個Organization的Webhook，配置好後，該組織下的所有倉庫可正常使用本外掛，與Meegle聯動；

  1. 【Meegle】在外掛中選擇「複製 URL」；

fHlxH0vc

  1. 【GitHub】登入 GitHub 後，點選進入對應的倉庫，Tab頁 Setting → Webhooks 選項；

    content type需要選擇為“application/json”

abcc9b10f-0f4a-4304-a558-7fb2d878d1a6

  1. 將1複製的 URL 貼上到 GitHub 的 Webhook 中的 URL 選項中，勾選「Pushs」、「Pull requests」後點選下方的「Add webhook」完成 webhook 關聯。

Fq6d33xH

外掛配置

操作人：【Meegle】空間管理員

訴求一：只關聯不流轉

無需再做任何配置，安裝外掛，配置 Webhook ，即可參照關聯方式去做關聯。

訴求二：關聯且流轉

新建規則

前往「空間配置 → 外掛 → GitHub 外掛」，點選「新增流轉規則」按鈕進入新建規則彈窗。

vKkRHatj

選擇工作項型別

選擇需要流轉的工作項型別，如需求 > 業務需求模板；

D0zsGmwK

配置一條倉庫&節點對映關係

鎖定流轉訊號來源，多端分別流轉看這裡：

  1. 點選「選擇倉庫」，選擇本條驅動規則的需要從哪個 GitHub 倉庫觸發：

rmay40wc

  1. 任意倉庫，無需分端流轉：選擇「任意倉庫」，代表在關聯的基礎上，任意倉庫的MR訊號，都可流轉工作項需求；
  2. 安全考慮，統一用特定倉庫：輸入特定倉庫的名稱（含namespace），按回車，並選中；配置好後，只有特定倉庫來的流轉訊號，才會驅動流轉節點/狀態。
  3. 多端節點/狀態，分別驅動流轉：首先，確定各端（前端/後端/...）倉庫相互獨立，不共用；然後，每條對映關係中，只配置某個端的倉庫名稱（含namespace），一個端有多個倉庫的，可注意新增；
  4. 配置好後，不同的倉庫訊號將會驅動流轉不同的節點/狀態；

注意倉庫名稱要帶 namespace。

選擇 GitHub 事件

「Pull Request 完成/建立」事件，選擇即可；

vzMzt8TT

選擇流轉的節點/狀態

配合上述完成對應節點/狀態的配置，如XXX 倉庫 的Pull Request完成時，服務端MR 節點完成

如需要一次性流轉多個連續序列的節點，可在此處多選； 注意：缺陷型別的工作項，建議不要多選，因為狀態流轉存在環路，流轉結果會不穩定。

OFJGbfn6

選擇必填模式

僅限節點流使用，如需求，是否卡點看這裡下方。

nHMJjCW1

關聯 PR 才能流轉工作項
  • 開關開啟，將為對應流轉的節點新增必填欄位，僅當關聯的 PR merged 後，該欄位才能變成「已透過」，節點才可流轉透過；
  • 使用場景：使開發流程規範化等；
  • 缺點：較為生硬，如果沒有關聯 PR merged 訊號流入，該欄位值將阻塞節點流轉，e.g.某些需求/缺陷不涉及研發倉庫修改；

54iU7rv5

自動流轉 + 手動流轉

開關關閉，代表模板中不會生成欄位，外掛將在滿足條件時驅動節點/狀態流轉透過，同時使用者也可手動點選流轉透過，不會阻塞流轉；同時因為沒有生成欄位，例項無需升級模板也可生效； 使用場景：提高研發/測試同學流轉節點的效率，在支援手動流轉的基礎上，外掛幫助自動流轉； 缺點：無法透過必填來形成開發規範。

自定義規則

a869d8f02-6b51-4a75-bc35-74d028560c31

自定義字首

  • 主要用於PR 關聯、commit 關聯、Branch 關聯
  • 使用方式參考：【訴求一：只關聯不流轉】-【在GitHub中透過以下方式關聯（任選其一）】

驅動關鍵字

  • 主要用於MR - merged 事件自動流轉節點/狀態
  • 使用方式參考：【訴求二：自動流轉】

儲存規則

點選「建立」儲存規則，規則預設啟用，後續可參照自動流轉方式進行關聯+自動流轉。

刪除規則

如果修改過程中發現模板已刪除的，代表規則已不再生效，建議點選刪除按鈕，刪掉這條規則。

rfaZIWCN

如果修改過程中發現節點/狀態已刪除的，可能還有存量資料使用這些節點/狀態，如果想對存量資料保持作用，則無需修改。

刪除外掛

如需刪除外掛，可以點選「刪除」按鈕，刪除後，外掛將不再展現，同時相關資料會全部清空，需重新新增並進行重新配置，請謹慎操作。 如果之前開啟了必填模式，注意存量工作項中的還會有必填欄位，可以透過在詳情頁升級版本去除。

外掛使用

操作人：【Meegle】使用者

訴求一：只關聯不流轉

外掛安裝後，配置好Webhook後，研發同學即可透過commit、branch、PR 關聯需求/缺陷等工作項，具體操作如下：

工作項詳情頁，快捷鍵複製ID

  • Windows: Ctrl + Shift + C
  • IOS： Cmd + Shift + C 也可透過介面點選獲取，如下圖：

p9dW3Bj9

在GitHub中透過以下方式關聯（任選其一）

PR 關聯

新建/編輯MR時，在MR的標題、描述中用關聯語法進行關聯；

  • 任何狀態都可關聯（opened、closed）
  • 可在標題、描述中關聯
  • 支援編輯、修改

3a58AZ4c

commit 關聯

commit message 中，用關聯語法進行關聯；注意這裡是一次性設定，無法修改。

gkgcAX1p

命令列關聯，單個需求、缺陷等工作項例項進行關聯時： 選擇多個需求、缺陷等工作項例項進行關聯時：

Branch 關聯

新建branch時，用關聯語法進行關聯；注意這裡的關聯屬於一次性關聯，無法修改，同樣一個開發分支可能對映多個需求、缺陷，不方便管理。 介面關聯：

IgBMNcEO

命令列關聯： 選擇多個需求、缺陷等工作項例項進行關聯時：

關聯語法

m-/M-/f-/F-workitemID ，如 m-439945

  • 大小寫不限
  • 位置不限
  • 一次性關聯多個時，用‘,’分隔即可

fq0TqHaG

關聯效果

完成關聯後，Meegle會收到相應的訊號，在對應的需求、缺陷等工作項例項的「GitHub程式碼分支」標籤頁展示對應資訊；

48TTLwnM

訴求二：自動流轉

配置對應流轉規則後，可透過 merged 事件自動流轉節點/狀態。

使用方式

新建/編輯PR時，在 PR 的標題、描述中填寫下方流轉語法，即可在該 MR 完成 merged 時，自動流轉對應工作項或節點。

resolve m-/M-/f-/F-workitemID ，如 resolve m-439945

  • 後續當 PR 狀態變更為 merged 時，關聯的工作項將根據配置規則自動流轉；
  • 若關聯時 PR 狀態已為 merged，則在關聯成功的瞬間觸發流轉；

  • 如果測試訊號沒有變綠，可以先流轉節點為進行中狀態。 除 resolve 之外，還支援以下詞：

  • Close：Close, Closes, Closed, Closing, close, closes, closed, closing

  • Fix：Fix, Fixes, Fixed, Fixing, fix, fixes, fixed, fixing

  • Resolve：Resolve, Resolves, Resolved, Resolving, resolve, resolves, resolved, resolving 以上關鍵詞不區分大小寫：

  • 整個流轉結構體，在標題、描述中的位置不限，即resolve m-439945可放在標題/描述中的任意位置；

  • 一次性流轉多個時，用‘,’分隔即可，如resolve m-439945, m-439946，即可實現 merged 後自動流轉兩個工作項。

bzfMRN3V

1GyvOdCH

FAQ

是否支援私有化部署的 GitHub？

支援，只要私有化版本可以和外網通訊且支援 HTTPS 即可使用。

為什麼配置之後沒有生效？

如果是私有化部署，考慮網路環境沒有互通，請檢查內網環境問題。如果非私有部署，考慮相關服務阻斷了連結，請等待相關服務恢復。

為什麼 PR 已 merged, 但沒有 GitHub 訊號

Check list ：

  • 規則配置是否完整；
  • 關聯規則中是否設定為必填；
  • 模板中的節點是否存在（有可能被其他管理員修改過）；
  • 是否升級了模板（若關聯配置是後新增的話，需要在前端升級模板，才能生效）；
  • MR 中是否使用流轉語法。
  • 流轉規則是否設定了倉庫條件。如有，檢查倉庫名稱是否匹配。注意：倉庫名稱嚴格區分大小寫。

是否可以配置分端（前端/後端/...）流轉？

可以配置多端分別驅動節點/狀態流轉：

  1. 確定各端（前端/後端/...）倉庫相互獨立，不共用；
  2. 每條對映關係中，只配置某個端的倉庫名稱（含namespace），一個端有多個倉庫的，可逐一新增。

關聯 GitHub Tab 何時展示？

  1. 配置了流轉規則的工作項一定會展示 Github tab；
  2. 未配置流轉規則的工作項，如果在倉庫端透過命令進行了關聯，被關聯的工作項例項會展示 GitHub tab。

點選解綁未報錯但是重新整理還在？

解綁操作必須是當前工作項的建立人、角色人員、或當前負責人才可以。 git commit -m "m-需求ID" git commit -m "m-需求ID,f-缺陷ID" git branch m-需求ID git branch m-需求ID,f-缺陷ID