CI/CDコンポーネント

プラン: Free、Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

GitLab 16.0でci_namespace_catalog_experimentalフラグとともに実験的機能として導入されました。デフォルトでは無効になっています。
GitLab 16.2のGitLab.comとGitLab Self-Managedで有効になりました。
GitLab 16.3で機能フラグci_namespace_catalog_experimentalは削除されました。
GitLab 16.6でベータに移行しました。
GitLab 17.0で一般提供になりました。

CI/CDコンポーネントは、再利用可能な単一のパイプライン設定ユニットです。コンポーネントを使用して、大規模なパイプラインの一部を作成したり、完全なパイプライン設定を構成したりできます。

コンポーネントは、入力パラメータを指定することで、より動的な動作を実現できます。

CI/CDコンポーネントは、includeキーワードで追加される他の種類の設定と似ていますが、次のようなメリットがあります:

コンポーネントはCI/CDカタログに一覧表示できる。
コンポーネントは特定のバージョンでリリースおよび使用できる。
同じプロジェクト内で複数のコンポーネントを定義し、まとめてバージョニングできる。

独自のコンポーネントを作成する代わりに、CI/CDカタログで必要な機能を持つ公開されたコンポーネントを検索することもできます。

概要と実践的な例については、Efficient DevSecOps workflows with reusable CI/CD components（再利用可能なCI/CDコンポーネントを使用した効率的なDevSecOpsワークフロー）をご覧ください。

一般的な質問と追加のサポートについては、FAQ: GitLab CI/CD Catalog（FAQ：GitLab CI/CDカタログ）のブログ記事を参照してください。

コンポーネントプロジェクト

コンポーネントプロジェクトは、1つ以上のコンポーネントをホストするリポジトリを持つGitLabプロジェクトです。プロジェクト内のすべてのコンポーネントは、まとめてバージョニングされます。プロジェクトごとに最大30のコンポーネントを使用できます。

コンポーネントが他のコンポーネントとは異なるバージョニングを必要とする場合は、そのコンポーネントを専用のコンポーネントプロジェクトに移動する必要があります。

コンポーネントプロジェクトを作成する

コンポーネントプロジェクトを作成するには、次の手順に従います:

README.mdファイルを使用して新しいプロジェクトを作成します:
- 説明にはコンポーネントの概要を明確に記載してください。
- オプション。プロジェクトの作成後、プロジェクトアバターを追加できます。
CI/CDカタログに公開されたコンポーネントは、コンポーネントプロジェクトの概要を表示する際に説明とアバターの両方を使用します。

必要なディレクトリ構造に従って、コンポーネントごとにYAML設定ファイルを追加します。例:

spec:
  inputs:
    stage:
      default: test
---
component-job:
  script: echo job 1
  stage: $[[ inputs.stage ]]

すぐにコンポーネントを使用できますが、コンポーネントをCI/CDカタログに公開することを検討してください。

ディレクトリ構造

リポジトリには、以下を含める必要があります:

リポジトリ内のすべてのコンポーネントの詳細を文書化したREADME.md Markdownファイル。
すべてのコンポーネント設定を含む最上位のtemplates/ディレクトリ。このディレクトリでは、次のことができます:
- templates/secret-detection.ymlのように、コンポーネントごとに.ymlで終わる単一のファイルを使用します。
- 各コンポーネントのtemplate.ymlでサブディレクトリを作成します（templates/secret-detection/template.ymlなど）。他のプロジェクトがこのコンポーネントを使用する際には、このtemplate.ymlファイルのみを使用します。これらのディレクトリ内の他のファイルはコンポーネントと一緒にリリースされませんが、テストやコンテナイメージのビルドなどの目的に使用できます。

必要に応じて、各コンポーネントに独自のREADME.mdファイルを用意して、詳細な情報を提供することもできます。このファイルは最上位のREADME.mdファイルからリンクできます。これにより、コンポーネントプロジェクトの概要とその使用方法をわかりやすく伝えることができます。

また、以下も行う必要があります:

