• 要約
• 目標
• 課題
  • GitLab CIテンプレートの問題点
• チャンス
• 用語解説
• パイプラインコンポーネントの定義
  • 予測可能なコンポーネント
• コンポーネントの構造
  • FQDN
  • コンポーネントのパス
  • コンポーネントのバージョン
• コンポーネントのリポジトリ
  • コンポーネントリポジトリの構造
• spec:inputs: パラメータ
  • CI設定の補間の観点と制限
  • なぜ環境変数ではなく入力パラメーターなのですか？
  • 既存のinclude: 構文の入力パラメータ
  • パイプラインの入力パラメータ
• CIカタログ
• カタログリソース
• 新しいバージョンのリソースをカタログにリリース
• CIカタログの機能提供
• 将来のリソースタイプに関する注意事項
• 実装ガイドライン
• イテレーション
• 限界
• 誰

CI/CDカタログ

要約

目標

CI/CDパイプラインコンポーネントカタログの目標は、パイプライン設定の再利用をより簡単かつ効率的にすることです。パイプライン構成を発見し、理解し、再利用する方法を学ぶ方法を提供することで、より合理的なエクスペリエンスが可能になります。また、CI/CDパイプラインコンポーネントカタログを持つことで、ユーザーがパイプラインコンストラクトを共同開発するためのフレームワークを構築し、長期的な進化と改善を可能にします。

このブループリントは、パイプラインコンポーネントのCI/CDカタログを構築する方法に関するアーキテクチャガイドラインを定義します。このブループリントは、ソリューションの反復と改善の長期的な方向性も定義します。

課題

• GitLab CI/CDは新規ユーザーにとって学習曲線が急な場合があります。パイプラインの設定方法を理解するために、ユーザーはドキュメントやYAMLリファレンスを読まなければなりません。
• 開発者は既存の CI/CD テンプレートを再利用するのに苦労しており、その結果、車輪を再発明して YAML 設定を繰り返し書かなければなりません。
• GitLabCIテンプレートは、特定の目的のためにパイプラインやジョブの雛形をユーザーに提供します。しかし、GitLabインスタンスに同梱されているため、それらをバージョン管理することは今日困難です。詳しくはこのイシューをご覧ください。
• GitLab CI/CDのユーザー(パイプライン作成者)は今日、組織内で共有されたパイプライン設定を整理するための独自のアドホックな方法を持っています。それらの設定はほとんど文書化されていない傾向があります。
• 発見可能な設定はGitLab CIテンプレートだけです。しかし、これらはインラインドキュメントを持っていないので、エディタに内容をコピーペーストして実際のYAMLを読まなければ、何をするのか、どのように使うのかを知ることが難しくなります。
• GitLab の追加機能（CD、セキュリティ、テストなど）を採用するのも難しくなります。
• 再利用可能な CI 設定をテストするフレームワークがありません。多くの設定は、単一の変更に対してユニットテストされていません。
• コミュニティ、パートナー、サードパーティ、個人の貢献者がGitLab管理テンプレートに貢献するには、GitLab貢献プロセスを通過する必要があります。詳しくはこのイシューをご覧ください。
• GitLabには100以上のテンプレートがあり、中には追加された後ほとんどメンテナーされていないものもあります。

GitLab CIテンプレートの問題点

• GitLab CIテンプレートは決定論的な振る舞いを念頭に置いて設計されていません。
• GitLab CI Templatesは再利用性を考慮して設計されていません。
• Jobs/ テンプレートはstage: 属性をハードコードしていますが、テンプレートのユーザーは何らかの方法で上書きするか、どのステージが必要かを事前に知っておく必要があります。
  • コンポーネントを使用するとき、ユーザーは与えられたステージ内でジョブをインポートするか、ステージ名を入力パラメーターとして渡すことができるべきです。
  • 正しいステージのマッピングに失敗すると、混乱したエラーになる可能性があります。
