2023/07/05 GitLab.com Enterprise Edition 16.2.0-pre の画面に差し替え、一部の文言を更新しました。
皆様こんにちは。SEの小池と申します。
GitLabを使っている方にはおなじみの機能であるラベルですが、実はこの機能、有償版でしかできないことがあります。
今回はGitLabのラベルについて、有償版と無償版の違いを踏まえながら簡単に説明致します。
- 本記事の対象の方
- 今回のブログのゴール
- このブログをお読みいただくにあたっての事前ご連絡事項
- GitLabのラベルとは？
- グループラベルとプロジェクトラベル
- 有償版 (Premium以上) でしか使えないスコープラベルとは？
- ラベルの作り方
- ラベルに関するあれこれFAQ
- 最後に
本記事の対象の方
- GitLabのラベルについて情報法収集なさっている方。
- 有償版と無償版におけるラベル機能の違いを確認なさりたい方。
- とりあえずGitLabのラベルを使ってみたい方。
今回のブログのゴール
このブログのゴールはこちらです。
- GitLabのラベルの概要と効果について理解する。
- GitLabでラベルを作成してみる。
- GitLabのスコープラベル (有償版限定の機能) について理解する。
このブログをお読みいただくにあたっての事前ご連絡事項
- 本記事はSaaS版 (GitLab.com) Enterprise Edition 16.2.0-pre (Ultimate) における仕様をベースに記載しております。それ以外のエディションやバージョンではこの記事に記載の通りではない可能性がございます。
- 本記事のGitLabのGUIは日本語にローカライズした状態で掲載しております。それ以外の言語をご利用の方は適宜読み替えてください。
GitLabのラベルとは？
GitLabにおけるラベルとは、イシュー、マージリクエスト、エピックに付与できるタグのようなものです。
グループレベルで設定するグループラベルと、プロジェクトレベルで設定するプロジェクトラベルが存在します。(こちらの詳細は次の章に記載致します。)
ラベルを付与することで、以下のような効果を得られます
- 既存の設定値では補いきれない付加情報やカテゴリなどを自由に付与できる。
- コメント欄などを参照せずとも、付加情報を視覚的に確認しやすくなる。
- 複数のラベルが付与することにより、検索・追跡・視認しやすくなる。
例えば、以下の画像はGitLabの公式開発プロジェクトのイシューボードですが、イシュー１つにつき10個くらいのラベルが付与されています。
参考：10.0 Workflow · Boards · GitLab.org / GitLab · GitLab
GitLabの公式開発プロジェクトに存在する、こちらのイシューを例に挙げます。
このイシューには6個のラベルが付与されています。
(GitLab開発プロジェクトのイシューの中では、これでもラベルが少ない方です‥‥。)
参考：Move IncomingEmail and ServiceDeskEmail to Email namespace (#381505) · Issues · GitLab.org / GitLab · GitLab
それぞれラベルの意味を調べると、以下の通りでした。
この様に、ラベルを細かく作成・付与することで、そのイシュー・マージリクエスト・エピックが何のプロジェクトに関連するのか、ステータスはどうなっているのか、バグなのか新機能なのか、顧客の要望なのか、バージョンはいくつで反映予定なのか 等、設定では補いきれない付加情報を視覚的に付与することができます。
特定のラベルをサブスクライブすると、他のユーザーによってそのラベルが使用された場合 (※) に通知を受け取ることができます。
※ イシューやマージリクエストにそのラベルが付与された場合 等。
ユーザー毎にラベルの優先度を設定できます。
優先度が設定されているラベルが付与されているイシューやマージリクエストは、イシューの一覧 及び マージリクエストの一覧において並び順を [優先順位] にすると、上の方に表示されるようになります。
また、イシューやマージリクエストの検索において、特定のラベルが付与されている/付与されていないことを条件に指定することができるようになります。
これにより、複雑な条件に一致するイシューやマージリクエストを的確に見つけることができます。
この様に、付与したラベルをサブスクライブしたり優先度をつけることで、自分がチェックすべきラベルが付与されたイシューやマージリクエストを追跡・検索しやすくなります。
グループラベルとプロジェクトラベル
ラベルはグループレベルかプロジェクトレベルのいずれかで設定します。
グループレベルで作成したラベルをグループラベル、プロジェクトで作成したラベルをプロジェクトラベルと言います。
グループラベルとプロジェクトラベルは使用可能なスコープが異なりますが、見た目は同じです。
グループラベルは、ラベルを設定したグループの配下に存在する全サブグループと全プロジェクトで使用することができます。
下の図の場合、グループAで「保留中」「顧客レビュー中」の2つのグループラベルを作成しています。
グループラベルは配下の全サブグループと全プロジェクトで使用可能なので、「保留中」「顧客レビュー中」の2つのラベルは、サブグループAA, プロジェクト01, プロジェクト02で利用可能になります。
また、サブグループでもグループラベルは作成可能です。
下の図の場合、サブグループAAで「対応中」のグループラベルを作成したので、プロジェクト02でも「対応中」のラベルを使用可能になります。
プロジェクトラベルは、ラベルを設定したプロジェクトのみで使用可能です。
下の図の場合、プロジェクト02で「脆弱性対応」というプロジェクトラベルを作成しています。
プロジェクトラベルは作成したプロジェクトでのみ使用可能ですので、他のグループ、サブグループ、プロジェクトでこのラベルを使用することはできません。
有償版 (Premium以上) でしか使えないスコープラベルとは？
有償版 (Premium以上) でのみ、スコープラベルを作成し使用することができます。
スコープラベルとは、key部とvalue部 (key::value) の2つで構成されるラベルです。
スコープラベルは、下図のように左側のkey部のみに色が付き、value部には色が付かないような見た目になります。
スコープラベルのkey部とvalue部をうまく指定することにより、「大カテゴリ::小カテゴリ」や「セキュリティ::プライオリティ」といったように、１つのラベルで２つの意味づけをすることができます。
例として、GitLabの公式開発プロジェクトにおいて、key部にBT-Statusが設定されているスコープラベルを見てみましょう。
図を見るだけでも、key部がBT-Statusのスコープラベルが9個あり、それぞれvalue部に違う値 (この例だとステータス) が設定されていることがわかります。
なお、スコープラベルは同じkey部のラベルを排他する仕様です。
つまり、同じkey部を持つスコープラベルを、１つのイシュー・マージリクエスト・エピックに付与することはできません。
例えば下図のようにスコープラベル優先度::低と優先度::中と優先度::高は全てスコープが "優先度" なので、１つのイシュー・マージリクエスト・エピックに付与できるのはどれか一つのみです。
スコープラベルを作成・運用する際は、key部が同じラベルは排他される仕様を考慮いただければと存じます。
参考：Labels - Scoped labels | GitLab
ラベルの作り方
ラベルを作成したいグループ または プロジェクトのページから、[管理] > [ラベル] をクリックします。
[新しいラベル] をクリックします。
なお、下図は１つもラベルがない状態の表示です。既にラベルがある場合、[新しいラベル] ボタンは画面右上に表示されています。
ラベルのタイトル、説明、背景色を入力し、[Create label] をクリックします。
- タイトル：ラベルに表示される文字列です。スコープラベルの場合は key部::value部 の書式で入力します。
- 説明：このラベルの意味を設定します。
- 背景色：このラベルの色です。
ラベルが作成されました！！とっても簡単です！！！
(おまけ) [初期設定ラベルセット] から作成する場合
グループにもプロジェクにもラベルが全くない状態で、プロジェクトの [管理] > [ラベル] メニューを開くと、[初期設定ラベルセットを生成する] というボタンが表示されるケースがあります。
このボタンをクリックすると以下の通常ラベルが一括で作成されます。
- bug
- confirmed
- critical
- discussion
- documentation
- enhancement
- suggestion
- support
ラベルに関するあれこれFAQ
この章では、GitLabのラベルに関するありそうなご質問をQA形式でまとめております。
ラベル作成・編集に必要な権限は？
Reporter以上のロールが必要になります。
ただし、イシュー作成時に既存ラベルを付与するだけならば、Guestロールでも可能です。
また、マージリクエストに既存ラベルを付与することは、Developer以上のロールが必要になります。
参考：Permissions and roles | GitLab
既存の通常ラベルをスコープラベルに変更できる？
Premium以上をご利用であれば可能です。
グループ もしくは プロジェクトのトップページから [管理] > [ラベル] を開き、ラベル一覧を表示させます。
スコープラベルに変更したいラベルの行で、縦3点リーダーのアイコンから [編集] をクリックすると、編集画面に遷移します。
この画面でラベルのタイトルをスコープラベル (key::value) の書式に変更し、保存すればOKです。
プロジェクトラベルをグループラベルに変更できる？
可能です。
ただし、グループラベルをプロジェクトラベルに降格させることはできません。
対象のラベルがあるプロジェクトのページで [管理] > [ラベル] を開き、ラベル一覧を表示させます。
グループラベルに変更したいラベルの行で、縦3点リーダーのアイコンから [グループラベルへ昇格] をクリックすることで、グループラベルへ昇格させることができます。
このプロジェクトがルートグループに直接属している場合はルートグループのグループラベルになります。
このプロジェクトがサブグループに属している場合は、サブグループのグループラベルになります。
ラベルをグループラベルに昇格させると、プロジェクトラベルに戻す (降格させる) ことはできませんのでご注意ください。
パレットに無い色を自由に設定できる？
可能です。
GitLabのラベルの色指定は、既存のパレットから選択する他、色コードを直接指定できます。
例えば以下の図のように色コード#00ffffを指定すると、パレットに無い明るい水色を設定することができます。
また、色指定のところに表示されている■をクリックするとカラーピッカーが起動するので、そこから色を指定することも可能です。無駄にすごい機能・・・。
ラベルの文字の色を変更できる？
不可です。(2022/11/07時点)
ラベルの色はカスタムで指定できますが、文字の色は指定できません。
2022/11/07時点では、GitLab側がラベルの色に対して白か黒のどちらか見やすい色の文字を自動で指定し、これをユーザーが変更することはできません。
スコープラベルを入れ子にできる？
可能です。
例えば、タイトルにペット種類::犬::マルチーズを指定してスコープラベルを作成します。
するとこの場合、key部 (スコープ) はペット種類::犬、value部 (値) はマルチーズとなります。
入れ子構造のスコープラベルの見た目はこんな感じになります。(個人的にはもうちょっとカッコよくしてほしい‥‥)
入れ子のスコープラベルの場合、検索時のkey部の一部分だけ指定しても、key部の全体を指定しても、ヒットさせることが可能です。
例えば今回作った入れ子のスコープラベル (ペット種類::犬::マルチーズ) の場合、以下のどちらの検索条件でもヒットします。
- ペット種類::犬::*
- ペット種類::*
参考：Labels - Nested scopes | GitLab
同じスコープを持つスコープラベルを複数付与できないんだけど？
仕様です。
key部が同じスコープラベルを、１つのイシューや１つのマージリクエスト等に複数付与することはできません。
これはスコープラベルの仕様として、同じkey部を持つラベルは相互に排他的であるからです。
例えば、スコープラベルstatus::reviewとstatus::pendingは、key部がどちらもstatusであるため、１つのイシュー、１つのマージリクエスト、１つのエピックにこれらを両方付与することはできません。
つまり、複数付与する可能性のある要素をスコープラベルのkey部に指定すべきではないと言えます。
スコープラベルはこの仕様を考慮して設計すると良いでしょう。
最後に
この度はGitもCI/CDもよくわかっていないど素人SEによるGitLab検証ブログをお読みいただき、誠にありがとうございます。
このブログの目標は以下のとおりでしたが、皆さまはいかがでしたでしょうか。
- GitLabのラベルの概要と効果について理解する。
- GitLabでラベルを作成してみる。
- GitLabのスコープラベル (有償版限定の機能) について理解する。
ラベルは付加情報を見やすくする・検索しやすくする・追跡しやすくするという、いいこと目白押しの機能です。
(というかラベルをうまく使わないと、正直なところプロジェクトのイシューとかがごちゃごちゃになりやすいような気がします…。)
ラベルは非常にシンプルな機能なので、ユーザー自身や企業の開発ルールを反映しやすいところも魅力の一つです。
GitLabを検討中の方はもちろん、現在GitLabをご利用中でラベルを使っていらっしゃらない方は、是非ラベルの機能をお試しください。
この記事がGitLabを触り始めた方の一助となれば幸いにございます。
GitLabに関するお問い合わせは、以下のフォームからお願い致します。
GitLab製品 お問い合わせ
今までのGitLabの検証ブログはこちらです。
GitLab操作デモ動画 (基本編) を作ってみました。(音声の録音は自宅でiPhoneのボイスメモ使うという超低クオリティですが…。)
つたない内容ではありますが、ご興味がおありでしたら是非ご視聴いただければと存じます。