プロジェクトの.gitlab-ci.ymlを設定して、コンポーネントをテストし、新しいバージョンをリリースします。
LICENSE.mdファイルを追加し、コンポーネントの利用を規定する、選択したライセンスについて記載します。たとえば、MITやApache 2.0などのオープンソースライセンスが該当します。

例:

プロジェクトに単一のコンポーネントが含まれている場合、ディレクトリ構造は次のようになります:
```
├── templates/
│   └── my-component.yml
├── LICENSE.md
├── README.md
└── .gitlab-ci.yml
```
プロジェクトに複数のコンポーネントが含まれている場合、ディレクトリ構造は次のようになります:
```
├── templates/
│   ├── my-component.yml
│   └── my-other-component/
│       ├── template.yml
│       ├── Dockerfile
│       └── test.sh
├── LICENSE.md
├── README.md
└── .gitlab-ci.yml
```
この例では:
- my-componentコンポーネントの設定は、単一のファイルで定義されています。
- my-other-componentコンポーネントの設定には、ディレクトリ内の複数のファイルが含まれています。コンポーネントを使用する他のプロジェクトでは、template.ymlファイルのみを使用できます。

コンポーネントを使用する

前提要件:

現在のグループまたはプロジェクトを含む親グループのメンバーである場合:

プロジェクトの親グループの表示レベルによって設定された最小限のロールが必要です。たとえば、親プロジェクトがプライベートに設定されている場合、少なくともレポーターロールが必要です。

コンポーネントをプロジェクトのCI/CD設定に追加するには、include: componentキーワードを使用します。コンポーネント参照の形式は<fully-qualified-domain-name>/<project-path>/<component-name>@<specific-version>です。次に例を示します:

include:
  - component: $CI_SERVER_FQDN/my-org/security-components/secret-detection@1.0.0
    inputs:
      stage: build

この例では:

$CI_SERVER_FQDNは、GitLabホストに一致する完全修飾ドメイン名（FQDN）を表す定義済み変数です。プロジェクトと同じGitLabインスタンス内のコンポーネントのみを参照できます。
my-org/security-componentsは、コンポーネントを含むプロジェクトのフルパスです。
secret-detectionはコンポーネント名で、templates/secret-detection.ymlという単一のファイル、またはtemplates/secret-detection/ディレクトリ内のtemplate.ymlとして定義されます。
1.0.0は、コンポーネントのバージョンです。

パイプライン設定とコンポーネント設定は、それぞれ独立して処理されるわけではありません。パイプラインが開始されると、インクルードされたすべてのコンポーネント設定がパイプラインの設定にマージされます。パイプラインとコンポーネントの両方に同じ名前の設定が含まれている場合、予期しない形で相互作用する可能性があります。

たとえば、同じ名前の2つのジョブはマージされて1つのジョブになります。同様に、extendsを使用するコンポーネントは、参照先の名前がパイプライン内のジョブと同じである場合、誤った設定を拡張する可能性があります。コンポーネントの設定をオーバーライドする場合を除き、パイプラインとコンポーネントで同じ名前の設定を共有しないようにしてください。

GitLab Self-ManagedインスタンスでGitLab.comコンポーネントを使用するには、コンポーネントプロジェクトをミラーリングする必要があります。

コンポーネントが機能するためにトークン、パスワード、その他の機密データを使用する必要がある場合は、コンポーネントのソースコードを監査し、そのデータが想定どおりに、承認したアクションの実行のみに使用されることを確認してください。また、トークンとシークレットは、アクションを完了するために必要最小限の権限、アクセス、スコープで使用してください。

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

コンポーネントのバージョンは、次のいずれかで指定できます。以下は優先度が高い順に並んでいます:

コミットSHA（例: e3262fdd0914fa823210cdb79a8c421e2cef79d8）。
タグ（例: 1.0.0）。同じ名前のタグとコミットSHAが存在する場合、コミットSHAがタグよりも優先されます。CI/CDカタログにリリースされたコンポーネントは、セマンティックバージョンでタグ付けする必要があります。
ブランチ名（例: main）。同じ名前のブランチとタグが存在する場合、タグがブランチよりも優先されます。
~latestまたは部分的なセマンティックバージョン。~latestは、常に徹底して最新バージョンを使用したい場合にのみ使用してください。その場合、破壊的な変更が含まれる可能性があります。~latestには、本番環境での利用が想定されていないプレリリース（1.0.1-rcなど）は含まれません。

