GitLab: Issue Templates & Merge Request Templates

本系列文是從 iT 邦幫忙鐵人賽系列文章搬至 gitlab-book.tw,鐵人賽撰文時 GitLab 仍為 12.x 版本,因此本系列文內容已有部分過期,本次搬移至此後,會視狀況新增一些補註說明。

本系列文是從 iT 邦幫忙鐵人賽系列文章搬至 gitlab-book.tw,鐵人賽撰文時 GitLab 仍為 12.x 版本,因此本系列文內容已有部分過期,本次搬移至此後,會視狀況新增一些補註說明。 鐵人賽原文網址:https://ithelp.ithome.com.tw/articles/10223168

隨著我們假想情境中的團隊日漸茁壯,產品的開發也正邁入軌道。在這個時候,團隊成員開始覺得工作流程中有一些地方需要持續改善。

首先提出意見的是 PM 與 QA,他們覺得每次開 Issue 都要按著規定的格式填寫,不知道有沒有方法可以讓他們節省一些時間?

Issue templates

很幸運的,GitLab 提供了 Issue Templates 的功能,透過它能為 Project 的 New Issue 建立範本,藉此減少一些繁瑣的輸入作業。

建立並使用 Issue templates

首先在 Project 的 default branch 建立 .gitlab/issue_templates/ 資料夾,接著以 Markdown 格式撰寫 Templates,例如下面的兩個範例:

bug.md

Bug 標題:

狀況描述:

Assign:
/assign

Due Date:
/due 

Milestone:
/milestone %

Label:
/label ~"Bug" 

feature.md

Feature 標題:

功能描述:

Assign:
/assign

Due Date:
/due 

Milestone:
/milestone %

Label:
/label 

將上述檔案存檔至 .gitlab/issue_templates/ 並且送進 Project 的 default branch。接著 GitLab 就會自動讀取該檔案,並且在建立 New Issue 時,讓你可以選擇想要套用的 Issue Templates。

如下圖,New Issue 的介面會自動出現一個新的選項,讓你 Choose a template


(可以建立多個 Issue template,在建立 Issue 時,即可根據狀況套用合適的 template。Template 的名稱即是 Markdown 檔案的檔名。)

一但選擇了 Template 就會如下圖一樣,在 Description 會自動出現 Template 的內容。另外別忘了 GitLab 有 Quick Actions 的功能,因此也可以如上述範例一樣,在 Template 中事先預備好常用的 Quick Actions,減少手動操作 UI 的繁瑣動作,快速的填寫 Issue 的 AssignMilestoneLabel


(善用 Quick Actions 可以減少用滑鼠點選 UI 的動作。)

Merge Request Templates

在 PM 與 QA 之後,Developer 也表達他覺得每次 Merge request 都要手動複製貼上固定的格式有點煩,既然 Issue 有 Templates,那麼 Merge Request 應該也能比照辦理吧?

沒錯,GitLab 也有 Merge Request Templates 的功能,使用方式也完全雷同。

建立並使用 Merge Request Templates

一樣在 Project 的 default branch 建立 .gitlab/merge_request_templates/ 資料夾,接著以 Markdown 格式撰寫 Templates,例如下面的範例:

相關 Issue: Closed #

Assign:
/assign

Due Date:
/due 

Milestone:
/milestone %

Label:
/label ~"Dev Leader" 

將上述內容存檔為 .gitlab/merge_request_templates/merge.md 並且送進 Project 的 default branch。同樣的 GitLab 就會自動讀取該檔案,讓你可以選擇想要套用的 Templates。

如下圖,New Merge Request 的介面會自動出現一個新的選項,讓你 Choose a template

同樣的操作方法,同樣可善用 Quick Actions 減少部分繁瑣操作。

再次提醒,Templates 要存放在 default branch 的指定資料夾內,如下圖範例 default branch 為 master,而 Templates 都分別存放在 .gitlab/issue_templates/.gitlab/merge_request_templates/ 裡面。

【新增補充】因應世界潮流,現在多半會建議將 default branch 從 master 改為 main


(上圖是 GitLab 提供的 Web IDE,臨時要修改 Project 的檔案,但手邊的電腦又沒有慣用的 IDE 時,也可以用用看。Web IDE 可以編修多個檔案,並且直接 Commit & Push 至 Project。)

小結

今天介紹的 New Issue 與 New Merge Request Templates,我覺得是 GitLab 提供的一項貼心小功能。這功能對於有一定工作規定與默契的團隊來說,應該是個不錯的幫手,能減少一些操作 GitLab 時的例行作業。其中特別要再次推薦 GitLab 的 Quick Actions,因為 Template 其實本身只是一個 Markdown,而真正讓 Template 變得好用的其實是 Quick Actions,善用 Quick Actions 才能發揮 Template 真正的價值。

參考資料