CI/CD 组件

CI/CD 组件是可复用的单一流水线配置单元。您可以使用组件来构建更大流水线的一小部分，甚至组合出完整的流水线配置。

组件可以通过输入参数进行配置，以实现更动态的行为。

CI/CD 组件与使用 include 关键字添加的其他配置类似，但具有以下优势：

• 组件可以列在 CI/CD Catalog中。
• 组件可以发布并使用特定版本。
• 可以在同一项目中定义多个组件，并一起进行版本管理。

除了创建自己的组件，您还可以在 CI/CD Catalog中搜索具有您所需功能的已发布组件。

有关常见问题和更多支持，请参阅 FAQ: GitLab CI/CD Catalog 博客文章。

组件项目#

组件项目是一个极狐GitLab 项目，其代码仓库中托管一个或多个组件。项目中的所有组件一起进行版本管理，每个项目最多可包含 100 个组件。

如果某个组件需要与其他组件采用不同的版本管理方式，则应将该组件移至专用的组件项目。

创建组件项目#

要创建组件项目，您必须：

1. 创建新项目，并包含一个 README.md 文件：

   • 确保描述清晰地介绍该组件。
   • 可选。项目创建后，您可以添加项目头像。

   发布到 CI/CD catalog的组件在显示组件项目摘要时会同时使用描述和头像。

2. 按照所需的目录结构为每个组件添加一个 YAML 配置文件。 例如：

   yaml
   1spec:
   2  inputs:
   3    stage:
   4      default: test
   5---
   6component-job:
   7  script: echo job 1
   8  stage: $[[ inputs.stage ]]

您可以立即使用该组件，但您可能需要考虑 将该组件发布到 CI/CD catalog。

目录结构#

代码仓库必须包含：

• 一个 README.md Markdown 文件，记录代码仓库中所有组件的详细信息。
• 一个顶层 templates/ 目录，包含所有组件配置。 在此目录中，您可以：
  • 为每个组件使用以 .yml 结尾的单个文件，例如 templates/secret-detection.yml。
  • 为每个组件创建包含 template.yml的子目录， 例如 templates/secret-detection/template.yml。使用该组件的其他项目只会使用 template.yml 文件。这些目录中的其他文件不会随组件一起发布， 但可用于测试或构建容器镜像等用途。

组件文件名和子目录名可以包含字母、数字、下划线（_）、连字符（-）和句点（.）。例如，templates/secret-detection.enterprise.yml 和 templates/secret-detection.enterprise/template.yml 都是有效的组件文件名。

您还应该：

• 配置项目的 .gitlab-ci.yml 以测试组件 并发布新版本。
• 添加一个 LICENSE.md 文件，其中包含您选择的、涵盖组件使用方式的许可证。 例如 MIT 或 Apache 2.0 开源许可证。

例如：

• 如果项目只包含一个组件，目录结构应类似于：

  plaintext
  ├── templates/
  │   └── my-component.yml
  ├── LICENSE.md
  ├── README.md
  └── .gitlab-ci.yml

• 如果项目包含多个组件，则目录结构应类似于：

  plaintext
  1├── templates/
  2│   ├── my-component.yml
  3│   └── my-other-component/
  4│       ├── template.yml
  5│       ├── Dockerfile
  6│       └── test.sh
  7├── LICENSE.md
  8├── README.md
  9└── .gitlab-ci.yml

  在此示例中：

  • my-component 组件的配置定义在单个文件中。
  • my-other-component 组件的配置包含目录中的多个文件。 使用该组件的其他项目只能使用 template.yml 文件。

使用组件#

先决条件：

如果您是包含当前群组或项目的父群组的成员：

• 您必须具有项目父群组的可见性级别所设置的最低角色。例如，如果父项目设置为 Private，您必须具有报告者、开发者、维护者或所有者角色。

要将组件添加到项目的 CI/CD 配置中，请使用 include: component 关键字。组件引用的格式为 <fully-qualified-domain-name>/<project-path>/<component-name>@<specific-version>，例如：

