GitとCI/CDに関する知識ゼロのSEが、GitLabのCode Owners (コード所有者) 機能を勉強しつつ設定する話

2022/08/23　一部の図の背景が透過されていて見づらかったので、修正致しました。　

皆様こんにちは。SEの小池と申します。

以前、GitLabで使用できる "マージリクエスト承認ルール (Marge request approval rules) "についてご紹介いたしました。(こちらの記事です。)
今回はそれに似て非なる機能である "Code Owners (コード所有者) " について概要を述べつつ、実際に簡単な設定を試します。

本記事の対象の方
今回のブログのゴール
このブログをお読みいただくにあたっての事前ご連絡事項
Code Owners機能の概要
Code Owners基本設定方法
Code Ownersご利用前の諸注意
Code Ownersお試しシナリオ
Code Ownersお試し設定
【余談】検証中に遭遇した怪現象～コードオーナーなのに[承認]ボタンがない～
【余談】承認ルール (Merge request approval rules) とCode Ownersの違い
最後に

本記事の対象の方

GitLabのCode Owners機能に関する情報を探していらっしゃる方
GitLabのCode Owners機能をお試しなさりたい方

今回のブログのゴール

このブログのゴールはこちらです。

今回のゴール

Code Ownersの概要を理解する。
Code Ownersを簡単に設定してみる。

このブログをお読みいただくにあたっての事前ご連絡事項

本記事はオンプレミス版のGitLab Enterprise Edition 14.10.4-ee (Ultimate) 及び SaaS版のGitLab Enterprise Edition 15.1.0-pre (Ultimate) における仕様をベースに記載しております。それ以外のエディションやバージョンではこの記事に記載の通りではない可能性がございます。
本記事のGitLabのGUIは日本語にローカライズした状態で掲載しております。それ以外の言語をご利用の方は適宜読み替えてください。
本記事はGitやCI/CDに関する知識ゼロのSEによるなんちゃって記事です。GitLabのディープな使用法についてはGitLabの公式オンラインドキュメント (こちら) をご参照ください。

Code Owners機能の概要

Code Ownersは簡単に言うと、プロジェクトのリポジトリ内にあるファイルまたはディレクトリの所有者を設定する機能です。
主な目的は特定のファイルに対して誤った変更や承認を受けていない変更を防止することです。
参考 : Code Owners | GitLab

Code Ownersが設定されたファイルには以下の効果が表れます。

Code Ownersの効果

GitLabのGUIでファイルの所有者名が表示される。
マージリクエストでCode Ownersが設定されたファイルに変更があると、承認フロー上にCode Ownersによる承認条件が自動で表示される。

Code Ownersを設定したファイルをGUIで閲覧すると、下図のように所有者の名前が表示されるようになります。

また、マージリクエストでCode Ownersが設定されたファイルを変更している場合、承認フロー上にCode Ownersによる承認が必要になる条件が自動で表示されます。マージリクエストの中でCode Ownersが設定されたファイルに変更がなかった場合は、Code Ownersによる承認を求める承認条件は表示されません。

なお、Code OwnersはPremium限定の機能です。
Premium以上のライセンスがない状態で本機能をお試しになりたい場合は、トライアルのライセンスを入手いただく必要がございます。
参考 : Why GitLab Premium? | GitLab

Code Owners基本設定方法

Code Ownersは、プロジェクトのリポジトリにファイルCODEOWNERSを作成し、そこへ対象のファイル or ディレクトリと所有者であるユーザーやグループを記載することで設定できます。
ファイルCODEOWNERSは以下のいずれかに置く必要があります。

リポジトリのルートディレクトリ
.gitlab/ディレクトリの中
docs/ディレクトリの中

次に、ファイルCODEOWNERSの書式について。基本的に以下の書式になります。

対象ファイルやディレクトリ @所有者にしたいユーザー名やグループ名

例えば、ルートディレクトリにあるreadme.mdにuser01を所有者として設定する場合は以下のようになります。

readme.md @user01

ディレクトリdocs/building/にあるファイル全てに対し、所有者を二人 (user01とuser02) 設定したい場合は、以下のようになります。

docs/building/ @user01 @user02

所有者をグループにする場合の設定方法の仕方について。
どんなグループであっても所有者に設定できるわけではなく、仕様上の条件を満たしたグループもしくはサブグループのみを設定できます。
設定可能な仕様上の条件は以下をご参照ください。
参考 : Code Owners | GitLab日本語ドキュメント, Code Owners | GitLab

ディレクトリdocs/building/にあるファイル全てに対し、仕様上の条件を満たすサブグループgroup-a/group-a01を所有者にする場合は、以下のようになります。
(group-a/group-a01という書き方は、group-aは親グループ、group-a01はグループgroup-aのサブグループという意味です。)

docs/building/ @group-a/group-a01

対象ファイルやディレクトリの指定には、ワイルドカードを使用できます。
ディレクトリdocs/にあるファイルのうち、末尾が.mdで終わるファイルに対してuser01を所有者として設定したい場合は、こうなります。

