GitLab CI/CD ComponentsとCatalogを使ってパイプラインを再利用可能な部品にする #gitlab

GitLabサポートエンジニアの今井です。GitLabのCI/CDパイプラインを構築するために.gitlab-ci.ymlを書いているとき、共通部品として使えそうな箇所は再利用したいと考えることは良くあるケースではないかと思います。
今までは共通で使えそうな箇所を.gitlab-ci.ymlから別のファイルに分割して、使うときはincludeキーワードを使ってパイプラインに組み込んでいました。しかしこれはあくまで外部ファイルで定義されたパイプラインをYAMLファイルに含めるという意味合いの機能であるため、パイプラインを再利用可能な部品として利用するにはいささか使いづらい点がありました。
その使いづらさを改善したGitLab CI/CD ComponentsとCI/CD Catalogの機能をご紹介したいと思います。

includeキーワードを使った再利用可能な部品化

前述のとおりincludeキーワードは外部ファイルで定義されたパイプラインをYAMLファイルに含める機能です。この分割した外部ファイルを部品とし、includeキーワードを使って再利用していました。includeした後でパイプラインの構成をオーバーライドすることもできるため、必要に応じてカスタマイズすることも可能です。
しかし、このオーバーライドでscriptのほんの一部を変えたいだけカスタマイズしたい場合、script全体を書き換えなければならないため、個人的には少し融通の利かない機能だと感じていました。

CI/CD Componentsによる部品化とCI/CD Catalogによる部品の公開

CI/CD Componentsでパイプラインを部品化

この融通の利かなさを改善してくれるのがGitLab 17.0で一般公開されたCI/CD Componentsという機能です。
この機能はComponentsプロジェクトに部品となるYAMLファイルを定義して、部品を利用するときはこのYAMLファイルをinclude: componentsキーワードで追加します。また部品を再利用できるだけでなく入力パラメーターを定義することでジョブの一部動作のカスタマイズも直感的にできるようになりました。

CI/CD CatalogでCI/CD Componentsで定義した部品を公開

同じくGitLab 17.0から一般公開されたCI/CD Catalogは公開されているCI/CD Componentsを含むプロジェクトのリストです。Catalogに公開することでComponentsの検索性も上がり、プロジェクトの説明やREADME、入力パラメーターの情報を見ることができます。Componentsは定義すればすぐに利用できますが、Catalogに公開した方がより利便性が向上します。

CI/CD Componentsを作ってCI/CD Catalogに公開して使ってみよう

CI/CD Componentsプロジェクトを作成する

1. プロジェクトを作成します
   1. CI CD Components Sampleという名前でプロジェクトを作成します
   2. プロジェクトの説明にComponentsの概要を記載します
   3. README.mdにComponentsの詳細を記載します
   4. ComponentsプロジェクトをCatalogプロジェクトに設定します
      Project > Settings > General > Visibility, project features, permissions
      
2. ディレクトリ、ファイルを作成します

.
├── templates/
│ └── my-component1.yml
│ └── my-component2.yml
├── README.md
└── .gitlab-ci.yml

名前	説明
templates/	Componentsを配置する最上位ディレクトリ。 1つのComponentsで複数のファイルを利用する場合、配下にサブディレクトリを作成しても良い
templates/my-component1.yml	Componentsを定義するYAMLファイル
templates/my-component2.yml	Componentsを定義するYAMLファイル
README.md	Componentsの詳細説明を記載するファイル
.gitlab-ci.yml	リポジトリにTagを付けたときにReleaseを作成するパイプラインジョブを定義するファイル (本来はComponentsをテストするジョブも定義すると良い)

CI/CD Componentsを書く

CI CD Components Sampleのmy-component1.ymlとmy-componen2.ymlを下記のように編集します。

my-component1.yml

spec:
  inputs:
    stage:
      default: test
      description: "Defines the test stage"
    job-name:
      default: "my-component1"
      description: "Pipeline job name"
    message:
      default: "my-component1"
      description: "Defalut echo message"
---
"$[[ inputs.job-name ]]-job":
  stage: $[[ inputs.stage ]]
  script:
    - echo "my-components1"
    - echo $[[ inputs.message ]]

my-component2.yml

spec:
  inputs:
    stage:
      default: test
      description: "Defines the test stage"
    job-name:
      default: "my-component2"
      description: "Pipeline job name"
    message:
      default: "my-component2"
      description: "Defalut echo message"