yaml
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 或包含 template.yml的目录 templates/secret-detection/。
• 1.0.0 是该组件的版本。

流水线配置和组件配置不会独立处理。当流水线启动时，任何包含的组件配置都会合并到流水线的配置中。如果您的流水线和组件都包含同名的配置，它们可能会以意想不到的方式相互影响。

例如，两个同名的作业会合并为一个作业。同样，如果组件使用 extends 引用的配置与您流水线中的某个作业同名，可能会扩展错误的配置。请确保您的流水线和组件不共享任何同名配置，除非您打算覆盖组件的配置。

要在极狐GitLab 私有化部署实例上使用 JihuLab.com 组件，您必须镜像该组件项目。

组件版本#

按优先级从高到低排列，组件版本可以是：

• 提交 SHA，例如 e3262fdd0914fa823210cdb79a8c421e2cef79d8。
• 标签，例如：1.0.0。如果存在同名的标签和提交 SHA， 提交 SHA 优先于标签。发布到 CI/CD Catalog 的组件 必须使用语义化版本打标签。
• 分支名称，例如 main。如果存在同名的分支和标签， 标签优先于分支。
• ~latest 或部分语义化版本，用于选择 CI/CD Catalog 中 已发布的、符合指定模式的最新版本。仅当您希望始终使用绝对 最新版本（可能包含破坏性变更）时，才使用 ~latest。~latest 不包含预发布版本，例如 1.0.1-rc，这些版本不被视为 可用于生产环境。

您可以使用组件支持的任何版本，但建议使用发布到 CI/CD catalog 的版本。通过提交 SHA 或分支名称引用的版本可能未发布在 CI/CD catalog 中，但可用于测试。

部分语义化版本#

当您引用 CI/CD catalog 组件时，请使用部分语义化版本号或 ~latest 来选择符合您指定规格的最新已发布版本。这些格式仅适用于已发布的 CI/CD catalog 组件，不适用于普通项目组件。

这种方法对组件的使用者和作者都有显著好处：

• 对用户而言，使用部分版本是自动接收 次要或补丁更新的绝佳方式，同时不会面临主要版本带来的破坏性变更风险。这可确保 您的流水线保持最新的缺陷修复和安全补丁， 同时保持稳定性。
• 对组件作者而言，部分版本支持允许发布主要版本 而不会立即破坏现有流水线。指定了 部分版本的用户会继续使用最新的兼容次要或补丁版本， 从而有时间按自己的节奏更新流水线。

使用：

• 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 和其他元数据。

要在组件中使用组件上下文，您必须：

1. 在 spec:component 标头中声明该组件需要哪些组件上下文字段。 spec:component 支持 name、sha、version 和 reference 字段。
2. 在组件模板中（spec 部分之外）使用 CI/CD 表达式 $[[ component.field-name ]] 引用这些上下文字段。

例如，一个引用使用相同版本构建的 Docker 镜像的组件：

yaml
1spec:
2  component: [name, version, reference]
3  inputs:
4    stage:
5      default: build
6---
7
8build-image:
9  stage: $[[ inputs.stage ]]
10  image: registry.example.com/$[[ component.name ]]:$[[ component.version ]]
11  script:
12    - echo "Building with component version $[[ component.version ]]"
13    - echo "Component reference: $[[ component.reference ]]"

您还可以使用组件上下文来引用带版本的资源。

组件 spec 部分#

组件模板中的 spec 部分定义组件的配置和输入。您可以在 spec 部分中使用以下关键字：

• description：提供组件的简短描述，显示在 CI/CD Catalog 中。
• inputs：定义输入参数，供用户自定义组件配置。
• component：声明哪些组件上下文字段可用于插值（如 name、sha、version 和 reference）。

编写组件#

本节介绍一些创建高质量组件项目的最佳实践。

管理依赖项#

虽然组件可以依次使用其他组件，但请务必谨慎选择依赖项。要管理依赖项，您应该：

