皆様こんにちは。SEの小池と申します。
GitLabではマージリクエストやイシューを作成する際は、それらを "説明" する文章を入力できます。
説明欄に適切な事項を記載することで、そのマージリクエストやイシューの概要画面を見ただけでどういった意図で変更したのか、といった情報を把握することができます。
ですがこの説明欄は、個人で自由に入力していると記載内容やレベル感がバラバラになってしまいがちです。
そんな問題を解決するために、このブログではGitLabのマージリクエストの説明欄にデフォルトのテンプレートを設定する方法を紹介いたします。
なお、ほぼ同じような手順でイシューの説明のテンプレートも作成・設定可能です。ただ、文字数が多くなりすぎるので本ブログではマージリクエストについてのみ記載致します。
- 本記事の対象の方
- 今回のブログのゴール
- このブログをお読みいただくにあたっての事前ご連絡事項
- 適用範囲と実装方法の概要
- 手順A : リポジトリにテンプレートファイルを作成する
- 手順B : プロジェクトの [設定] で直接テンプレートを指定する (プレミアム以上)
- 手順C : グループ単位でマージリクエストの説明のテンプレートを設定する (プレミアム以上)
- 手順D : インスタンス単位でマージリクエストの説明のテンプレートを設定する (プレミアム以上 且つ オンプレミス)
- 手順E : 動作確認
- 最後に
本記事の対象の方
- GitLabのマージリクエストの説明欄に規定のフォーマットを使いたい方。
今回のブログのゴール
このブログのゴールはこちらです。
- GitLabのマージリクエストの説明欄に規定のテンプレートを設定する
このブログをお読みいただくにあたっての事前ご連絡事項
- 本記事はオンプレミス版 (Self-Managed) のGitLab Enterprise Edition 14.10.4-ee (Ultimate) における仕様をベースに記載しております。それ以外のエディションやバージョンではこの記事に記載の通りではない可能性がございます。
- 本記事ではGitLabにおけるマージリクエストの概要 及び 用途については記載しておりません。これについては恐れ入りますがGitLabのドキュメント (こちら) をご参照ください。
- 本記事の例ではテンプレートをマークダウン書式で作成します。マークダウン書式の書き方については、マークダウン公式のチートシート (こちら) をご参照ください。
- 本記事ではGitLabのクイックアクションは使用しておりません。クイックアクションの紹介と、テンプレートにクイックアクションを組み込む例については後日公開するブログにてご紹介する予定です。
- 本記事のGitLabのGUIは日本語にローカライズした状態で掲載しております。それ以外の言語をご利用の方は適宜読み替えてください。
適用範囲と実装方法の概要
マージリクエストの説明欄に適用するテンプレートは、プロジェクト単位、グループ単位、インスタンス単位で設定が可能です。
ただし、グループ単位のテンプレートはプレミアム以上でのみ、インスタンス単位のテンプレートはプレミアム以上 且つ オンプレ版 (Self-Managed) の場合のみ利用可能です。
本ブログでは以下の4つの実装方法について記載しております。
- 実装方法A：プロジェクト単位 (無償版でも可。Default.mdを作成する。)
- 実装方法B：プロジェクト単位 (プロジェクトの設定で直接作成する。)
- 実装方法C：グループ単位
- 実装方法D：インスタンス単位 (Self-Managed版のみ。)
適用のスコープ、利用形態 (SaaS or Self-Managed) 、有償版か無償版かによって選定方法が異なります。
以下の図を参考に実装方法をご検討ください。
それぞれの実装方法の概要と、必要な手順は以下の表の通りです。
| 実装方法 | 実装方法の概要 | 手順 |
|---|---|---|
| A | プロジェクト単位でテンプレートを適用する。 リポジトリに直接テンプレートとなる Default.mdファイルを作成する。全ティアで設定可能。(無料版でも設定可能。) |
①ﾃﾝﾌﾟﾚｰﾄﾌｧｲﾙ作成(手順A) ②確認(手順E) |
| B | プロジェクト単位でテンプレートを適用する。 プロジェクトの [設定] > [一般] > [マージリクエスト] に直接設定する。 プレミアム以上でのみ設定可能。 |
①ﾌﾟﾛｼﾞｪｸﾄの設定(手順B) ②確認(手順E) |
| C | グループ全体にテンプレートを適用する。 グループ配下のプロジェクトのリポジトリに、テンプレートとなる Default.mdファイルを作成する。その後、グループの [設定] から、テンプレートファイルを作成したプロジェクトを指定する。 プレミアム以上でのみ設定可能。 |
①ﾃﾝﾌﾟﾚｰﾄﾌｧｲﾙ作成(手順A) ②ｸﾞﾙｰﾌﾟの設定(手順C) ③確認(手順E) |
| D | インスタンス全体にテンプレートを適用する。 任意のプロジェクトのリポジトリに、テンプレートとなる Default.mdファイルを作成する。その後、インスタンスの [設定] から、テンプレートファイルを作成したプロジェクトを指定する。 プレミアム以上 且つ オンプレ版 (Self-Managed) でのみ設定可能。 |
①ﾃﾝﾌﾟﾚｰﾄﾌｧｲﾙ作成(手順A) ②ｲﾝｽﾀﾝｽの設定(手順D) ③確認(手順E) |
次の章から 手順A ～ 手順E について紹介いたします。
実装なさりたい方法で必要な手順を上の表でご確認いただき、実施してください。
なお、これ以降ご紹介する手順はGitLab Docsにも記載がありますので、さらに詳細を確認なさりたい場合はそちらをご参照ください。
参考 : Description templates | GitLab
手順A : リポジトリにテンプレートファイルを作成する
本章では、リポジトリにマージリクエストの説明欄で使うテンプレートとなるファイルを作成します。
本章の手順は、本ブログで紹介している４つの実装方法のうち、実装方法:A,C 及び D で必要な手順となります。(下の表の黄色いセルの赤字部分。)
| 実装方法 | 実装方法の概要 | 手順 |
|---|---|---|
| A | プロジェクト単位でテンプレートを適用する。 リポジトリに直接テンプレートとなる Default.mdファイルを作成する。全ティアで設定可能。(無料版でも設定可能。) |
①ﾃﾝﾌﾟﾚｰﾄﾌｧｲﾙ作成(手順A) ②確認(手順E) |
| B | プロジェクト単位でテンプレートを適用する。 プロジェクトの [設定] > [一般] > [マージリクエスト] に直接設定する。 プレミアム以上でのみ設定可能。 |
①ﾌﾟﾛｼﾞｪｸﾄの設定(手順B) ②確認(手順E) |
| C | グループ全体にテンプレートを適用する。 グループ配下のプロジェクトのリポジトリに、テンプレートとなる Default.mdファイルを作成する。その後、グループの [設定] から、テンプレートファイルを作成したプロジェクトを指定する。 プレミアム以上でのみ設定可能。 |
①ﾃﾝﾌﾟﾚｰﾄﾌｧｲﾙ作成(手順A) ②ｸﾞﾙｰﾌﾟの設定(手順C) ③確認(手順E) |
| D | インスタンス全体にテンプレートを適用する。 任意のプロジェクトのリポジトリに、テンプレートとなる Default.mdファイルを作成する。その後、インスタンスの [設定] から、テンプレートファイルを作成したプロジェクトを指定する。 プレミアム以上 且つ オンプレ版 (Self-Managed) でのみ設定可能。 |
①ﾃﾝﾌﾟﾚｰﾄﾌｧｲﾙ作成(手順A) ②ｲﾝｽﾀﾝｽの設定(手順D) ③確認(手順E) |
実装方法によって手順が微妙に異なる場合はその旨を記載しておりますので、実装方法にあった手順を実施いただけますようお願い申し上げます。
Developer以上のロールを持つユーザーでGitLabにサインインします。
テンプレートファイルを作成したいプロジェクトのトップページで、デフォルトブランチが選択された状態で [+] > [新規ファイル] をクリックします。
ファイル名の入力ボックスに.gitlab/merge_request_templates/Default.mdを入力します。
この時、ファイル名をDefault.mdとすることで、これがデフォルトテンプレート (規定のテンプレート) として認識されます。
- テンプレートのファイル名を
Default.md以外にすると、このテンプレートは規定のテンプレートとはならず、任意に使用可能なテンプレートとなります。
マージリクエスト作成画面にて、説明欄の上のプルダウンからこのテンプレートを明示的に選択することで、説明欄にテンプレートを適用することができます。
- プレミアム以上のティアを利用中の場合において、テンプレートのファイル
Default.mdが存在していて、且つ プロジェクトやグループの [設定] でテンプレートを指定している場合、優先される設定についてはGitLab Docs (こちら) をご参照ください。
テンプレートに適用したい内容をマークダウン書式で記載します。
サンプルがGitLab Docsに載っておりますので、ご参考になさってください。
参考 : Description templates - example-description-template | GitLab
このブログでは例として、GitLab Docsのサンプルを日本語化してみた内容を設定致しました。
筆者は開発経験がないので、実際の開発現場ではあり得ないような内容かもしれません・・・。
## 概要 発生したバグや要望の概要。 ## 再現手順 問題の再現手順。 ## サンプルプロジェクト 問題の挙動を示すサンプルプロジェクトがある場合は、そのプロジェクトへのリンク。 ## 現在の挙動 ## 期待する挙動 ## 関連するログやスクリーンショット コードを直接貼り付ける場合はコードブロック (```) を使ってはりつけてください。 ## 想定される修正点 既に修正箇所が分かっている場合は、問題の原因となっているコードの行にリンクしてください。
任意のコメントを入力し、デフォルトブランチにコミットします。
なお、この際ユーザーのロールによっては直接デフォルトブランチにコミットできないので、その場合はマージリクエストを作成してデフォルトブランチにコミットしてください。
以上でマージリクエストの説明欄に適用するテンプレート作成は完了です。
実装方法:A の場合は、これで設定は完了です。手順E : 動作確認 を実施して作成したテンプレートがデフォルト (規定) のテンプレートとなっていることを確認してください。
実装方法:C の場合は、続けて手順Cを実施してください。
実装方法:D の場合は、続けて手順Dを実施してください。
手順B : プロジェクトの [設定] で直接テンプレートを指定する (プレミアム以上)
本章では任意のプロジェクトの [設定] に直接、マージリクエスト作成時の説明欄で使用するテンプレートを設定します。
本手順は今回ご紹介する実装方法のうち、実装方法 : B でのみ必要な手順となります。(下の表の黄色いセルの赤字部分。)
| 実装方法 | 実装方法の概要 | 手順 |
|---|---|---|
| A | プロジェクト単位でテンプレートを適用する。 リポジトリに直接テンプレートとなる Default.mdファイルを作成する。全ティアで設定可能。(無料版でも設定可能。) |
①ﾃﾝﾌﾟﾚｰﾄﾌｧｲﾙ作成(手順A) ②確認(手順E) |
| B | プロジェクト単位でテンプレートを適用する。 プロジェクトの [設定] > [一般] > [マージリクエスト] に直接設定する。 プレミアム以上でのみ設定可能。 |
①ﾌﾟﾛｼﾞｪｸﾄの設定(手順B) ②確認(手順E) |
| C | グループ全体にテンプレートを適用する。 グループ配下のプロジェクトのリポジトリに、テンプレートとなる Default.mdファイルを作成する。その後、グループの [設定] から、テンプレートファイルを作成したプロジェクトを指定する。 プレミアム以上でのみ設定可能。 |
①ﾃﾝﾌﾟﾚｰﾄﾌｧｲﾙ作成(手順A) ②ｸﾞﾙｰﾌﾟの設定(手順C) ③確認(手順E) |
| D | インスタンス全体にテンプレートを適用する。 任意のプロジェクトのリポジトリに、テンプレートとなる Default.mdファイルを作成する。その後、インスタンスの [設定] から、テンプレートファイルを作成したプロジェクトを指定する。 プレミアム以上 且つ オンプレ版 (Self-Managed) でのみ設定可能。 |
①ﾃﾝﾌﾟﾚｰﾄﾌｧｲﾙ作成(手順A) ②ｲﾝｽﾀﾝｽの設定(手順D) ③確認(手順E) |
本手順の設定は、プレミアム以上をご利用時のみ可能です。
また、この手順は以下の前提を満たしている必要があります。
対象プロジェクトで [設定] > [一般] をクリックし、[可視性、プロジェクトの機能、権限]を展開します。課題またはマージ リクエストが、アクセス権のある全員またはプロジェクト メンバーのみに設定されていることを確認します。
出典 : Description templates - Set a default template for merge requests and issues | GitLab
対象プロジェクトに対してMaintainer以上のロールを持つユーザーで、GitLabにサインインします。
サインイン後、対象プロジェクトのページで [設定] > [一般] をクリックし、マージリクエストの [展開] をクリックします。
展開して表示された設定値の一番下にマージリクエストの、デフォルトの説明テンプレートという設定項目があるので、そこにテンプレートを直接入力します。
入力後は [変更を保存] をクリックします。
画面上部に「プロジェクトは正常に更新されました。」と表示されることを確認します。
以上がプロジェクトの [設定] で直接テンプレートを指定する手順でした。
続けて手順E : 動作確認 を実施して、作成したテンプレートがデフォルト (規定) のテンプレートとなっていることを確認してください。
手順C : グループ単位でマージリクエストの説明のテンプレートを設定する (プレミアム以上)
本章では、対象のグループに対してマージリクエストの説明のデフォルト (規定) のテンプレートを指定します。
本手順は今回ご紹介する実装方法のうち、実装方法 : C でのみ必要な手順となります。(下の表の黄色いセルの赤字部分。)
| 実装方法 | 実装方法の概要 | 手順 |
|---|---|---|
| A | プロジェクト単位でテンプレートを適用する。 リポジトリに直接テンプレートとなる Default.mdファイルを作成する。全ティアで設定可能。(無料版でも設定可能。) |
①ﾃﾝﾌﾟﾚｰﾄﾌｧｲﾙ作成(手順A) ②確認(手順E) |
| B | プロジェクト単位でテンプレートを適用する。 プロジェクトの [設定] > [一般] > [マージリクエスト] に直接設定する。 プレミアム以上でのみ設定可能。 |
①ﾌﾟﾛｼﾞｪｸﾄの設定(手順B) ②確認(手順E) |
| C | グループ全体にテンプレートを適用する。 グループ配下のプロジェクトのリポジトリに、テンプレートとなる Default.mdファイルを作成する。その後、グループの [設定] から、テンプレートファイルを作成したプロジェクトを指定する。 プレミアム以上でのみ設定可能。 |
①ﾃﾝﾌﾟﾚｰﾄﾌｧｲﾙ作成(手順A) ②ｸﾞﾙｰﾌﾟの設定(手順C) ③確認(手順E) |
| D | インスタンス全体にテンプレートを適用する。 任意のプロジェクトのリポジトリに、テンプレートとなる Default.mdファイルを作成する。その後、インスタンスの [設定] から、テンプレートファイルを作成したプロジェクトを指定する。 プレミアム以上 且つ オンプレ版 (Self-Managed) でのみ設定可能。 |
①ﾃﾝﾌﾟﾚｰﾄﾌｧｲﾙ作成(手順A) ②ｲﾝｽﾀﾝｽの設定(手順D) ③確認(手順E) |
本手順の設定は、プレミアム以上をご利用時のみ可能です。
本手順は、事前に設定対象となるグループ配下の任意のプロジェクトにテンプレートとなるDefault.mdファイルが存在していることが前提となります。
まだこのファイルを作成していない場合は、手順Aをご参照の上、先に作成をお願い致します。
対象グループに対してMaintainer以上のロールを持つユーザーで、GitLabにサインインします。
サインイン後、対象グループのページで [設定] > [一般] をクリックし、テンプレートの [展開] をクリックします。
テンプレートリポジトリを選択という設定項目のプルダウンから、事前にテンプレートファイルを作成したプロジェクトを選択します。
[変更を保存] をクリックします。
画面上部に「Group '<グループ名>' was successfully updated.」と表示されることを確認します。
以上がグループ単位でマージリクエストの説明のテンプレートを設定する手順でした。
続けて手順E : 動作確認 を実施して、作成したテンプレートがグループのデフォルト (規定) のテンプレートとなっていることを確認してください。
手順D : インスタンス単位でマージリクエストの説明のテンプレートを設定する (プレミアム以上 且つ オンプレミス)
本章では、オンプレミスのGitLabのインスタンスに対してマージリクエストの説明のデフォルト (規定) のテンプレートを指定します。
本手順は今回ご紹介する実装方法のうち、実装方法 : D でのみ必要な手順となります。(下の表の黄色いセルの赤字部分。)
| 実装方法 | 実装方法の概要 | 手順 |
|---|---|---|
| A | プロジェクト単位でテンプレートを適用する。 リポジトリに直接テンプレートとなる Default.mdファイルを作成する。全ティアで設定可能。(無料版でも設定可能。) |
①ﾃﾝﾌﾟﾚｰﾄﾌｧｲﾙ作成(手順A) ②確認(手順E) |
| B | プロジェクト単位でテンプレートを適用する。 プロジェクトの [設定] > [一般] > [マージリクエスト] に直接設定する。 プレミアム以上でのみ設定可能。 |
①ﾌﾟﾛｼﾞｪｸﾄの設定(手順B) ②確認(手順E) |
| C | グループ全体にテンプレートを適用する。 グループ配下のプロジェクトのリポジトリに、テンプレートとなる Default.mdファイルを作成する。その後、グループの [設定] から、テンプレートファイルを作成したプロジェクトを指定する。 プレミアム以上でのみ設定可能。 |
①ﾃﾝﾌﾟﾚｰﾄﾌｧｲﾙ作成(手順A) ②ｸﾞﾙｰﾌﾟの設定(手順C) ③確認(手順E) |
| D | インスタンス全体にテンプレートを適用する。 任意のプロジェクトのリポジトリに、テンプレートとなる Default.mdファイルを作成する。その後、インスタンスの [設定] から、テンプレートファイルを作成したプロジェクトを指定する。 プレミアム以上 且つ オンプレ版 (Self-Managed) でのみ設定可能。 |
①ﾃﾝﾌﾟﾚｰﾄﾌｧｲﾙ作成(手順A) ②ｲﾝｽﾀﾝｽの設定(手順D) ③確認(手順E) |
本手順の設定は、プレミアム以上 且つ オンプレミス版 (Self-Managed) をご利用時のみ可能です。
本手順は、設定対象となるインスタンスにある任意のプロジェクトに、テンプレートとなるDefault.mdファイルが存在していることが前提となります。
まだこのファイルを作成していない場合は、手順Aをご参照の上、先に作成をお願い致します。
GitLabのインスタンスに対して管理者権限を持っているユーザーでサインインします。
サインイン後、[メニュー] > [管理者] をクリックします。
左側のメニューから [設定] > [テンプレート] をクリックし、テンプレートの [展開] をクリックします。
テンプレートという設定項目のプルダウンから、事前にテンプレートファイルを作成した グループ/プロジェクト を選択します。
[変更を保存] をクリックします。
画面上部に「アプリケーション設定は正常に保存されました」と表示されることを確認します。
以上がインスタンス単位でマージリクエストの説明のテンプレートを設定する手順でした。
続けて手順E : 動作確認 を実施して、作成したテンプレートがインスタンスレベルのデフォルト (規定) のテンプレートとなっていることを確認してください。
手順E : 動作確認
実際にマージリクエスト作成時に、説明欄にデフォルトのテンプレートが適用されるかを確認します。
ご自身が設定なさったスコープの範囲内にある任意のプロジェクトで、マージリクエストを作成してください。
以下はマージリクエスト作成画面です。
正常にデフォルト (規定の) テンプレートが適用されていると、作成画面に遷移した時点で説明欄にはテンプレートの内容が反映された状態になっています。
今回作成したテンプレートが説明欄に表示されず空欄になっている場合は、[テンプレート] のプルダウンに作成したテンプレート名が表示されているかご確認ください。
表示されている場合、テンプレート自体は正常に認識されていますが、それがデフォルトテンプレートになっていない状態です。
実装方法に応じたデフォルトテンプレート設定に誤りが無いかご確認ください。
表示されていない場合、テンプレート自体が正常に認識されていない可能性が高いです。
テンプレートファイルを作成している場合は、そのパスやファイル名に誤りが無いかご確認ください。
テンプレートをプロジェクトの [設定] に直接指定している場合は、GitLabがサポートする書式で記載されているかご確認ください。
最後に
この度はGitもCI/CDもよくわかっていないど素人SEによるGitLab検証ブログをお読みいただき、誠にありがとうございます。
このブログの目標は以下のとおりでしたが、皆さまはいかがでしたでしょうか。
- GitLabのマージリクエストの説明欄に規定のテンプレートを設定する
今回はマージリクエストの説明欄のデフォルトテンプレート設定方法をご紹介いたしましたが、似たような手順でイシューの説明欄のテンプレートを設定することもできます。
こちらはまた後日ご紹介する・・・かもしれません。
この記事がGitLabを触り始めた方の一助となれば幸いにございます。
GitLabに関するお問い合わせは、以下のフォームからお願い致します。
GitLab製品 お問い合わせ
今までのGitLabの検証ブログはこちらです。
GitLab操作デモ動画 (基本編) を作ってみました。(音声の録音は自宅でiPhoneのボイスメモ使うという超低クオリティですが…。)
つたない内容ではありますが、ご興味がおありでしたら是非ご視聴いただければと存じます。