コンポーネントでサポートされている任意のバージョンを使用できますが、CI/CDカタログに公開されているバージョンを使用することをおすすめします。コミットSHAまたはブランチ名で参照されるバージョンは、CI/CDカタログに公開されていない可能性がありますが、テストに使用することは可能です。

部分的なセマンティックバージョン

仕様に一致する最新の公開バージョンを選択するために、CI/CDカタログコンポーネントを参照するときに、部分的なセマンティックバージョン番号とキーワード~latestを使用できます。

これらの形式は、公開されているCI/CDカタログのコンポーネントでのみ機能し、通常のプロジェクトコンポーネントでは機能しません。これにより、1.2や~latestなどの形式を使用する場合、リポジトリからプルされるのは、検証されCI/CDカタログに公開されたコンポーネントのみとなり、テストされていない可能性のあるコードがプルされることはありません。

このアプローチは、コンポーネントのユーザーと作成者の両方に大きなメリットをもたらします:

ユーザーにとって、部分的なバージョンを使用すると、破壊的な変更のリスクを伴わずに、マイナーまたはパッチの更新を自動的に受信できる優れた方法です。これにより、安定性を維持しながら、最新のバグ修正とセキュリティパッチによりパイプラインを常に最新の状態に保つことができます。
作成者にとって、部分的なバージョンのサポートにより、既存のパイプラインをすぐに破壊することなく、メジャーバージョンのリリースが可能です。部分的なバージョンを指定したユーザーは、最新の互換性のあるマイナーバージョンまたはパッチバージョンを引き続き使用し、自分のペースでパイプラインを更新する時間を得ることができます。

使用方法:

1.2を使用して、最新の1.2.*バージョンを選択します
1を使用して、最新の1.*.*バージョンを選択します
~latestを使用して、最新のリリースされたバージョンを選択します

たとえば、コンポーネントにはバージョンがあります：1.0.0、1.1.0、1.1.1、1.2.0、2.0.0、2.0.1、2.1.0

コンポーネントを参照する場合:

1は1.2.0を選択します
1.1は1.1.1を選択します
~latestは2.1.0を選択します

部分的なバージョン選択を使用する場合、プレリリースバージョンはフェッチされません。プレリリースバージョンをフェッチするには、完全なバージョン（1.0.1-rcなど）を指定します。

コンポーネントでコンポーネントコンテキストを使用する

コンポーネントは、コンポーネントコンテキストCI/CD式を使用して、コンポーネント自体のメタデータにアクセスできます。この式をコンポーネントテンプレートで使用して、バージョン、コミットSHA、およびその他のメタデータを動的に参照します。

コンポーネントでコンポーネントコンテキストを使用するには、次のようにする必要があります:

コンポーネントに必要なコンポーネントコンテキストフィールドをspec:componentヘッダーで宣言します。spec:componentは、name、sha、version、およびreferenceフィールドをサポートします。
コンポーネントテンプレートで$[[ component.field-name ]] CI/CD式を使用して、コンテキストフィールドを参照します。

たとえば、同じバージョンでビルドされたDockerイメージを参照するコンポーネント:

spec:
  component: [name, version, reference]
  inputs:
    image_tag:
      default: latest
---

build-image:
  image: registry.example.com/$[[ component.name ]]:$[[ component.version ]]
  script:
    - echo "Building with component version $[[ component.version ]]"
    - echo "Component reference: $[[ component.reference ]]"

コンポーネントコンテキストを使用して、バージョニングされたリソースを参照することもできます。

コンポーネントを作成する

このセクションでは、高品質のコンポーネントプロジェクトを作成するためのベストプラクティスについて説明します。

依存関係を管理する

コンポーネントが、さらに他のコンポーネントを使用することは可能ですが、依存関係を慎重に選択してください。依存関係を管理する際には、次の点に注意する必要があります:

依存関係は最小限に抑える。少量の重複であれば、通常、依存関係を持つよりも適切です。
可能な限りローカルの依存関係を利用する。たとえば、include:localを使用すると、複数のファイルで同じGit SHAが使用されるようになります。
他のプロジェクトのコンポーネントに依存する場合は、~latestやGit参照などの変動するターゲットバージョンを使用せず、カタログにあるリリースにバージョンを固定する。リリースまたはGit SHAを使用すると、常に同じリビジョンをフェッチすることを保証し、コンポーネントのユーザーに一貫した動作を提供できます。
新しいリリースにバージョンを固定し、依存関係を定期的に更新する。その後、更新後の依存関係を使用して、コンポーネントの新しいリリースを公開します。
依存関係の権限を評価し、最小限の権限で利用可能な依存関係を使用する。たとえば、イメージをビルドする必要がある場合は、Dockerの代わりにBuildahの使用を検討してください。これにより、特権付きデーモンを持つRunnerを使用せずに済みます。

明確な`README.md`を作成する

各コンポーネントプロジェクトには、明確で包括的なドキュメントが必要です。優れたREADME.mdファイルを作成するには、次の点に留意してください:

コンポーネントが提供する機能の概要から始める。
プロジェクトに複数のコンポーネントが含まれている場合は、目次を用意して、ユーザーが特定のコンポーネントの詳細にすばやく移動できるようにする。
## Componentsセクションを追加し、各コンポーネントに対して### Component Aのようなサブセクションを追加する。
各コンポーネントセクションの内容:
- コンポーネントの機能を説明する。
- その使用方法を示すYAMLの例を少なくとも1つ追加する。
- spec:inputs:descriptionを使用して、コンポーネントが使用する変数またはシークレットをドキュメント化する。
- README内に入力の説明を重複させない。入力はコンポーネントページに自動的に表示されます。代わりに、公開済みコンポーネントにリンクします。
コントリビュートを歓迎する場合は、## Contributeセクションを追加する。

コンポーネントに追加の指示が必要な場合は、そのコンポーネントのディレクトリ内のMarkdownファイルに追記し、メインのREADME.mdファイルからリンクします。例:

README.md    # with links to the specific docs.md
templates/
├── component-1/
│   ├── template.yml
│   └── docs.md
└── component-2/
    ├── template.yml
    └── docs.md

例については、AWSコンポーネントのREADMEを参照してください。

コンポーネントをテストする

開発ワークフローの一環としてCI/CDコンポーネントをテストすることを強くおすすめします。これにより、一貫した動作を確保できます。

ルートディレクトリに.gitlab-ci.ymlを作成して、CI/CDパイプラインで（他のプロジェクトと同様に）変更をテストします。コンポーネントの動作と潜在的な副作用の両方をテストしてください。必要に応じて、GitLab APIを使用できます。

例:

include:
  # include the component located in the current project from the current SHA
  - component: $CI_SERVER_FQDN/$CI_PROJECT_PATH/my-component@$CI_COMMIT_SHA
    inputs:
      stage: build

stages: [build, test, release]

# Check if `component job of my-component` is added.
# This example job could also test that the included component works as expected.
# You can inspect data generated by the component, use GitLab API endpoints, or third-party tools.
ensure-job-added:
  stage: test
  image: badouralix/curl-jq
  # Replace "component job of my-component" with the job name in your component.
  script:
    - |
      route="${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/pipelines/${CI_PIPELINE_ID}/jobs"
      count=`curl --silent "$route" | jq 'map(select(.name | contains("component job of my-component"))) | length'`
      if [ "$count" != "1" ]; then
        exit 1; else
        echo "Component Job present"
      fi

# If the pipeline is for a new tag with a semantic version, and all previous jobs succeed,
# create the release.
create-release:
  stage: release
  image: registry.gitlab.com/gitlab-org/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 repository $CI_PROJECT_PATH"

変更をコミットしてプッシュすると、パイプラインはコンポーネントをテストし、前段階のジョブが成功した場合はリリースを作成します。

プロジェクトが非公開の場合は、認証が必要です。

サンプルファイルに対してコンポーネントをテストする