• 一部のテンプレートはAutoDevOpsで動作するように設計されていますが、十分に汎用的ではありません（例）。
• 多くのCIテンプレート、特に言語固有のテンプレートは、チュートリアル/足場固めスタイルのテンプレートです。
  • これらは典型的なパイプラインがどのように見えるかをユーザーに示すためのものですが、ユーザーの視点から高度なカスタマイズが必要です。
  • パイプラインエディターのカーソルの位置にコピーペーストするという、異なるUXが必要です。
• SAST.latest.gitlab-ci.yml のように、複数のジョブを同じパイプラインに条件付きで追加するテンプレートもあります。
  • これらのジョブは子パイプラインとして実行され、親パイプラインでレポーターを利用できるようにするのが理想的です。
  • このエピックは、親子パイプラインを使用するために必要です。
• variables,image などのトップレベルキーワードを誤って使用しているテンプレートがありますが、これはテンプレートで定義されたものだけでなく、すべてのパイプラインジョブで定義されています。
  • このテクニックは、テンプレートが不必要にジョブを修正する場合、継承の問題を引き起こします。

チャンス

• ユーザーが検索して必要なものを見つけることができるパイプライン構造のカタログを持つことで、新規ユーザーのハードルを大幅に下げることができます。
• 顧客はすでに、共有設定のアドホックなカタログを展開しようとしています。パイプラインコンストラクトを製品内で直接記述、パッケージ化、共有するための標準化された方法を提供できます。
• 新しいパイプラインの構成要素（例えば、再利用可能なジョブステップなど）を実装すると、それらはカタログの項目になる可能性があります。カタログは新しい構成要素の採用を後押しします。
• カタログは、パートナーが提供しメンテナーするコンポーネントを持つことで、パートナーとの関係を強化する場所になります。
• 発見しやすく、より良いバージョン管理メカニズムによって、私たちはより多くの改善とより良いコラボレーションを行うことができます。
• 競争環境は、このような機能の必要性を示しています。
  • R2DevOpsはGitLabパイプラインのCIテンプレートのカタログを実装しています。
  • GitHub Actionsは再利用可能なジョブステップの広範なカタログを提供します。
  • CircleCI Orbsは再利用可能なYAML設定パッケージを提供します。

用語解説

このセクションでは、本文書を通して使用されるいくつかの用語を定義します。これらの用語は抽象的な概念に過ぎず、新たなインサイトを発見して設計を改良する際に変更される可能性があります。

• コンポーネントパイプライン設定の再利用可能な単位。
• コンポーネントリポジトリは、同じプロジェクトに格納されているCIコンポーネントのコレクションを表します。
• プロジェクトは、単一のコンポーネントリポジトリに接続されたGitLabプロジェクトです。
• Catalogはコンポーネントリポジトリのようなリソースのコレクションです。
• カタログリソースは、カタログに表示される単一のアイテムです。コンポーネントリポジトリはカタログリソースです。
• バージョンは、カタログリソースの特定のリビジョンです。プロジェクトのリリースタグに対応し、コンポーネントを特定のリビジョンに固定できます。
• ステップとは、ジョブの実行方法の指示の集まりです。

パイプラインコンポーネントの定義

パイプラインコンポーネントは、単一のパイプライン設定ユニットを抽象化した、再利用可能な単一目的のビルディングブロックです。コンポーネントは、パイプライン設定の一部または全体を構成するために使用されます。オプションで入力パラメータを受け取り、異なるパイプラインコンテキストに適応して再利用できるようにすることができます。

コンポーネントを使用すると、すべての詳細を一箇所で定義する代わりに、抽象化を使用してパイプラインを組み立てることができます。パイプラインでコンポーネントを使用する場合、ユーザーはコンポーネントの実装の詳細を知る必要はなく、提供されるインターフェイスのみに依存する必要があります。

パイプラインコンポーネントは、パイプライン設定のどのコンテキストでコンポーネントを使用できるかを示すタイプを定義します。例えば、タイプXのコンポーネントは、タイプXのユースケースに従ってのみ使用できます。

コンポーネントで構成されたシステムで最良の経験をするためには、コンポーネントで構成されることが基本です：

