こんにちは、クラウド事業部 CI/CDサービスメニューチームの山路です。

今回はGitLabが提供する各種template機能を利用し、開発者の生産性の向上を目指すパターンをいくつか紹介いたします。template機能をまだ使っていない方や一部しか使ったことがない方は、ぜひ読んでいただければ幸いです。

GitLabのtemplate機能とは
テンプレートの組み合わせ
CI/CD PipelineにおけるJobの再利用
開発作業における各種メッセージ・ドキュメントの再利用
- Issue / Merge requestによる開発者間でのやり取り
- Wikiによるドキュメント管理
Projectの再利用
- Project templateとファイル・テンプレートの組み合わせ
- Project templateとincludeの組み合わせ
参考リンク
最後に

GitLabのtemplate機能とは

GitLabはリポジトリやCI/CD周辺に多くのtemplate機能を提供しています。まずは現在提供中のtemplate機能を簡単に紹介します。

なお、各種template機能の一覧を以下のような図にしてみました。

include

include はGitLab CI/CDの中で使えるキーワードの一つで、 .gitlab-ci.yml 以外のファイルを呼び出して利用する機能です。例えば同じProject中にテンプレート用のファイルを用意し、繰り返し発生するJobの内容をテンプレートに記載しておくと、 .gitlab-ci.yml はテンプレートの内容を呼び出して処理を実行できます。

これにより、 .gitlab-ci.yml で同じ処理を何度も記載する事態を避け、メンテナンス性を向上することができます。

techstep.hatenablog.com

include:template

include:template は include の利用形態の一つで、GitLabがオフィシャルに公開するtemplateを利用します。あるCI/CDの処理が既にGitLab templateで定義されていれば、自分たちで .gitlab-ci.yml に処理を記載することなく、実行したい処理を実現できます。

なおGitLabの提供するtemplateは以下の場所で管理されています。

gitlab.com

CI/CD Catalog

include と似たような機能にCatalogというものがあります。これはCI/CD componentsという再利用可能なパイプラインのユニットを組織内外に共有する機能で、例えば特定の言語やツールにまつわるよくある処理 (JavaやGoのbuild / test、Dockerfileのbuild / pushなど) をProject外のCatalogに依存することで、CI/CDの実装の速度やメンテナンス性を向上することができます。

techstep.hatenablog.com

Description template

Description templateはIssue / Merge request用のテンプレートを提供し、事前に記載する項目やメッセージを定義できます。これにより、Projectで決まっているMerge request等のフォームを設定しておき、コミットやIssueチケット作成のたびにイチから記載する手間を省けます。またtemplateを使うことでIssue/Merge requestごとの記載内容や情報量のぶれを少なくすることも期待できます。

techstep.hatenablog.com

Wiki template

Wiki templateはWikiページのテンプレートを提供し、事前に記載内容を定義します。特にProjectで繰り返し使用するWikiのページ/フォーマットがある場合、事前にテンプレートを用意することで記載の手間や内容のブレを抑えることが期待できます。

techstep.hatenablog.com

Commit message template

Commit message templateはコミット時のテンプレートを提供し、Merge commit / Squash commitで使う内容を事前に定義します。Projectによってはコミット時の記載内容を決めている場合もあり、本機能を使うことで繰り返し記載する手間や内容の抜け漏れなどを防ぐことができます。

techstep.hatenablog.com

Comment template

Comment templateはIssue / Merge request / Epicでのコメントのテンプレートを提供し、コメントを事前に定義します。これにより頻繁に使用するコメントをすぐに入力し、コメントを考えたり入力する時間を省略できます。なおComment templateは1ユーザー単位で設定することも、Project / Groupで設定することも可能です (Project / GroupはPremiumプラン以上) 。

techstep.hatenablog.com

Project template

Project templateはPremiumプラン以上で使うことのできる機能で、Project作成時の設定やファイルを事前に定義できます。これはProjectを頻繁に作成するような大規模な組織では特に有用な機能で、組織で定まっているCI/CDの設定や他テンプレートなどを毎回設定する手間を省き、大幅な作業時間の短縮を実現できます。