場合によっては、コンポーネントから操作できるソースファイルが必要になります。たとえば、Goソースコードを構築するコンポーネントは、テスト対象とするGoのサンプルが必要になる可能性があります。あるいは、Dockerイメージを構築するコンポーネントは、テスト対象とするDockerfileのサンプルが必要になる可能性があります。

コンポーネントのテスト中に使用するために、これらのサンプルファイルをコンポーネントプロジェクトに直接含めることができます。

詳細については、コンポーネントのテストの例を参照してください。

インスタンスまたはプロジェクト固有の値をハードコードしないようにする

コンポーネントで別のコンポーネントを使用する場合は、インスタンスの完全修飾ドメイン名（gitlab.comなど）の代わりに$CI_SERVER_FQDNを使用します。

コンポーネントでGitLab APIにアクセスする場合は、インスタンスの完全なURLとパス（https://gitlab.com/api/v4など）の代わりに$CI_API_V4_URLを使用します。

これらの定義済み変数により、たとえば、GitLab Self-ManagedインスタンスでGitLab.comコンポーネントを使用する場合など、別のインスタンスでもコンポーネントが確実に動作するようになります。

APIリソースは常に公開されているとは限らない

コンポーネントとそのテストパイプラインがGitLab Self-Managedでも動作することを確認してください。GitLab.comの公開プロジェクトの一部のAPIリソースには、未認証リクエストでアクセスできますが、GitLab Self-Managedインスタンスでは、コンポーネントプロジェクトが非公開または内部プロジェクトとしてミラーリングされる場合があります。

GitLab Self-Managedインスタンスでのリクエストを認証できるように、必要に応じて入力または変数からアクセストークンを指定できるようにしておくことが重要です。

グローバルキーワードの使用を避ける

コンポーネントでは、グローバルキーワードの使用を避けてください。コンポーネントでこれらのキーワードを使用すると、メインの.gitlab-ci.ymlに直接定義されたジョブや、他のインクルードされたコンポーネントのジョブを含め、パイプライン内のすべてのジョブに影響します。

グローバルキーワードの代替手段は次のとおりです:

コンポーネント設定に重複が発生しても、各ジョブに設定を直接追加する。
コンポーネントでextendsキーワードを使用する。ただし、コンポーネントが設定にマージされる際に名前の競合リスクを軽減できるよう、一意の名前を使用してください。

たとえば、defaultグローバルキーワードの使用は避けてください:

# Not recommended
default:
  image: ruby:3.0

rspec-1:
  script: bundle exec rspec dir1/

rspec-2:
  script: bundle exec rspec dir2/

代替手段は次のとおりです:

設定を各ジョブに明示的に追加する:

rspec-1:
  image: ruby:3.0
  script: bundle exec rspec dir1/

rspec-2:
  image: ruby:3.0
  script: bundle exec rspec dir2/

extendsを使用して設定を再利用する:

.rspec-image:
  image: ruby:3.0

rspec-1:
  extends:
    - .rspec-image
  script: bundle exec rspec dir1/

rspec-2:
  extends:
    - .rspec-image
  script: bundle exec rspec dir2/

ハードコードされた値を入力に置き換える

CI/CDコンポーネントでハードコードされた値を使用することは避けてください。ハードコードされた値を使用すると、コンポーネントのユーザーはコンポーネントの内部詳細を確認し、コンポーネントと連携するようにパイプラインを適合させる必要が生じる可能性があります。

値のハードコードでしばしば問題が発生するキーワードの1つは、stageです。コンポーネントジョブのステージがハードコードされている場合、そのコンポーネントを使用するすべてのパイプラインは、まったく同じステージを定義するか、設定をオーバーライドするmust（必要があります）。

推奨される方法は、inputキーワードを使用して動的にコンポーネントを設定することです。コンポーネントユーザーは必要とする値を指定できます。

たとえば、ユーザーがstage設定を定義できるコンポーネントを作成するには、次のようにします:

コンポーネントの設定:

spec:
  inputs:
    stage:
      default: test
---
unit-test:
  stage: $[[ inputs.stage ]]
  script: echo unit tests

integration-test:
  stage: $[[ inputs.stage ]]
  script: echo integration tests