• 単一の目的：コンポーネントは、単一の目標に焦点を当て、スコープをできるだけ小さくする必要があります。
• 分離: コンポーネントがパイプラインで使用される場合、その実装の詳細がコンポーネント自体の外部に漏れたり、メインのパイプラインに漏れたりしてはいけません。
• 再利用可能: コンポーネントは、さまざまなパイプラインで使用できるように設計されています。コンポーネントがどのような前提で構築されているかによって、コンポーネントは多かれ少なかれ汎用的なものになります。汎用コンポーネントは再利用性が高いですが、カスタマイズが必要になる場合があります。
• バージョン指定: コンポーネントを使用する際には、バージョンを指定する必要があります。バージョンは、コンポーネントの正確なインターフェースと動作を特定します。
• 解決可能：コンポーネントが他のコンポーネントに依存する場合、この依存関係は明示的で追跡可能でなければなりません。

予測可能なコンポーネント

最終的には、CIカタログコンポーネントを予測可能にしたいと考えています。固定の@ バージョンを使用して、そのパスでコンポーネントをインクルードすると、インクルード元のコンテキストに関係なく、常に同じ設定が返されるはずです。結果として得られる設定は、与えられたコンポーネントのバージョンと、include:inputs キーワードを使用して渡された入力のセットに対して同じであるべきです。したがって、それは決定論的であるべきです。

コンポーネントは、インクルードされることによって副作用を生じるべきではなく、参照透過であるべきです。

コンポーネントを予測可能にすることはプロセスであり、CIテンプレートを大幅に再設計しなければ達成できないかもしれません。私たちは当初、コンポーネントをより決定論的にするために、include: remote: のようなトップレベルのキーワードを制限することを検討しましたが、最終的には、コンポーネントをより予測可能にするために必要な設計をよりよく理解するために、まずMVPを反復する必要があることに合意しました。予測可能性、決定性、参照透過性、CIコンポーネントを予測可能にすることは、今でも私たちにとって重要ですが、初期の反復では達成できないかもしれません。

コンポーネントの構造

パイプラインコンポーネントは、<fqdn>/<component-path>@<version> を含むユニークなアドレスで識別されます：

• FQDN（完全修飾ドメイン名）。
• リポジトリまたはそれを定義するディレクトリへのパス。
• 特定のバージョン

例：gitlab.com/gitlab-org/dast@1.0.

FQDN

当初は、同じ GitLab インスタンスを指すコンポーネントアドレス、つまり FQDN が GitLab ホストと一致するものだけをサポートしていました。

コンポーネントのパス

コンポーネントパスによって特定されるディレクトリには、少なくともコンポーネントの YAML と、オプションで関連するREADME.md ドキュメントファイルが含まれていなければなりません。

コンポーネントパスは

• プロジェクトへのパス:gitlab.com/gitlab-org/dast.デフォルトのコンポーネントは処理されます。
• 明示的コンポーネントへのパス:gitlab.com/gitlab-org/dast/api-scan. この場合、明示的コンポーネントapi-scan が処理されます。
• 内部ディレクトリへの相対パス:./path/to/component 。このパスには、コンポーネントを定義するコンポーネント YAML を含める必要があります。パスは、現在のファイルのパスからの相対パスを示すために、./ または../ で始まる必要があります。

相対ローカルパスは完全なコンポーネントアドレスの省略形です。つまり、gitlab-org/dast プロジェクトのmydir/file.yml ファイルから呼び出された./path/to/component は次のように展開されます：

gitlab.com/gitlab-org/dast/mydir/path/to/component@<CURRENT_SHA>

コンポーネント YAML ファイルはファイル名の規約<type>.yml に従います：

コンポーネントが使われるコンテキストに基づいて、正しいYAMLファイルを取得します。たとえば

• コンポーネントgitlab.com/gitlab-org/dast@1.0 をインクルードする場合、gitlab-org/dast リポジトリのルートディレクトリにあるtemplate.yml という名前の YAML ファイルを期待します。
• コンポーネントgitlab.com/gitlab-org/dast/api-scan@1.0 をインクルードする場合、gitlab-org/dast リポジトリのapi-scan ディレクトリにtemplate.yml という名前の YAML ファイルが存在することを期待します。