docs/*.md @user01

CODEOWNERSの中で角括弧を使うことでセクションを設定できます。
セクションの名前は任意に設定できます。
これにより、ファイルCODEOWNERSが見やすくなるだけでなく、マージリクエストのGUI上の表示がちょっとだけいい感じになります。
筆者の語彙力では適語表現ができないので、図をご参照ください。すみません。

[Documentation]
SampleFileA @admin01
SampleFileB @admin01 @admin02

明示的にオプション (任意) 条件にしたい場合は、セクション名の行頭に^を入れます。
なお、オプション (任意) 条件の指定には前述のセクションの設定が必須です。

[Code owner rule1]
SampleFileA @admin01
^[Code owner rule2]
SampleFileB @admin01 @admin02

Code Ownersご利用前の諸注意

ファイルCODEOWNERSの書式の他、Code Ownersご利用前にご確認いただきたい基本的な事項についてまとめました。

ターゲットブランチの保護設定

ファイルCODEOWNERSが存在するブランチがターゲットになっているマージリクエストにおいて、コード所有者の承認が任意になるか必須になるかは、そのターゲットブランチの保護の設定に依存します。

ファイルCODEOWNERSに指定された所有者による承認を必須としたい場合、ターゲットブランチの保護が有効且つ "コード所有者の承認が必要" が有効になっている必要があります。
参考 : Protected branches | GitLab

この設定はGitLabの対象プロジェクトの[設定]>[リポジトリ]>[Protected branches]から確認、設定できます。

上記の設定が有効になっていない場合、Code Ownersによって自動で表示された承認条件は全てオプション (任意) となります。

ファイル`CODEOWNERS`のチェック機能がない

2022/06/16現在、GitLabにはファイルCODEOWNERSのチェックをする機能がありません。
したがって、単純に書式に問題があった場合は最悪なかなか気づけない場合もあり得ます。
また、オートコンプリート機能もないので、そもそも存在しないもしくは Code Ownersの資格がないユーザーやグループを所有者に指定できてしまいます。

ファイル`CODEOWNERS`に重複する条件があるとき

ファイルCODEOWNERSにて、同じファイルに対して複数の設定をしている場合、結果的に採用されるのは一番最後の設定のみとなります。
参考 : Code Owners | GitLab

例えば、CODEOWNERSで以下の通り設定している場合、package.jsonの所有者はdev02となります。

package.json @dev01
*.json @dev02

Code Ownersお試しシナリオ

ここからは、実際にCode Ownersの機能を試していきます。

GitLabを利用中の架空の企業Aは、以下のご要件をお持ちであると仮定致します。
なお、今回ブログが長くなってきたので、筆者の都合で超簡単なご要件とします！

【企業Aのご要件】

mainブランチの.gitlab-ci.ymlに変更があった場合、指定したユーザーによる承認を必須とする。
承認者は admin01とする。
前提として、承認者はこのプロジェクトのメンバーである。

うーん・・・まさに仕様を考慮したご都合主義のご要件・・・。
このご要件を満たすようにCode Ownersを設定していきます。

Code Ownersお試し設定

前章のシナリオを実際に設定し、どのような結果になるかを確認します。

事前準備

まず、ターゲットとなるmainブランチの保護設定を確認します。

対象のプロジェクトにロールMaintainer以上の権限を持つユーザーでサインインします。
[設定]>[リポジトリ]を開き、[Protected branches]を展開します。
一覧にmainブランチが表示されていることと、"コードオーナーの承認" が有効になっていることを確認します。

事前準備は以上です。

ご要件の設定 : `.gitlab-ci.yml`にCode Ownersを設定する

ファイル.gitlab-ci.ymlにCode Ownersを設定します。

まず、mainブランチにファイルCODEOWNERSを作成します。
作成する場所はこちらの章で記載した場所であればどこでも構いませんが、今回はルートディレクトリ直下に作成しました。

任意のユーザーでmainブランチにあるファイルCODEOWNERSに以下の通り追記します。

[CICD Pipeline Definition file]
.gitlab-ci.yml @admin01

上記を記載したら、ファイルCODEOWNERSの変更をmainブランチにマージしてください。
ご要件の設定は以上です。もう終わってしまった…。ご要件簡単にしすぎたかな。

動作確認

先ほどCode Ownersを設定したファイル.gitlab-ci.ymlに対し変更を加え、mainブランチへのマージリクエストで承認条件が表示されることを確認します。

ロールDeveloperを持つ任意のユーザーでファイル.gitlab-ci.ymlに対して任意の変更を加えます。
ここでは例として、無難にコメントを１行追加しました。

上記の変更でマージリクエストを開始します。
なお、マージリクエスト作成画面で承認者を確認できますが、この時点ではファイルCODEOWNERSに設定した条件は表示されません。(仕様です。)
Code Ownersに指定したファイルに変更があっても無くても表示されませんので、そういうものだと思ってマージリクエストを開始してください。

マージリクエストを開始したら、承認欄を展開させます。
そこにコードオーナーというカテゴリが表示され、ファイル名.gitlab-ci.ymlが表示されていればOKです。
また、ユーザーアイコンにカーソルを合わせると、そのユーザー名を確認できます。

コードオーナーに設定されたユーザーadmin01から見ると、承認ボタンをクリックできる状態になっています。

後の承認やマージの手順は通常のマージリクエストと同様です。
動作確認は以上です。

【余談】検証中に遭遇した怪現象～コードオーナーなのに[承認]ボタンがない～

このブログを書くためにCode Ownersを検証した際、コードオーナーにもかかわらず [承認] ボタンが表示されないという事象に遭遇しました。

この時、当方は以下のようなグループとプロジェクトの構成でCode Ownersの検証をしていました。

結論からすると、この事象はCode Ownersに指定したdev03のロールがGuestだったことが原因です。
こちらのGitLab日本語ドキュメントに以下の通り記載がありました。

Note: Developer or higher permissions are required in order to approve a merge request.

よって本件は、上の図の検証用プロジェクトに対し、サブグループAをDeveloper以上のロールで招待することで解消できます。
この様に、Code Ownersに設定するユーザー及びグループ (サブグループ含む) にはいくらかの条件がありますが、2022/06/16現在、GitLab Docsにもまとまった情報をなかなか見つけづらい状況です…。
Code Ownersを実際に運用することを検討なさっている場合は、GitLab Docsを読み込んでいただくことはもちろんですが、実際にそのCode Ownersがちゃんと動作するかどうかを検証なさってからお使いただければと存じます。
参考 : Code Owners | GitLab日本語ドキュメント, Code Owners | GitLab

【余談】承認ルール (Merge request approval rules) とCode Ownersの違い

以前こちらのブログでご紹介いたしました承認ルール (Merge request approval rules) との違いに関しまして。
どちらもマージリクエストにおける承認のフローに関する設定ですが、微妙に仕様が異なります。
詳細はGitLab Docsをご参照いただければと存じますが、個人的に「あ、そうなんだ～」と思った仕様の違いを挙げてみます。

使用可能なティアが違う (2022/06/16現在)

承認ルール (Merge request approval rules) の場合
デフォルトの承認ルールはFree版でもご利用いただけますが、それ以外のカスタムのルールや必須のルールについてはUltimate版でご利用いただけます。
参考 : Merge request approvals | GitLab
Code Ownersの場合
Premium版以上でご利用いただけます。
参考 : Code Owners | GitLab

設定が発動される条件が違う

承認ルール (Merge request approval rules) の場合
ルールで設定したブランチがターゲットになっている場合のみ、マージリクエスト画面に承認条件が表示されます。このマージリクエストでどのような変更がされたかは影響しません。
Code Ownersの場合
以下2つの条件の両方を満たしている場合のみ、マージリクエスト画面に承認条件が表示されます。
- リポジトリにファイルCODEOWNERS が存在するブランチがターゲットになっている。
- Code Ownersが設定されているファイルもしくはディレクトリに対して変更がある。

条件設定の粒度が違う

承認ルール (Merge request approval rules) の場合
ターゲットブランチの指定のみが条件であり、それより細かい条件設定はできません。
Code Ownersの場合
ファイル名、ディレクトリ名で条件を指定するため、柔軟かつ細かい条件設定が可能です。
条件のファイル名、ディレクトリ名にワイルドカードを使用可能なことも良い点です。

必須とする承認者の人数が違う

承認ルール (Merge request approval rules) の場合
必須とする承認者の人数を任意に設定できます。
必要人数に0を設定することで、オプション (任意) 条件も作成することができます。
Code Ownersの場合
そもそも、ターゲットブランチがProtected branches (保護されたブランチ) であり、且つ、"コード所有者の承認が必要" が有効になっていないと、承認条件が必須になりません。
この条件を満たしている場合であっても、必須とする承認者の人数の設定はデフォルトで一人です。これは変更できません。
ファイルCODEOWNERSで一つのファイルに二人の所有者を設定した場合、マージリクエストではこの二人のどちらか一人から承認を得ることが条件として表示されます。

なお、条件の冒頭に^を記載することで、オプション (任意) 条件を指定することが可能です。
参考 : Code Owners | GitLab

上記の仕様の違いを考慮すると、Code Ownersは更新頻度が低く且つプロジェクトやサービスへの影響が極端に大きいファイル等に設定することが適していると考えられます。
GitLabでいえば、CI/CDパイプラインを構成する`.gitlab-ci.yml`ファイルが該当するかもしれません。

一方、承認ルール (Merge request approval rules) はmainやリリース待ちのブランチ等、重要度が高いブランチに対して設定することが適していると考えられます。
毎日発生するマージリクエストの承認で、毎回ターゲットブランチを目視確認することはなかなか難しいことです。(しかもターゲットブランチ名の表示って、地味に小さいんですよね…。)
承認ルール (Merge request approval rules) を使うことで、重要なブランチがターゲットになっているマージリクエストに限って承認の条件を増やせることはもちろん、マージリクエストの承認画面から「あ、これは○○ブランチへのマージリクエストなんだな」と気づきやすくなるのではないでしょうか。