コンポーネントを使用するプロジェクトの設定:

stages: [verify, release]

include:
  - component: $CI_SERVER_FQDN/myorg/ruby/test@1.0.0
    inputs:
      stage: verify

入力でジョブ名を定義する

stageキーワードの値と同様に、CI/CDコンポーネントでジョブ名をハードコードすることは避けてください。コンポーネントのユーザーがジョブ名をカスタマイズできる場合、パイプライン内の既存の名前との競合を防ぐことができます。また、異なる名前を使用して、異なる入力オプションで同じコンポーネントを複数回含めることもできます。

コンポーネントのユーザーが特定のジョブ名、またはジョブ名のプレフィックスを定義できるようにするには、inputsを使用します。例:

spec:
  inputs:
    job-prefix:
      description: "Define a prefix for the job name"
    job-name:
      description: "Alternatively, define the job's name"
    job-stage:
      default: test
---

"$[[ inputs.job-prefix ]]-scan-website":
  stage: $[[ inputs.job-stage ]]
  script:
    - scan-website-1

"$[[ inputs.job-name ]]":
  stage: $[[ inputs.job-stage ]]
  script:
    - scan-website-2

カスタムCI/CD変数を入力に置き換える

コンポーネントでCI/CD変数を使用する場合は、代わりにinputsキーワードを使用することを検討してください。inputsの方が適している場合は、コンポーネントを設定するためにユーザーにカスタム変数を定義させるのは避けてください。

入力はコンポーネントのspecセクションで明示的に定義され、変数よりも優れた検証機能があります。たとえば、必須入力がコンポーネントに渡されなかった場合、GitLabはパイプラインエラーを返します。これに対して、変数が定義されていない場合、その値は空になり、エラーは発生しません。

たとえば、スキャナーの出力形式を設定するには、変数の代わりにinputsを使用します:

コンポーネントの設定:

spec:
  inputs:
    scanner-output:
      default: json
---
my-scanner:
  script: my-scan --output $[[ inputs.scanner-output ]]

コンポーネントを使用するプロジェクトの設定:

include:
  - component: $CI_SERVER_FQDN/path/to/project/my-scanner@1.0.0
    inputs:
      scanner-output: yaml

CI/CD変数を優先して使うべきケースもあります。例:

定義済み変数を使用して、ユーザーのプロジェクトに合わせてコンポーネントを自動的に設定する。
機密性の高い値をプロジェクト設定でマスクまたは保護されたCI/CD変数として保存するよう、ユーザーに依頼する。

CI/CDカタログ

プラン: Free、Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

CI/CDカタログは、CI/CDワークフローを拡張するために使用できる公開済みCI/CDコンポーネントを含むプロジェクトのリストです。

誰でもコンポーネントプロジェクトを作成してCI/CDカタログに追加したり、既存のプロジェクトにコントリビュートして利用可能なコンポーネントを改善したりできます。

クリック操作のデモについては、CI/CDカタログベータ版の製品ツアーを参照してください。

CI/CDカタログを表示する

CI/CDカタログにアクセスして、利用可能な公開済みコンポーネントを表示するには、次のようにします:

左側のサイドバーで、検索または移動先を選択します。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
検索を選択します。
CI/CDカタログを選択します。

または、プロジェクトのパイプラインエディタをすでに開いている場合は、CI/CDカタログを選択できます。

CI/CDカタログ内のコンポーネントの表示レベルは、コンポーネントのソースプロジェクトの表示レベルの設定に従います。ソースプロジェクトの設定に応じて、コンポーネントは次のように表示されます:

非公開: ソースコンポーネントプロジェクトのゲストロール以上が割り当てられたユーザーにのみ表示されます。コンポーネントを使用するには、少なくともレポーターロールが必要です。
内部: GitLabインスタンスにログインしているユーザーにのみ表示されます。
公開: GitLabインスタンスへのアクセス権を付与されているすべてのユーザーに表示されます。

コンポーネントプロジェクトを公開する

CI/CDカタログにコンポーネントプロジェクトを公開するには、次の手順を実行する必要があります:

プロジェクトをカタログプロジェクトとして設定します。
新しいリリースを公開します。

コンポーネントプロジェクトをカタログプロジェクトとして設定する

CI/CDカタログにコンポーネントプロジェクトの公開バージョンを表示するには、プロジェクトをカタログプロジェクトとして設定する必要があります。

前提要件:

プロジェクトのオーナーロールが必要です。

プロジェクトをカタログプロジェクトとして設定するには、次のようにします:

左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
設定 > 一般を選択します。
可視性、プロジェクトの機能、権限を展開します。
CI/CDカタログプロジェクトの切り替えをオンにします。

プロジェクトは、新しいリリースを公開した後にのみカタログで検索可能になります。

この設定を自動で有効にするには、mutationcatalogresourcescreate GraphQLエンドポイントを使用します。イシュー463043は、これをREST APIでも公開することを提案しています。

新しいリリースを公開する

CI/CDコンポーネントは、CI/CDカタログに掲載されていなくても使用できます。ただし、コンポーネントのリリースをカタログに公開した方が、他のユーザーが容易に見つけられるようになります。

前提要件:

プロジェクトのメンテナーロール以上が必要です。
プロジェクトは次の条件を満たしている必要があります:
- カタログプロジェクトとして設定されている。
- プロジェクトの説明が定義されている。
- リリース対象のタグのコミットSHAに対応するルートディレクトリにREADME.mdファイルが存在する。
- リリース対象のタグのコミットSHAに対応するtemplates/ディレクトリ内にCI/CDコンポーネントが少なくとも1つ存在する。
リリースを作成するには、リリースAPIではなく、CI/CDジョブでreleaseキーワードを使用する必要があります。

コンポーネントの新しいバージョンをカタログに公開するには、次のようにします:

タグが作成されたときに新しいリリースを作成するreleaseキーワードを使用するジョブを、プロジェクトの.gitlab-ci.ymlファイルに追加します。リリースジョブを実行する前に、コンポーネントをテストするようにタグパイプラインを設定する必要があります。例:
```
create-release:
  stage: release
  image: registry.gitlab.com/gitlab-org/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"
```
リリース用の新しいタグを作成します。これにより、リリースを作成するジョブを含むタグパイプラインがトリガーされます。タグはセマンティックバージョニングを使用する必要があります。

リリースジョブが正常に完了すると、リリースが作成され、新しいバージョンがCI/CDカタログに公開されます。

セマンティックバージョニング

コンポーネントの新しいバージョンをカタログにタグ付けしてリリースする場合は、セマンティックバージョニングを使用する必要があります。セマンティックバージョニングは、メジャー、マイナー、パッチなど、どの種類の変更であるかを伝えるための標準規格です。

たとえば、1.0.0、2.3.4、1.0.0-alphaはすべて有効なセマンティックバージョンです。

コンポーネントプロジェクトの公開を停止する

コンポーネントプロジェクトをカタログから削除するには、プロジェクト設定でCI/CD Catalog resource（CI/CDカタログリソース）の切り替えをオフにします。

このアクションにより、コンポーネントプロジェクトに関するメタデータと、そのカタログに公開済みのバージョンが破棄されます。プロジェクトとそのリポジトリはまだ存在しますが、カタログには表示されません。

コンポーネントプロジェクトをカタログに再度公開するには、新しいリリースを公開する必要があります。

検証済みのコンポーネント作成者

一部のCI/CDコンポーネントにはアイコンが付けられており、そのコンポーネントがGitLabまたはインスタンス管理者によって検証されたユーザーによって作成および管理されていることを示しています:

GitLabが管理（）: GitLabが作成および管理しているGitLab.comコンポーネント。
GitLabパートナー（）: GitLabによって検証済みのパートナーが個別に作成および管理しているGitLab.comコンポーネント。
GitLabパートナーは、GitLabパートナーアライアンスのメンバーに連絡して、GitLab.com上のネームスペースにGitLab検証済みのフラグを立ててもらうことができます。これにより、そのネームスペースにあるCI/CDコンポーネントに、GitLabパートナーコンポーネントのバッジが付けられます。パートナーアライアンスのメンバーは、検証済みのパートナーに代わって内部リクエストイシュー（GitLabチームメンバーのみ）を作成します。
GitLabパートナーが作成したコンポーネントは、いかなる種類の保証もなく、as-is（現状のまま）で提供されます。GitLabパートナーが作成したコンポーネントの使用は、エンドユーザーご自身の責任で行ってください。GitLabは、エンドユーザーによるコンポーネントの使用に関して、いかなる補償義務も、いかなる種類の責任も負わないものとします。そのようなコンテンツの使用、およびそれに関連する責任は、コンテンツの公開者とエンドユーザーとの間で生じるものとします。
検証済みの作成者（）: 管理者によって検証済みのユーザーが作成および管理しているコンポーネント。

コンポーネントを検証済みの作成者による管理として設定する

プラン: Free、Premium、Ultimate
提供形態: GitLab Self-Managed、GitLab Dedicated

GitLab管理者は、CI/CDコンポーネントを、検証済みの作成者によって作成および管理されるものとして設定できます:

管理者アカウントでインスタンス内のGraphiQLを開きます（例: https://gitlab.example.com/-/graphql-explorer）。

次のクエリを実行します。ただし、root-level-groupは、検証するコンポーネントのルートネームスペースに置き換えてください:

mutation {
  verifiedNamespaceCreate(input: { namespacePath: "root-level-group",
    verificationLevel: VERIFIED_CREATOR_SELF_MANAGED
    }) {
    errors
  }
}

このクエリが完了すると、ルートネームスペース内のプロジェクトにあるすべてのコンポーネントが検証済みとなります。CI/CDカタログのコンポーネント名の横に検証済みの作成者バッジが表示されます。

コンポーネントからバッジを削除するには、verificationLevelにUNVERIFIEDを指定し、同じクエリを再度実行します。

CI/CDテンプレートをコンポーネントに変換する

include:構文を使用してプロジェクト内で利用している既存のCI/CDテンプレートは、次の手順により、CI/CDコンポーネントに変換できます:

コンポーネントを既存のコンポーネントプロジェクトの一部として他のコンポーネントとグループ化するか、新しいコンポーネントプロジェクトを作成するかを決定します。
ディレクトリ構造に従って、コンポーネントプロジェクト内にYAMLファイルを作成します。
元のテンプレートYAMLファイルの内容を、新しいコンポーネントYAMLファイルにコピーします。
新しいコンポーネントの設定を次のようにリファクタリングします:
- コンポーネントの作成に関するガイダンスに従います。
- マージリクエストパイプラインを有効にしたり、効率化したりするなど、設定を改善します。
コンポーネントリポジトリの.gitlab-ci.ymlを活用して、コンポーネントに対する変更をテストします。
タグを付けてコンポーネントをリリースします。

詳細については、Go CI/CDテンプレートをCI/CDコンポーネントに移行する実践的な例を参照してください。

GitLab Self-ManagedでGitLab.comコンポーネントを使用する

プラン: Premium、Ultimate
提供形態: GitLab Self-Managed、GitLab Dedicated

新たにインストールされたGitLabインスタンスのCI/CDカタログには、最初は公開済みのCI/CDコンポーネントは存在しません。インスタンスのカタログにデータを追加するには、次のようにします:

独自のコンポーネントを公開する。
GitLab Self-ManagedインスタンスでGitLab.comからコンポーネントをミラーリングする。

GitLab Self-ManagedインスタンスでGitLab.comコンポーネントをミラーリングするには、次のようにします:

ネットワーク送信リクエストがgitlab.comに対して許可されていることを確認します。
コンポーネントプロジェクトをホスティングするためのグループを作成します（推奨グループ: components）。
新しいグループ内にコンポーネントプロジェクトのミラーを作成します。
リポジトリのミラーリングではプロジェクトの説明がコピーされないため、コンポーネントプロジェクトのミラーにプロジェクトの説明を記述します。
セルフホストのコンポーネントプロジェクトをカタログリソースとして設定します。
タグ（通常は最新のタグ）のパイプラインを実行して、セルフホストのコンポーネントプロジェクトに新しいリリースを公開します。