• 将依赖项保持在最低限度。少量重复通常比引入依赖项更好。
• 尽可能依赖本地依赖项。例如，使用 include:local 是确保 多个文件使用相同 Git SHA 的好方法。
• 当依赖其他项目的组件时，请将其版本固定到目录中的某个发布版本，而不是使用 诸如 ~latest 或 Git 引用之类的移动目标版本。使用发布版本或 Git SHA 可保证您始终 获取相同的修订版本，并且组件的使用者获得一致的行为。
• 通过将依赖项固定到较新的发布版本来定期更新依赖项。然后发布带有更新 依赖项的组件新版本。
• 评估依赖项的权限，并使用所需权限最少的依赖项。 例如，如果您需要构建镜像，请考虑使用 Buildah 而不是 Docker，这样您就 不需要具有特权 Docker 守护进程的 Runner。

编写清晰的 README.md#

每个组件项目都应有清晰、全面的文档。要编写好的 README.md 文件：

• 以组件所提供能力的摘要开头。
• 如果项目包含多个组件，请使用目录 帮助用户快速跳转到特定组件的详细信息。
• 添加一个 ## Components 部分，并为每个组件添加诸如 ### Component A的子部分。
• 在每个组件部分中：
  • 描述该组件的作用。
  • 至少添加一个 YAML 示例，展示如何使用它。
  • 使用 spec:inputs:description 来 记录组件使用的任何变量或密钥。
  • 不要在 README中重复输入文档。输入会自动显示在组件页面上。 请改为链接到已发布的组件。
• 如果欢迎贡献，请添加一个 ## Contribute 部分。

如果组件需要更多说明，请在组件目录中的 Markdown 文件中添加额外文档，并从主 README.md 文件链接过去。例如：

plaintext
1README.md    # with links to the specific docs.md
2templates/
3├── component-1/
4│   ├── template.yml
5│   └── docs.md
6└── component-2/
7    ├── template.yml
8    └── docs.md

有关示例，请参阅 AWS 组件 README。

测试组件#

强烈建议将 CI/CD 组件测试作为开发工作流的一部分，这有助于确保行为一致。

在根目录中创建 .gitlab-ci.yml，在 CI/CD 流水线中测试变更（与任何其他项目一样）。请务必测试组件的行为和潜在副作用。如有需要，您可以使用极狐GitLab API。

例如：

yaml
1include:
2  # include the component located in the current project from the current SHA
3  - component: $CI_SERVER_FQDN/$CI_PROJECT_PATH/my-component@$CI_COMMIT_SHA
4    inputs:
5      stage: build
6
7stages: [build, test, release]
8
9# Check if `component job of my-component` is added.
10# This example job could also test that the included component works as expected.
11# You can inspect data generated by the component, use GitLab API endpoints, or third-party tools.
12ensure-job-added:
13  stage: test
14  image: badouralix/curl-jq
15  # Replace "component job of my-component" with the job name in your component.
16  script:
17    - |
18      route="${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/pipelines/${CI_PIPELINE_ID}/jobs"
19      count=`curl --silent --header "JOB-TOKEN: ${CI_JOB_TOKEN}" "$route" | jq 'map(select(.name | contains("component job of my-component"))) | length'`
20      if [ "$count" != "1" ]; then
21        exit 1; else
22        echo "Component Job present"
23      fi
24
25# If the pipeline is for a new tag with a semantic version, and all previous jobs succeed,
26# create the release.
27create-release:
28  stage: release
29  image: registry.gitlab.com/gitlab-org/cli:latest
30  script: echo "Creating release $CI_COMMIT_TAG"
31  rules:
32    - if: $CI_COMMIT_TAG
33  release:
34    tag_name: $CI_COMMIT_TAG
35    description: "Release $CI_COMMIT_TAG of components repository $CI_PROJECT_PATH"

提交并推送变更后，流水线会测试该组件，如果前面的作业通过，则创建一个发布版本。

使用示例文件测试组件#