コンポーネントのYAMLファイル

• 参照される名前が必要です。
• ファイル名でそのタイプを指定する必要があります。これは、どのように使用できるかを定義します（includedされる生の設定、子パイプラインワークフロー、ジョブステップ）。
• タイプに基づいて内容を定義する必要があります。
• 受け入れる入力パラメータを指定する必要があります。コンポーネントは、環境変数ではなく、動的な値の入力パラメータに依存する必要があります。
• 静的に検証されなければなりません (たとえば、JSON スキーマバリデータを使用します)。

spec:
  inputs:
    website:
    environment:
      default: test
    test_run:
      options:
        - unit
        - integration
        - system
---
# content of the component

コンポーネントのバージョン

コンポーネントのバージョンは、（優先順位の高いものから順に）次のようになります：

1. コミット SHA：gitlab.com/gitlab-org/dast@e3262fdd0914fa823210cdb79a8c421e2cef79d8
2. タグ - 例えばgitlab.com/gitlab-org/dast@1.0
3. 最新のリリースされたタグを指す、特別なムービングターゲット・バージョン：gitlab.com/gitlab-org/dast@~latest
4. ブランチ名：gitlab.com/gitlab-org/dast@master

タグとブランチが同じ名前の場合、タグがブランチより優先されます。同様に、タグの名前がe3262fdd0914fa823210cdb79a8c421e2cef79d8 の場合、コミット SHA（存在する場合）が優先されます。

どんなリビジョンでも（リリースされていないものでも）参照できるようにしたいので、コンポーネントは Git リポジトリで定義しなければなりません。

コンポーネントを内部パス (./path/to/component など) で参照する場合、そのバージョンは暗黙的なもので、現在のパイプラインコンテキストのコミット SHA と一致します。

コンポーネントのリポジトリ

コンポーネントリポジトリは、1つまたは複数のパイプラインコンポーネントを専用にホストするGitLabプロジェクト/リポジトリです。

コンポーネントリポジトリはカタログリソースになることができます。コンポーネントリポジトリでは、適切なアバターとプロジェクトの説明を設定することを強くお勧めします。

カタログでリリースされるコンポーネントリポジトリは、リポジトリのREADME.md ルートディレクトリにファイルが README.mdなければなりません。README.md この README.mdファイルはコンポーネントリポジトリのドキュメントを表しますので、リポジトリをカタログに掲載しない場合でも推奨されます。

コンポーネントリポジトリの構造

コンポーネントリポジトリは、1つまたは複数のコンポーネントをホストできます。作成者は、リポジトリごとに単一のコンポーネントを定義するか、同じリポジトリに複数のまとまったコンポーネントを含めるかを決めることができます。

コンポーネントリポジトリは、プロジェクトのフルパスで識別されます。

RailsアプリのRSpecテストを実行するコンポーネントを開発するとしましょう。myorg/rails-rspec というプロジェクトを作成します。

次のようなディレクトリ構造で、リポジトリごとに1つのコンポーネントをサポートします：

.
├── template.yml
├── README.md
└── .gitlab-ci.yml

プロジェクトでは、変更が適切に検証されるよう、.gitlab-ci.yml を推奨します。

コンポーネントはgitlab.com/myorg/rails-rspec というパスで識別されるようになり、プロジェクトのパスにも対応します。template.yml ファイルとREADME.md がリポジトリのルートディレクトリにあることを期待します。

次のようなディレクトリ構造で、リポジトリごとに複数のコンポーネントをサポートします：

.
├── .gitlab-ci.yml
├── README.md
├── unit/
│   └── template.yml
├── integration/
│   └── template.yml
└── feature/
    └── template.yml

この例では、RSpec で実行する複数のテストプロファイルを定義しています。ユーザーは、これらのうち 1 つ以上を選択することができます。

これらのコンポーネントは、それぞれgitlab.com/myorg/rails-rspec/unit 、gitlab.com/myorg/rails-rspec/integration 、gitlab.com/myorg/rails-rspec/feature というパスで識別されます。