techblog.ap-com.co.jp

テンプレートの組み合わせ

ここからは各テンプレート機能を使い、具体的にどう便利になるのかの例を紹介します。

CI/CD PipelineにおけるJobの再利用

1つめはGitLab CI/CDパイプラインでのJob等の設定を再利用するケースです。

パイプラインの作成を素早く行いたい場合

CI/CD template / CI/CD Catalogを使うことで、CI/CDでよく使う処理、あるいはこれまで実装経験のない処理を、自分たちで管理することなく実現できる場合があります。

例えば新規の開発プロジェクトをGitLabで管理し、CI/CDもGitLabで行うとします。またこのProjectでは開発の段階から脆弱性などのチェックも行いつつ、セキュリティ面で安全な状態を目指しているとします。

よくある開発ワークフローでは、開発したコードのコンパイルやコンテナイメージのビルド、開発コードに対するテスト、そして各環境へのデプロイをCI/CDで行います。一方CI/CDの中でセキュリティをチェックするのは比較的最近になって盛り上がった動きであり、Projectによってはどうやってセキュリティチェックを入れればよいか、調査・実装に時間のかかる場合もあるでしょう。

GitLabは公式のtemplateを提供しており、この中にはセキュリティ関連のものも含まれます。こちらのtemplateはFreeプランから使えるものなので、まだGitLabを本格利用するか検討中の段階からでも利用可能です。そのため、以下のようなセキュリティスキャンを、プロジェクトの初期から利用できます。

Container Scanning: コンテナイメージをスキャンしOS・開発言語の脆弱性をチェック
SAST: ソースコードに対しSAST (Static Application Security Tesing)を実施
IaC Scanning: IaC定義ファイルをスキャンして脆弱性をチェック
Secret detection: コミットしたファイル内に秘密鍵といった秘匿情報を含まないかチェック

Projectの初期からこれを使うことで早い段階から脆弱性を含むコードをコミットすることを防ぎ、セキュリティの向上を見込めます。

なおGitLabは同様の処理をCI/CD Catalogでも提供しており、こちらを利用することもできます。CI/CD Catalogは先日のGitLab 17.0リリースに合わせてGAを迎えたばかりですが、CI/CD templateと比べて「templateのバージョンを柔軟に指定できる」「input parameterなどを通じて柔軟に設置できる」といった特徴があります。

gitlab.com

今後はGitLabはCI/CD Catalogに注力すると思われるので、新しいProjectではCI/CD Catalogを利用することをお勧めします。

1つのProject内で繰り返し同じ設定をする場合

.gitlab-ci.yml はextends や include といったキーワードを活用することで、CI/CD定義の重複を避けることができます。例えば1つのProjectをモノレポとして扱う、またはtemplate用のリポジトリとして扱う場合などは、1つのProject内でも繰り返し発生する処理を定義するため、これらのキーワードが役に立ちます。

GitLabは rules というキーワードでCI/CD Job/Workflowをどのタイミングで起動するか制御できます。 rules は複数のキーワードを組み合わせた幅広い設定が可能ですが、実際にProject中で使うと同じタイミングで起動したいJobも多く出てきます。

この場合、 rules のみを定義したJobを用意し、それを別のJobから呼び出すことで、 rulesの設定を再利用できます。例えば rules を直接パイプラインから実行できない形で定義し (Hidden jobとも呼ばれます) 、 extendsキーワードで別のJobから呼び出すと、複数のJobを同じタイミングで実行することも可能です。

.merge-request-trigger:
  rules:
    - if $CI_PIPELINE_SOURCE == "merge_request_event"

job1:
  extends: .merge-request-trigger
  script:
    - echo "This is from job1."

job2:
  extends: .merge-request-trigger
  script:
    - echo "This is from Job2."