在某些情况下，组件需要与之交互的源文件。例如，构建 Go 源代码的组件可能需要一些 Go 示例来进行测试。或者，构建 Docker 镜像的组件可能需要一些示例 Dockerfile 来进行测试。

您可以直接在组件项目中包含此类示例文件，供组件测试期间使用。

您可以在测试组件的示例中了解更多信息。

避免硬编码实例或项目特定的值#

在组件中使用另一个组件时，请使用 $CI_SERVER_FQDN 而不是您实例的完全限定域名（如 gitlab.com）。

在组件中访问极狐GitLab API 时，请使用 $CI_API_V4_URL 而不是您实例的完整 URL 和路径（如 https://gitlab.com/api/v4）。

这些预定义变量可确保您的组件在其他实例上使用时也能正常工作。例如，您可能在极狐GitLab 私有化部署实例上使用 JihuLab.com 组件。

不要假设 API 资源始终是公开的#

确保组件及其测试流水线也能在极狐GitLab 私有化部署上正常工作。JihuLab.com 上公开项目的某些 API 资源可以通过未经身份验证的请求访问。但是，在极狐GitLab 私有化部署实例上，组件项目可能被镜像为私有或内部项目。

重要的是，可以通过输入或变量选择性地提供访问令牌，以便在极狐GitLab 私有化部署实例上对请求进行身份验证。

避免使用全局关键字#

避免在组件中使用全局关键字。在组件中使用这些关键字会影响流水线中的所有作业，包括直接定义在主 .gitlab-ci.yml 或其他包含的组件中的作业。

作为全局关键字的替代方案：

• 将配置直接添加到每个作业，即使这会在组件配置中 造成一些重复。
• 在组件中使用 extends 关键字，但使用 唯一的名称，以降低组件合并到配置中时发生命名冲突的风险。

例如，避免使用 default 全局关键字：

yaml
1# Not recommended
2default:
3  image: ruby:3.0
4
5rspec-1:
6  script: bundle exec rspec dir1/
7
8rspec-2:
9  script: bundle exec rspec dir2/

您可以改为：

• 将配置显式添加到每个作业：

  yaml
  1rspec-1:
  2  image: ruby:3.0
  3  script: bundle exec rspec dir1/
  4
  5rspec-2:
  6  image: ruby:3.0
  7  script: bundle exec rspec dir2/

• 使用 extends 复用配置：

  yaml
  1.rspec-image:
  2  image: ruby:3.0
  3
  4rspec-1:
  5  extends:
  6    - .rspec-image
  7  script: bundle exec rspec dir1/
  8
  9rspec-2:
  10  extends:
  11    - .rspec-image
  12  script: bundle exec rspec dir2/

用输入替换硬编码值#

避免在 CI/CD 组件中使用硬编码值。硬编码值可能会迫使组件用户需要查看组件的内部细节，并调整他们的流水线以配合该组件。

一个常见的有问题的硬编码值关键字是 stage。如果组件作业的阶段是硬编码的，则所有使用该组件的流水线都必须定义完全相同的阶段，或者覆盖该配置。

首选方法是使用 input 关键字来实现动态组件配置。组件用户可以指定他们所需的确切值。

例如，要创建一个带有可由用户定义的 stage 配置的组件：

• 在组件配置中：

  yaml
  1spec:
  2  inputs:
  3    stage:
  4      default: test
  5---
  6unit-test:
  7  stage: $[[ inputs.stage ]]
  8  script: echo unit tests
  9
  10integration-test:
  11  stage: $[[ inputs.stage ]]
  12  script: echo integration tests

• 在使用该组件的项目中：

  yaml
  1stages: [verify, release]
  2
  3include:
  4  - component: $CI_SERVER_FQDN/myorg/ruby/test@1.0.0
  5    inputs:
  6      stage: verify

使用输入定义作业名称#

与 stage 关键字的值类似，您应避免在 CI/CD 组件中硬编码作业名称。当组件的用户可以自定义作业名称时，他们可以防止与其流水线中现有名称的冲突。用户还可以通过使用不同的名称，多次包含具有不同输入选项的同一组件。