このディレクトリ構造は、両方の戦略をサポートすることもできます：

.
├── template.yml       # myorg/rails-rspec
├── README.md
├── LICENSE
├── .gitlab-ci.yml
├── unit/
│   └── template.yml   # myorg/rails-rspec/unit
├── integration/
│   └── template.yml   # myorg/rails-rspec/integration
└── feature/
    └── template.yml   # myorg/rails-rspec/feature

上記の構造では、デフォルトのコンポーネントとして使用できるトップレベルのコンポーネントを持つことができます。たとえば、myorg/rails-rspec はすべてのテストプロファイルを一緒に実行できます。しかし、より特定のテストプロファイルを個別に使用することもできます（たとえばmyorg/rails-rspec/integration ）。

spec:inputs: パラメータ

コンポーネントが入力パラメータを受け取る場合、以下のスキーマに従って指定する必要があります：

spec:
  inputs:
    website: # by default all declared inputs are mandatory.
    environment:
      default: test # apply default if not provided. This makes the input optional.
    flags:
      default: null # make an input entirely optional with no value by default.
    test_run:
      options: # a choice must be made from the list since there is no default value.
        - unit
        - integration
        - system
---
# content of the component
my-job:
  script: echo

この場合の YAML は2つのドキュメントを含みます。最初のドキュメントは仕様を表し、2番目のドキュメントは内容を表します。

コンポーネントを使うとき、入力パラメータを次のように渡します：

include:
  - component: gitlab.com/org/my-component@1.0
    inputs:
      website: ${MY_WEBSITE} # variables expansion
      test_run: system
      environment: $[[ inputs.environment ]] # interpolation of upstream inputs

変数の展開は、include:inputs 構文と、アップストリームで提供される可能性のある入力の補間をサポートしている必要があります。

入力パラメータはできるだけ早く検証されます：

1. org/my-component プロジェクト内部のファイルgitlab-template.yml を読んでください。
2. 仕様書からspec:inputs を解析し、このスキーマに対してパラメーターを検証します。
3. 検証に成功した場合は、コンテンツの解析を進めます。そうでない場合はエラーを返します。
4. 入力パラメータをコンポーネントの中身に補間します。

spec:
  inputs:
    environment:
      options: [test, staging, production]
---
"run-tests-$[[ inputs.environment ]]":
  script: ./run-test

scan-website:
  script: ./scan-website $[[ inputs.environment ]]
  rules:
    - if: $[[ inputs.environment ]] == 'staging'
    - if: $[[ inputs.environment ]] == 'production'

$[[ inputs.XXX ]] の場合、入力はコンテンツをパースした直後に補間されます。

CI設定の補間の観点と制限

spec:inputs 、ユーザーはCI設定のための入力引数を定義できるようになります。include:inputs では、これらの引数を CI コンポーネントに渡します。

inputs $[[ inputs.something ]] は、ユーザーが補間ブロックの引数にアクセスできるようにするために、私たちが提供する初期の「オブジェクト」または「コンテナ」になります。しかし、これは、例えば、無数の方向に発展させることができます：

1. 例えば、ユーザーが簡単に環境変数にアクセスできるように、variables やenv オブジェクトを提供することもできます。
2. 他の場所から渡されたJSONもしくはYAMLオブジェクトを簡単にナビゲートするためにブロック評価を拡張できます。
3. リポジトリファイル、スニペット、イシューへのアクセスも提供できます。

CI 設定補間は、特に GitLab.com でこの仕組みが頻繁に使われることが予想されるため、比較的計算負荷の高い技術です。ユーザーが責任を持ってこれを使うことを保証するために、私たちは様々な制限を導入しました。別のレベルで利用可能なアプリケーションの制限 (サポートされる最大 YAML サイズ、YAML ファイルをパースする際のタイムアウトなど) があるため、この制限がユーザーに影響を与えることはありません。たとえば

1. 補間ブロックは1キロバイトより大きくなりません。
2. 補間を含むYAMLの値は1メガバイトより大きくすることはできません。
3. YAML 設定は50万項目を超えることはできません。