また extends は includeキーワードと組み合わせ、別のtemplateに定義されたHidden Jobをextends経由で呼び出すこともできます。これにより、例えばあるProject内で共有するtemplateによく使う rules の設定を定義し、それぞれのJobで必要な rulesを再利用することができます。

template.yml

.merge-request-trigger:
  rules:
    - if $CI_PIPELINE_SOURCE == "merge_request_event"

.push-tag-trigger:
  rules:
    - if: $CI_COMMIT_TAG

.gitlab-ci.yml

include:
  local: template/template.yml

job1:
  extends: .merge-request-trigger
  script:
    - echo "This is from job1."

job2:
  extends: .push-tag-trigger
  script:
    - echo "This is from Job2."

2つ以上のProjectで共通の設定をする場合

複数のProjectを利用する場合、Project間で共通の処理をtemplateに定義し、各Projectの .gitlab-ci.yml から呼び出すことで、CI/CD設定を再利用できます。

前項で使用した include は include:project または include:component というキーワードを使い、別Projectからtemplateを呼び出せます。これを利用し、特定のProjectをtemplate用に用意し、別のProjectが利用するtemplateファイルを1か所で管理できます。

template.yml

.merge-request-trigger:
  rules:
    - if $CI_PIPELINE_SOURCE == "merge_request_event"

.push-tag-trigger:
  rules:
    - if: $CI_COMMIT_TAG

.gitlab-ci.yml

include:
  project: MyGroup/TemplateProject
  ref: main
  file: template/template.yml

job1:
  extends: .merge-request-trigger
  script:
    - echo "This is from job1."

job2:
  extends: .push-tag-trigger
  script:
    - echo "This is from Job2."

開発作業における各種メッセージ・ドキュメントの再利用

2つめは、Projectで開発作業をすると頻繁に発生する作業において、各種template機能を利用するケースです。

Issue / Merge requestによる開発者間でのやり取り

GitLabを使ってチームでソフトウェアを開発する場合、実装予定の機能や課題の管理にはIssue、ソースコードの変更にはMerge requestを使います。Issue / Merge requestはGitLabでも特に頻繁に利用するため、あらかじめtemplateを用意すると便利です。

例えば開発中に変更をコミットするとき、Project内で一定のフォーマットを定めている場合は、Commit message templateを用意すれば一定のフォーマットでのコミットが楽にできます。

またIssue / Merge requestに対してはDescription templateという機能が使えます。例えばIssueなら バグ報告 新機能の追加依頼 セキュリティ脆弱性の報告と対応 、Merge requestなら 機能追加時 Hot fix対応時 リリース時といった、頻繁に使うであろうケースに対応したtemplateを用意すれば、新規Issue/MR作成時にイチから用意する手間を省けます。

さらにIssue / Merge request上でコメントを残すときも、頻繁に使うコメントやコメントのフォーマットがある場合、Comment templateを用意すれば簡単に記入できます。

なおGitLabのドキュメントでは、以下のようなバグ報告用のtemplateを紹介しています。

## Summary

(Summarize the bug encountered concisely)

## Steps to reproduce

(How one can reproduce the issue - this is very important)

## Example Project

(If possible, create an example project here on GitLab.com that exhibits the problematic
behavior, and link to it here in the bug report.
If you are using an older version of GitLab, this will also determine whether the bug has been fixed
in a more recent version)

## What is the current bug behavior?

(What actually happens)

## What is the expected correct behavior?

(What you should see instead)

## Relevant logs and/or screenshots