使用 inputs 允许组件的用户定义特定的作业名称，或作业名称的前缀。例如：

yaml
1spec:
2  inputs:
3    job-prefix:
4      description: "Define a prefix for the job name"
5    job-name:
6      description: "Alternatively, define the job's name"
7    job-stage:
8      default: test
9---
10
11"$[[ inputs.job-prefix ]]-scan-website":
12  stage: $[[ inputs.job-stage ]]
13  script:
14    - scan-website-1
15
16"$[[ inputs.job-name ]]":
17  stage: $[[ inputs.job-stage ]]
18  script:
19    - scan-website-2

用输入替换自定义 CI/CD 变量#

在组件中使用 CI/CD 变量时，请评估是否应改用 inputs 关键字。当 inputs 是更好的解决方案时，避免要求用户定义自定义变量来配置组件。

输入在组件的 spec 部分中显式定义，并且比变量具有更好的验证。例如，如果未向组件传递必需的输入，极狐GitLab 会返回流水线错误。相比之下，如果未定义变量，其值为空，且不会报错。

例如，使用 inputs 而不是变量来配置扫描器的输出格式：

• 在组件配置中：

  yaml
  1spec:
  2  inputs:
  3    scanner-output:
  4      default: json
  5---
  6my-scanner:
  7  script: my-scan --output $[[ inputs.scanner-output ]]

• 在使用该组件的项目中：

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

在其他情况下，CI/CD 变量可能仍然是首选。例如：

• 使用预定义变量自动配置 组件以匹配用户的项目。
• 要求用户将敏感值存储为项目设置中已屏蔽或受保护的 CI/CD 变量。

CI/CD Catalog#

CI/CD Catalog 是一个包含已发布 CI/CD 组件的项目列表，您可以使用它们来扩展您的 CI/CD 工作流。

任何人都可以创建组件项目并将其添加到 CI/CD Catalog，或为现有项目做出贡献以改进可用的组件。

有关点击式演示，请参阅 CI/CD Catalog 测试版产品导览。

查看 CI/CD Catalog#

要访问 CI/CD Catalog 并查看可供您使用的已发布组件：

1. 在顶部栏中，选择搜索或跳转到。
2. 选择探索。
3. 选择 CI/CD Catalog。

或者，如果您已经在项目的流水线编辑器中， 可以选择 CI/CD Catalog。

CI/CD catalog 中组件的可见性遵循组件源项目的可见性设置。源项目设置为以下内容的组件：

• 私有：仅对在源组件项目中分配了访客、计划者、报告者、开发者、维护者或所有者角色的用户可见。要使用组件，您必须具有报告者、开发者、维护者或所有者角色。
• 内部：仅对登录到极狐GitLab 实例的用户可见。
• 公开：对任何有权访问极狐GitLab 实例的人可见。

列表中的每个 CI/CD Catalog 项目都会显示一个使用次数。此计数表示在过去 30 天内，在流水线中使用过该目录项目中任何组件的唯一项目总数。

查看 CI/CD Catalog 项目分析#

如果您维护 CI/CD catalog 资源，可以查看使用分析，以了解您的组件在各项目中的采用情况。

先决条件：

• 您必须对一个或多个目录资源项目具有维护者或所有者角色。

要查看目录资源分析：

1. 在顶部栏中，选择搜索或跳转到 > 探索。
2. 选择 CI/CD Catalog。
3. 选择分析标签页。

分析视图会显示您具有维护者或所有者角色的目录资源。此视图显示：

• 项目：目录资源名称及其最新发布的版本。
• 使用统计：在过去 30 天内，在流水线中使用过此目录资源中某个组件的唯一项目数量。
• 组件：目录资源最新版本中可用的组件列表。

例如：

您可以使用这些信息来：

• 确定哪些目录资源被最广泛地采用。
• 跟踪您的组件随时间的使用趋势。
• 了解哪些项目正在使用您的目录资源。
• 就组件维护和弃用做出明智的决策。