なぜ環境変数ではなく入力パラメーターなのですか？

今日まで、私たちは環境変数を活用して情報をやり取りしてきました。例えば、アップストリームパイプラインからダウンストリームパイプラインに情報を渡すために環境変数を使います。

環境変数を使ってコンポーネントに情報を渡すのは、プログラミング言語でグローバル変数を宣言するようなものです。宣言する変数が多ければ多いほど、変数の衝突や変数のスコープが広がるリスクが高まります。

入力パラメータはコンポーネントに渡される変数のようなもので、特定のスコープ内に存在し、外部に漏れることはありません。入力パラメータはアップストリームincludeから継承されません。

このパラダイムは、より堅牢で分離されたコンポーネントを構築し、コントラクトを宣言して強制することを可能にします。

既存のinclude: 構文の入力パラメータ

include:component を介して使用されるコンポーネントに入力パラメータを追加しているため、inputs: 構文を介して入力をサポートする他のinclude: タイプに拡張する機会があります：

include:
  - component: gitlab.com/org/my-component@1.0
    inputs:
      foo: bar
  - local: path/to/file.yml
    inputs:
      foo: bar
  - project: org/another
    file: .gitlab-ci.yml
    inputs:
      foo: bar
  - remote: http://example.com/ci/config
    inputs:
      foo: bar
  - template: Auto-DevOps.gitlab-ci.yml
    inputs:
      foo: bar

それから、インクルードされる設定は YAML のなかで指定セクションを定義することで入力を指定しなければなりません：

spec:
  inputs:
    foo:
---
# rest of the configuration

YAML がinclude:inputs を使う内容をインクルードするにもかかわらず、インクルードされる YAML が仕様のなかでspec:inputs を定義しない場合、エラーが発生します。

パイプラインの入力パラメータ

入力は、トリガー時にパイプラインにパラメータを渡すために使用することもできます。

今日、明示的な入力パラメータを使用することが有益である、さまざまなユースケースがあります：

1. Run Pipeline UIフォーム
   • 今日の問題：環境変数をUIに表示するためにvariables:*:description 、トップレベルの変数を使っています。この問題は責任が混在していることと変数が(YAML変数からパイプライン変数に)優先されることです。このソリューションの上にバリデーションと機能を構築することは挑戦的で複雑です。
2. API経由でパイプラインをトリガーします。たとえば、POST /projects/:id/pipelines/trigger 。{ inputs: { provider: 'aws' } }
3. trigger: 構文を使用してパイプラインをトリガーします。

deploy-app:
  trigger:
    project: org/deployer
    inputs:
      provider: aws
      deploy_environment: staging

Run Pipeline UIフォームの問題を解決するために、私たちはinputs 仕様を完全に活用することができました：

spec:
  inputs:
    concurrency:
      default: 10    # displayed as default value in the input box
    provider: # can enforce `required` in the form validation
      description: Deployment provider # optional: render as input label.
    deploy_environment:
      options: # render a selectbox with options in order of how they are defined below
        - staging    # 1st option
        - canary     # 2nd option
        - production # 3rd option
      default: staging # selected by default in the UI.
                      # if `default:` is not specified, the user must explicitly select
                      # an option.
      description: Deployment environment # optional: render as input label.
---
# rest of the pipeline config

CIカタログ

CIカタログは、ユーザーがCI/CDで活用できるリソースのインデックスです。初期状態では、ユーザーがパイプラインで発見し利用できるコンポーネントリポジトリのリストが含まれています。

将来的には、このカタログには他の種類のリソース（インテグレーション、プロジェクトテンプレートなど）も含めることができます。

コンポーネントリポジトリをカタログに掲載するには、プロジェクトをカタログリソースとしてマークする必要があります。プロジェクトの設定を変更するのと同じように、APIエンドポイントを使って最初に行います。

プロジェクトが「カタログリソース」としてマークされると、カタログに表示することができます。

APIエンドポイントが使用されたときにデータベースレコードを作成し、同じものが無効/削除されたときにレコードを削除することができます。

カタログリソース