---
"$[[ inputs.job-name ]]-job":
  stage: $[[ inputs.stage ]]
  script:
    - echo "my-components2"
    - echo $[[ inputs.message ]]

spec: inputsキーワードを使ってComponentsの入力パラメーターを定義しています。また、入力パラーメーターではscriptだけでなく、ジョブ名やstageをカスタマイズすることも可能です。
Componentsを書く上での注意事項はここでは割愛します。詳細は公式ドキュメントを参照してください。

CI/CD ComponentsをCI/CD Catalogに公開する

Releaseを作るパイプラインジョブを定義する

CI CD Components Sampleの.gitlab-ci.ymlを下記のように編集します (公式ドキュメントの.gitlab-ci.ymlの例をそのまま使っています)。
これはTagが付けられたときにReleaseを作成するシンプルなジョブになっています。

.gitlab-ci.yml

stages:
  - release

create-release:
  stage: release
  image: registry.gitlab.com/gitlab-org/release-cli:latest
  script: echo "Creating release $CI_COMMIT_TAG"
  rules:
    - if: $CI_COMMIT_TAG
  release:
    tag_name: $CI_COMMIT_TAG
    description: "Release $CI_COMMIT_TAG of components in $CI_PROJECT_PATH"

Tagを付けてReleaseを作成する

1. Project > Code > Tagsを開いてNew tagをクリックします
   
2. Tag nameに1.0.0を入力してCreate tagをクリックします
   
3. Tag1.0.0が作成されます
   
4. Project > Build > Pipelinesを開いてパイプラインジョブが完了していることを確認します
   
5. Project > Deploy > Releasesを開いてRelease1.0.0が作成されていることを確認します
   

CI/CD Catalogを確認する

Search or go to… > Explore > CI/CD Catalogを開いてCI/CD Componentsが公開されていることを確認します。一覧画面にはComponentsプロジェクト名やプロジェクトの説明、Components名などが表示されます。

Componentsプロジェクト名をクリックすると詳細画面が表示されます。ReadmeタブにはREADME.mdの内容が表示されます。

Componentsタブにはinclude: componentキーワードの記述や入力パラメーターの定義が表示されます。

補足: CI/CD Componentsのバージョン

TagとReleaseを作成するときに1.0.0を指定しましたが、CI/CD ComponentsではComponentsプロジェクト毎にセマンティックバージョンを指定できます。もちろんComponentsを利用するときもバージョンを指定することができます。

補足: CI/CD Catalogの可視性

CI/CD Componentsプロジェクトの表示設定に準拠します。

• Private: Componentsプロジェクトに対してGuest以上のロールが割り当てられているユーザーのみに表示されます
• Internal: インスタンスにログインしているユーザーのみに表示されます
• Public: インスタンスにアクセスできるすべてのユーザーに表示されます

CI/CD Componentsを使う

1. プロジェクトを作成します
   1. Use CI CD Components Sampleという名前でプロジェクトを作成します
2. 下記の内容で.gitlab-ci.ymlを作成します
   1. include: componentキーワードでComponentsプロジェクトに定義されたmy-component1とmy-component2を利用するように記述します
   2. inputsキーワードで各Componentsの入力パラメータを記述します

stages:
  - test
  - build

include:
  - component: $CI_SERVER_FQDN/creationline/personal/y-imai/ci-cd-components/my-component2@1.0.0
    inputs:
      stage: test
      job-name: "my-component2"
      message: "hogehoge"
  - component: $CI_SERVER_FQDN/creationline/personal/y-imai/ci-cd-components/my-component1@1.0.0
    inputs:
      stage: build
      job-name: "my-component1"
      message: "piyopiyo"

3. Project > Build > Pipelines > 実行されたパイプラインを開いてパイプラインの実行を確認します
   
4. 各ジョブをクリックしてジョブログを開いてジョブの実行を確認します
   

まとめ

CI/CD Componentsを使いパイプラインを部品化して、CI/CD Catalogで公開することができました。
従来のincludeキーワードよりも部品の検索性や入力パラメーターによるカスタマイズの柔軟性が向上していることを実感できたかと思います。
今回は紹介しきれませんでしたがGitLab.comで公開されているComponentsを自分のSelf-Managedインスタンスで利用することも可能ですので、自分たちで作成したComponentsだけでなく広く公開されているComponentsを活用も視野に入れ、パイプライン構築の省力化を進めてみると良いと思います。