查看组件使用详情#

如果您维护 CI/CD catalog 组件项目，可以查看详细的组件使用信息，以了解哪些项目使用了这些组件以及使用了哪些版本。这有助于您规划升级、传达弃用信息，并识别使用过时版本的项目。

详情页面还会在每个组件名称旁显示一个使用次数。此计数特定于版本，显示在过去 30 天内使用过该组件版本的唯一项目数量。

先决条件：

• 您必须对目录资源项目具有维护者或所有者角色。

要查看组件使用详情：

1. 在顶部栏中，选择搜索或跳转到 > 探索。
2. 选择 CI/CD Catalog。
3. 从目录中选择一个组件项目。
4. 在详情页面上，选择使用情况标签页。

此标签页列出了在过去 30 天内，在流水线中包含过此项目任何组件的项目。该列表仅包含您有权查看的项目。

详情包括：

• 项目路径：项目的完整路径，并带有指向该项目的链接。
• 状态：如果项目使用了组件的最新版本，则标记为最新。否则为已过时。
• 使用的组件：项目使用的组件名称和版本。

您无法看到的项目会显示为私有项目，且不带链接。

您可以使用这些信息来：

• 识别使用过时组件版本并需要升级的项目。
• 在有新版本可用或弃用组件时通知项目维护者。
• 了解特定组件版本在您组织中的采用情况。

发布组件项目#

要将组件项目发布到 CI/CD catalog 中，您必须：

1. 将项目设置为目录项目。
2. 发布新版本。

将组件项目设置为目录项目#

要使组件项目的已发布版本在 CI/CD catalog 中可见，您必须将该项目设置为目录项目。

先决条件：

• 您必须对项目具有所有者角色。

要将项目设置为目录项目：

1. 在顶部栏中，选择搜索或跳转到并找到您的项目。
2. 在左侧边栏中，选择设置 > 通用。
3. 展开可见性、项目功能、权限。
4. 打开 CI/CD Catalog 项目开关。

只有在您发布新版本后，该项目才能在目录中被找到。

要使用自动化启用此设置，您可以使用 mutationcatalogresourcescreate GraphQL 端点。议题 463043 提议也在 REST API 中公开此功能。

发布新版本#

CI/CD 组件无需列在 CI/CD catalog 中即可使用。 但是，在目录中发布组件的版本可以让其他用户发现它。

先决条件：

• 您必须对项目具有维护者或所有者角色。
• 项目必须：
  • 设置为目录项目。
  • 定义了项目描述。
  • 在正在发布的标签的提交 SHA 的根目录中有一个 README.md 文件。
  • 在正在发布的标签的提交 SHA 的 templates/ 目录中至少有一个 CI/CD 组件。
• 您必须在 CI/CD 作业中使用 release 关键字来创建发布版本， 而不是使用 Releases API。

要将组件的新版本发布到目录：

1. 在项目的 .gitlab-ci.yml 文件中添加一个作业，使用 release 关键字在创建标签时创建新版本。 您应配置标签流水线，以便在运行发布作业之前测试组件。例如：

   yaml
   1create-release:
   2  stage: release
   3  image: registry.gitlab.com/gitlab-org/cli:latest
   4  script: echo "Creating release $CI_COMMIT_TAG"
   5  rules:
   6    - if: $CI_COMMIT_TAG
   7  release:
   8    tag_name: $CI_COMMIT_TAG
   9    description: "Release $CI_COMMIT_TAG of components in $CI_PROJECT_PATH"

2. 为发布版本创建新标签， 这应触发包含负责创建发布版本的作业的标签流水线。 标签必须使用语义化版本。

发布作业成功完成后，发布版本即创建，新版本 会发布到 CI/CD catalog。

语义化版本#

在将组件的新版本打标签并发布到目录时，您必须使用语义化版本。语义化版本是传达变更属于主要、次要、补丁或其他类型变更的标准。

例如，1.0.0、2.3.4 和 1.0.0-alpha 都是有效的语义化版本。