カタログリソースを公開する際には、少なくとも以下の属性を持つ必要があります：

• path: 一意に識別されること。
• name: コンポーネントリポジトリの場合、これはプロジェクト名かもしれません。
• documentation:README.md ファイルを使います。
• versionsリソースの1つ以上のリリース。

カタログリソースのその他のプロパティ：

• descriptionコンポーネントリポジトリの場合、これはプロジェクトの説明になります。
• avatar imageプロジェクトのアバターを使うこともできます。
• 人気の指標（スター、フォーク）。
• カテゴリ分類：ユーザーはカテゴリを選択するか、検索タグを定義する必要があります。

コンポーネントリポジトリが “カタログリソース “としてマークされると、すぐにカタログにリソースが表示されるはずです。

リソースの初期状態では、プロジェクトはリリースタグを持っていないかもしれません。ユーザーは、バージョンのブランチ名やコミット SHA を指定することで、コンポーネントリポジトリを使用できるようになります。しかし、このようなバージョンの修飾子は、さまざまな理由から、カタログリソースのページにリストされるべきではありません：

• ブランチやタグのリストが非常に大きくなってしまいます。
• ブランチやタグはエンドユーザーにとって意味のあるものではないかもしれません。
• ブランチやタグは、バージョン管理を完全に伝えるものではありません。

新しいバージョンのリソースをカタログにリリース

リソースに対して表示されるべきバージョンは、プロジェクトリリースであるべきです。プロジェクトリリースの作成は、リソースをバージョン管理する公式な行為です。

リソースページには

• 証拠となる最新リリース（例：デフォルトバージョン）。
• リソースの過去のリリースを検査し、使用する機能。
• README.md で表されるドキュメント。

ユーザーは、継続的デリバリーの原則に従ってソフトウェアがデプロイされるのと同様に、CIのパイプラインジョブでリソースの新しいバージョンをリリースできるはずです。

コンポーネントリポジトリと含まれるコンポーネントが品質基準を満たしていることを確認するために、ユーザーはCIカタログで新しいバージョンをリリースする前にそれらをテストすることができます。

新しいリソースバージョンのリリース中に実行できるチェックの例をいくつか示します：

• プロジェクトのルートディレクトリにREADME.md があることを確認します。
• プロジェクトの説明が存在することを確認してください。
• 利用可能なコンポーネントのインデックスがコンポーネントリポジトリに存在する場合、それぞれのコンポーネントが有効な YAML を持っていることを確認します。

プロジェクトの新しいリリースが作成されたら、リソースのメタデータをインデックス化します。CIカタログのメインページをより柔軟に設計するために、最初はできるだけ多くのメタデータをインデックス化したいと思います。CIカタログのリソースを適切に可視化するために、利用可能なデータの不足に制約されたくないのです。そのためには、リリースされているすべてのリソースを見つけ、そのデータとメタデータをインデックス化する必要があるかもしれません。例：CIコンポーネントのspec: セクションの内容をインデックス化します。

コンポーネントリポジトリの開発ワークフローの例を参照してください。

CIカタログの機能提供

CIカタログの2つの機能を独立したビューとして導入する予定です：

1. Namespace Catalog (GitLab Ultimate):組織はトップレベルの名前空間内に作成されたカタログリソースを共有し、発見することができます。ユーザーはトップレベル名前空間内のプロジェクトやサブグループから名前空間カタログにアクセスできるようになります。
2. コミュニティカタログ（GitLab無料）：GitLabインスタンス内の誰もがカタログリソースを共有・発見することができます。コミュニティカタログは公開されているリソース/プロジェクトのみを表示します。

Namespace Catalogのリソースが公開された場合（プロジェクトの可視性が変更された場合）、リソースはNamespace CatalogとCommunity Catalogの両方で利用できます。

CIカタログは1つしかありません。NamespaceカタログとCommunityカタログはCIカタログの異なるビューです。

プロジェクト管理者は、プロジェクトを非公開または公開に設定する責任があります。CIカタログは、コミュニティカタログにプロジェクトが表示されないようにするようなセキュリティ機能を提供すべきではありません。プロジェクトが公開されていれば、いずれにせよ世界中に公開されます。