(Paste any relevant logs - use code blocks (```) to format console output, logs, and code, as
it's very hard to read otherwise.)

## Possible fixes

(If you can, link to the line of code that might be responsible for the problem)

/label ~bug ~reproduced ~needs-investigation
/cc @project-manager
/assign @qa-tester

Wikiによるドキュメント管理

GitLabにはWiki機能があり、例えばProjectの利用方法や設計、開発時のルールといったドキュメントをWikiで運用すれば、リポジトリの変更履歴に余計なものを加えず、ドキュメントを管理できます。

またProject内で繰り返し利用するWikiのフォーマットがある場合は、Wiki templateを作成してそれを利用できます。例えばProject内の議事録、マニュアルなど、フォーマットがある程度決まっているものをWikiで管理している場合は、templateによる作業時間の削減や品質の安定化を狙えるでしょう。

例えば以下のような議事録用のtemplateを用意しておき、会議前・会議後にやることを明確にすると、より効果的な会議を行えるかもしれません。

# 機能開発定例_(機能名)_(日時)

(会議主催者は会議前にアジェンダを記入し、参加者にWikiページのリンクを送付する。)

## 参加者

(会議の参加者を記入する)

## アジェンダ

(新機能の実装内容やスコープ・担当者など、この会議で話し合うことを記入する)

## 決定事項

(会議の最後に、決定した事項を記入する。スコープと担当者が決定しているものはチケットを作成しアサインする。)

## 実装時の課題

(実装時に課題となるものはこちらに記入する。スコープと担当者が決定しているものはチケットを作成しアサインする。)

## 議事メモ

(会議中のメモを記載する)

## 参考リンク

(議題に関連する情報のURLをこちらに記入する。)

Projectの再利用

最後に、Project自体をtemplateとして利用するケースを紹介します。

Project templateとファイル・テンプレートの組み合わせ

以前Project templateの紹介記事で少し触れましたが、Project templateは他のtemplate機能と組み合わせてさらに便利に使えます。

Project templateは元となるProject中の設定やファイルを引き継いで新しいProjectを作成します。そのため、README.md .gitlab-ci.ymlといった必須のファイルに加え、各種template用のファイルも引き継がれます。

例えばDescription templateは .gitlab/issue_templates .gitlab/merge_request_templates ディレクトリ配下のファイルを利用するため、Project templateとDescription templateを組み合わせれば、Project初期段階からIssue/Merge requestを共通のフォーマットで利用でき、開発者はすぐにフォーマットに従い開発を始められます。

Project templateとincludeの組み合わせ

Project templateは .gitlab-ci.yml も新Projectに引き継げますが、元のProjectの .gitlab-ci.yml に全ての設定を書いてしまうと、開発者が理解しにくく、CI/CDのメンテナンスが難しくなる可能性があります。そこで、前項でも登場した include を使い、template用のProjectからCI/CDの設定を再利用します。

これにより、Project templateから作成したProject上のCI/CDも、見通しがよく、メンテナンスしやすい状態で利用可能となります。

参考リンク

最後に

今回はGitLabのtemplate機能について紹介しました。GitLabには多くのtemplate機能があるだけでなく、それらを組み合わせることも可能です。template機能を使いこなすことで無駄な作業をする時間を削減し、より開発に集中できる環境を作れるのではないでしょうか。

また、今回紹介したtemplate機能の多くはFreeプランからでも利用可能なため、まだ試したことのない方も気軽に始められます。ぜひこの機会に検討してみてください。

最後に、弊社はGitLabオープンパートナー認定を受けております。また以下のようにCI/CDの導入を支援するサービスも行っているので、何かご相談したいことがあればお気軽にご連絡ください。

APC 技術ブログ

株式会社エーピーコミュニケーションズの技術ブログです。

GitLabのtemplate機能を組み合わせて開発生産性を向上する

GitLabのtemplate機能とは

include

include:template

CI/CD Catalog

Description template

Wiki template

Commit message template

Comment template

Project template

テンプレートの組み合わせ

CI/CD PipelineにおけるJobの再利用

パイプラインの作成を素早く行いたい場合

1つのProject内で繰り返し同じ設定をする場合

2つ以上のProjectで共通の設定をする場合

開発作業における各種メッセージ・ドキュメントの再利用

Issue / Merge requestによる開発者間でのやり取り

Wikiによるドキュメント管理

Projectの再利用

Project templateとファイル・テンプレートの組み合わせ

Project templateとincludeの組み合わせ

参考リンク

最後に