取消发布组件项目#

要将组件项目从目录中移除，请在项目设置中关闭 CI/CD Catalog 资源开关。

要再次将组件项目发布到目录中，您需要发布新版本。

已验证的组件创建者#

某些 CI/CD 组件会显示一个已验证图标。该图标表示该组件由经 GitLab 或实例管理员验证的用户创建并维护：

• GitLab 维护（）：由 GitLab 创建和维护的 JihuLab.com 组件。

• GitLab 合作伙伴（）：由经 GitLab 验证的合作伙伴独立创建 和维护的 JihuLab.com 组件。

  GitLab 合作伙伴可以联系 GitLab Partner Alliance 的成员，将其在 JihuLab.com 上的 命名空间标记为经 GitLab 验证。然后，该命名空间中的 任何 CI/CD 组件都会被标记为 GitLab 合作伙伴组件。Partner Alliance 成员 代表已验证的合作伙伴创建内部请求议题（仅限 GitLab 团队成员）。

  GitLab 合作伙伴创建的组件按原样提供，不附带任何形式的保证。 最终用户使用 GitLab 合作伙伴创建的组件需自行承担风险， 对于最终用户使用该组件，GitLab 不承担任何赔偿义务，也不承担任何类型的责任。 最终用户对此类内容的使用及任何相关责任应由内容发布者与最终用户之间承担。

• 已验证创建者（）：由管理员验证的 用户创建和维护的组件。

将组件设置为由已验证创建者维护#

极狐GitLab 管理员可以将 CI/CD 组件设置为由已验证创建者创建和维护：

1. 使用您的管理员账号在实例中打开 GraphiQL，例如：https://gitlab.example.com/-/graphql-explorer。

2. 运行此查询，将 root-level-group 替换为要验证的组件的根命名空间：

   graphql
   1mutation {
   2  verifiedNamespaceCreate(input: { namespacePath: "root-level-group",
   3    verificationLevel: VERIFIED_CREATOR_SELF_MANAGED
   4    }) {
   5    errors
   6  }
   7}

查询完成后，根命名空间中项目里的所有组件都会被验证。已验证创建者徽章会显示在 CI/CD catalog 中的组件名称旁边。

要从组件中移除该徽章，请使用 verificationLevel的 UNVERIFIED 重新运行该查询。

将 CI/CD 模板转换为组件#

任何您通过 include: 语法在项目中使用的现有 CI/CD 模板都可以转换为 CI/CD 组件：

1. 决定您希望该组件作为现有组件项目的一部分与其他组件分组， 还是创建新的组件项目。
2. 按照目录结构在组件项目中创建 YAML 文件。
3. 将原始模板 YAML 文件的内容复制到新的组件 YAML 文件中。
4. 重构新组件的配置，以：
   • 遵循编写组件的指导。
   • 改进配置，例如通过启用合并请求流水线 或使其更高效。
5. 利用组件代码仓库中的 .gitlab-ci.yml 来测试对组件的变更。
6. 打标签并发布组件。

您可以按照将 Go CI/CD 模板迁移到 CI/CD 组件的实用示例了解更多信息。

在极狐GitLab 私有化部署上使用 JihuLab.com 组件#

全新安装的极狐GitLab 实例的 CI/CD catalog 初始没有任何已发布的 CI/CD 组件。要填充实例的目录，您可以：

• 发布您自己的组件。
• 在您的极狐GitLab 私有化部署实例中镜像来自 JihuLab.com 的组件。

要在您的极狐GitLab 私有化部署实例中镜像 JihuLab.com 组件：

1. 确保允许对 gitlab.com 进行网络出站请求。
2. 创建群组来托管组件项目（推荐的群组：components）。
3. 在新群组中创建组件项目的镜像。
4. 为组件项目镜像编写项目描述， 因为镜像代码仓库不会复制描述。
5. 将私有化部署的组件项目设置为目录资源。
6. 通过为标签（通常是最新标签）运行流水线， 在私有化部署的组件项目中发布新版本。