将来のリソースタイプに関する注意事項

将来的には、カタログで複数のタイプのリソースをサポートするために、プロジェクトのルートディレクトリにファイルcatalog-resource.yml を定義する必要があるかもしれません：

name: DAST
description: Scan a web endpoint to find vulnerabilities
category: security
tags: [dynamic analysis, security scanner]
type: components_repository

このファイルは、リソースの内容に関するメタデータのインデックス付けにも使用できます。例えば、ユーザーはリポジトリ内のコンポーネントをリストアップすることができ、私たちは検索目的のためにさらにデータをインデックス化することができます：

name: DAST
description: Scan a web endpoint to find vulnerabilities
category: security
tags: [dynamic analysis, security scanner]
type: components_repository
metadata:
  components:
    - all-scans
    - scan-x
    - scan-y

実装ガイドライン

• 最小のユーザーベースから始めてください。gitlab-org 、gitlab-com グループ向けに機能をドッグフード化します。私たちのソリューションをテストし検証するために、パイプライン設定の作成者であるEngineering Productivityやその他のグループに参加してもらいます。
• 技術的なデザインやUXの変更を意味するとしても、収集したすべてのフィードバックをインテグレーションできるようにします。機能をGA化するまでは、アーリーアダプターに対して明確な期待を持つべきです。
• 既存の機能をできるだけ再利用しましょう。最初のイテレーションで車輪を再発明しないようにしましょう。例えば、タイトル、説明、アバターのようなプロジェクトの機能を再利用して、カタログを作りましょう。
• コンポーネントの開発ライフサイクルにGitLabの機能を活用しましょう（.gitlab-ci.yml を使ったテスト、リリース管理、パイプラインエディタなど）。
• セルフマネージドサポートを念頭にカタログを設計します。
• カタログとワークフローが、将来的なパイプラインの構成や新しい使用方法をサポートできるようにします。
• 決定論的パッケージマネージャの構築に関する業界のベストプラクティスに従って、コンポーネントとカタログを設計します。

イテレーション

1. 実験段階
   • namespace アクタで機能フラグの後ろにMVCを構築します。
   • gitlab-com およびgitlab-org ネームスペースに対してのみ機能フラグを有効にして、ドッグフーディングを開始します。
   • フィードバックに基づいてソリューションとUXを改良します。
   • この機能のアーリーアダプターとなる顧客を見つけ、彼らのフィードバックを反復します。
2. 新しいパイプライン構造を設計（他のフェーズと並行）。
   • 新しいパイプライン構成（ステップ、ワークフロー、テンプレート）の提案に取り組むための技術・設計プロセスを開始します。
   • 新しいコンストラクトを実装します。カタログはこれらに対応していなければなりません。
   • 新しいコンストラクトをドッグフード化し、フィードバックを反復。
   • 非公開カタログで新コンストラクトをリリース。
3. Ultimateプランのグループの非公開カタログをリリース。
   • フィードバックの反復。
4. GitLabユーザー全員への公開カタログのリリース（展望機能）
   • GitLab CIテンプレートの新バージョンを、可能な限り新しいコンストラクトを使用したコンポーネントとして公開します。
   • GitLab.comやリポジトリエクスポートからコンポーネントをインポート/更新することで、セルフマネージメント管理者がセルフマネージドカタログに入力できるようにします。
   • フィードバックの反復。

限界

機能を公開するMVCは、最初から制限付きで追加すべきです。使われるようになってから機能を制限するよりも、制限付きで新しい機能を追加する方が安全です。ユーザーの要求に応じて、後からいつでも制限を緩和することができます。

いくつかの制限を追加することを検討しましょう：

• 1つのプロジェクトが含む/エクスポートできるコンポーネントの数
• .gitlab-ci.yml ファイルが使用できるインポート数
• コンポーネントが宣言/使用できるインポート数
• ネストされたインポートの最大レベル
• エクスポートされるコンポーネント名の最大長

誰

提案

DRI

ドメインの専門家