CI/CD 组件安全最佳实践#

对于组件用户#

由于任何人都可以将组件发布到目录，因此在项目中使用组件之前，您应仔细审查它们。使用极狐GitLab CI/CD 组件的风险由您自行承担，极狐GitLab 无法保证第三方组件的安全性。

使用第三方 CI/CD 组件时，请考虑以下安全最佳实践：

• 审计并审查组件源代码：仔细检查代码，确保其不包含恶意内容。
• 尽量减少对凭据和令牌的访问：
  • 审计组件的源代码，以确认任何凭据或令牌仅用于 执行您预期并授权的操作。
  • 使用范围最小的访问令牌。
  • 避免使用长期有效的访问令牌或凭据。
  • 审计 CI/CD 组件使用的凭据和令牌。
• 使用固定版本：将 CI/CD 组件固定到特定的提交 SHA（首选） 或发布版本标签，以确保流水线中使用的组件的完整性。 仅在您信任组件维护者时才使用发布标签。避免使用 latest。
• 安全地存储密钥：不要在 CI/CD 配置文件中存储密钥。 如果您可以使用外部密钥管理解决方案，请避免在项目设置中存储密钥和凭据。
• 使用临时、隔离的 Runner 环境：尽可能在临时、 隔离的环境中运行组件作业。请注意自管理 Runner 的安全风险。
• 安全地处理缓存和产物：除非绝对必要，否则不要将流水线中其他作业的 缓存或产物传递给 CI/CD 组件作业。
• 限制 CI_JOB_TOKEN 访问：为使用 CI/CD 组件的项目限制 CI/CD 作业令牌（CI_JOB_TOKEN）的项目访问和权限。
• 审查 CI/CD 组件变更：在更改为使用组件的更新提交 SHA 或发布标签之前， 仔细审查对 CI/CD 组件配置的所有变更。
• 审计自定义容器镜像：仔细审查 CI/CD 组件使用的任何自定义容器镜像， 以确保它们不包含恶意内容。

对于组件维护者#

要维护安全可信的 CI/CD 组件，并确保您交付给用户的流水线配置的完整性，请遵循以下最佳实践：

• 使用双重身份验证（2FA）：确保所有 CI/CD 组件项目的维护者 和所有者都启用了 2FA， 或对群组中的所有用户强制实施 2FA。
• 使用受保护分支：
  • 为组件项目发布使用受保护分支。
  • 保护默认分支，并使用通配符规则保护所有发布分支。
  • 要求所有人对受保护分支的变更提交合并请求。将受保护分支的 允许推送和合并选项设置为 No one。
  • 阻止对受保护分支的强制推送。
• 签署所有提交：签署对组件项目的所有提交。
• 不鼓励使用 latest：避免在 README.md中包含使用 @latest的示例。
• 限制对其他作业缓存和产物的依赖：仅在绝对必要时，才在 CI/CD 组件中使用 其他作业的缓存和产物
• 更新 CI/CD 组件依赖项：定期检查并应用依赖项的更新。
• 仔细审查变更：
  • 在合并到默认分支或发布分支之前，仔细审查对 CI/CD 组件流水线配置的 所有变更。
  • 对 CI/CD 组件目录项目的所有面向用户的变更使用合并请求审批。

故障排除#

content not found 消息#

如果您使用 ~latest 或部分语义版本限定符来引用由目录项目托管的组件，可能会看到此错误：

plaintext
This GitLab CI configuration is invalid: Component 'gitlab.com/my-namespace/my-project/my-component@~latest' - content not found

~latest 限定符指的是目录资源的最新语义化版本。要解决此问题，请创建新版本。

错误：Build component error: Spec must be a valid json schema#

如果组件的格式无效，您在创建发布版本时可能会收到类似 Build component error: Spec must be a valid json schema的错误。

此错误可能由空的 spec:inputs 部分引起。如果您的配置不使用任何输入，可以将 spec 部分留空。例如：

yaml
spec:
---

my-component:
  script: echo