CI/CD 组件

Tier: 基础版, 专业版, 旗舰版
Offering: JihuLab.com, 私有化部署

History

引入于极狐GitLab 16.0，作为实验功能，使用名为 ci_namespace_catalog_experimental 的功能标志。默认禁用。
在极狐GitLab 16.2 中，为 JihuLab.com 和私有化部署启用。
功能标志 ci_namespace_catalog_experimental 在极狐GitLab 16.3 中被移除。
在极狐GitLab 16.6 中被更改为 beta。
在极狐GitLab 17.0 中 GA。

CI/CD 组件#

极狐GitLab CI/CD 组件是一个可重用的单一流水线配置单元。使用组件可以创建一个较大流水线的一小部分，甚至可以组合成完整的流水线配置。

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

极狐GitLab CI/CD 组件类似于其他使用 include 关键字添加的配置，但有几个优势：

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

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

有关介绍和动手示例，请参见 Efficient DevSecOps workflows with reusable CI/CD components。

组件项目#

History

每个项目的最大组件数在极狐GitLab 16.9 中从 10 更改为 30。

组件项目是一个极狐GitLab项目，其中的仓库托管一个或多个组件。项目中的所有组件都一起进行版本管理，每个项目最多允许 30 个组件。

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

创建组件项目#

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

创建一个新项目，并包含一个 README.md 文件：
- 确保描述清晰介绍组件。
- 可选。在项目创建后，您可以添加项目头像。
发布到 CI/CD catalog 的组件会在显示组件项目摘要时使用描述和头像。

为每个组件添加一个 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。

每个组件还可以有自己的 README.md 文件，提供更详细的信息，并可以从顶级 README.md 文件链接。这有助于提供更好的组件项目概览及其使用方法。

您还应该：

配置项目的 .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-simple-component.yml
3│   └── my-complex-component/
4│       ├── template.yml
5│       ├── Dockerfile
6│       └── test.sh
7├── LICENSE.md
8├── README.md
9└── .gitlab-ci.yml

在这个例子中：

my-simple-component 组件的配置定义在一个文件中。
my-complex-component 组件的配置包含多个文件在一个目录中。

使用组件#

要将组件添加到项目的 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 或作为目录 templates/secret-detection/ 包含 template.yml。
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 中，但可以用于测试。

语义版本范围#

History

引入于极狐GitLab 16.11。

在引用 CI/CD Catalog 组件时，您可以使用一种特殊格式来指定范围内的最新语义版本。

这种方法为组件消费者和作者提供了显著的优势：

对于用户而言，使用版本范围是自动接收小版本或补丁更新的绝佳方式，而不会因主要版本发布而冒破坏性更改的风险。这确保了您的流水线始终与最新的错误修复和安全补丁保持同步，同时保持稳定性。
对于组件作者而言，使用版本范围允许主要版本发布，而不会立即破坏现有流水线的风险。指定版本范围的用户继续使用最新兼容的小版本或补丁版本，允许他们在自己的节奏上更新流水线。

要指定：

小版本的最新发布版本，请在引用中使用主要和小版本号，但不使用补丁版本号。例如，使用 1.1 来使用以 1.1 开头的最新版本，包括 1.1.0 或 1.1.9，但不包括 1.2.0。
主要版本的最新发布版本，请在引用中仅使用主要版本号。例如，使用 1 来使用以 1. 开头的最新版本，例如 1.0.0 或 1.9.9，但不包括 2.0.0。
所有版本，使用 ~latest 来使用最新发布版本。

例如，组件按以下确切顺序发布：

1.0.0
1.1.0
2.0.0
1.1.1
1.2.0
2.1.0
2.0.1

在这个例子中，引用组件时：

1 将使用 1.2.0 版本。
1.1 将使用 1.1.1 版本。
~latest 将使用 2.1.0 版本。

预发布版本在引用版本范围时永远不会被获取。要获取预发布版本，请指定完整版本，例如 1.0.1-rc。

编写组件#

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

管理依赖项#

虽然组件可以转而使用其他组件，但请确保仔细选择依赖项。要管理依赖项，您应该：

将依赖项保持在最低限度。通常少量重复比拥有依赖项更好。
尽可能依赖本地依赖项。例如，使用 include:local 是确保在多个文件之间使用相同 Git SHA 的好方法。
在依赖于其他项目的组件时，将其版本固定为来自 catalog 的发布版本，而不是使用移动目标版本，例如 ~latest 或 Git 引用。使用发布版本或 Git SHA 保证您始终获取相同的修订版，并且组件使用者获得一致的行为。
通过固定到较新的发布版本来定期更新依赖项。然后发布更新依赖项的组件新版本。

编写清晰的 README.md#

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

文档应以项目中组件提供的功能摘要开始。
如果项目包含多个组件，请使用目录帮助用户快速跳转到特定组件的详细信息。
添加一个 ## Components 部分，包含像 ### Component A 的子部分，用于项目中的每个组件。
在每个组件部分中：
- 添加组件的功能描述。
- 添加至少一个 YAML 示例，展示如何使用它。
- 如果组件使用输入，请添加一个表格，显示所有输入的名称、描述、类型和默认值。
- 如果组件使用任何变量或密钥，这些也应该记录。
如果欢迎贡献，推荐添加 ## Contribute 部分。

如果某个组件需要更多说明，请在组件目录中添加额外的文档文件，并从主 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

测试组件#

在开发工作流程中测试极狐GitLab 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 "$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/release-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 镜像的组件可能需要一些示例 Dockerfiles 进行测试。

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

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

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

在您的组件中使用其他组件时，使用 $CI_SERVER_FQDN 而不是您实例的完全限定域名（如 jihulab.com）。

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

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

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

确保组件及其测试流水线也能在极狐GitLab私有化部署上工作。虽然极狐GitLab.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/

用输入替换硬编码值#

避免在极狐GitLab 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 关键字的值类似，应避免在极狐GitLab 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#

Tier: Free, Premium, Ultimate
Offering: JihuLab.com, 极狐GitLab私有化部署, 极狐GitLab Dedicated

History

引入于极狐GitLab 16.1，作为实验功能。
在极狐GitLab 16.7 中移动至beta。
在极狐GitLab 17.0 中 GA。

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

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

查看 CI/CD Catalog#

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

在左侧边栏中选择 搜索或转到。
选择 Explore。
选择 CI/CD Catalog。

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

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

私有的组件仅对被分配至少为来源组件项目客人角色的用户可见。
内部的组件仅对登录极狐GitLab实例的用户可见。
公共的组件对任何具有极狐GitLab实例访问权限的人可见。

发布组件项目#

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

将项目设置为 catalog 项目。
发布新版本。

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

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

前提条件：

您必须拥有项目的所有者角色。

要将项目设置为 catalog 项目：

在左侧边栏中选择 搜索或转到 并找到您的项目。
选择 设置 > 通用。
展开 可见性、项目功能、权限。
打开 CI/CD 目录项目 切换。

项目只有在您发布新版本后才会在 catalog 中可找到。

要使用自动化启用此设置，您可以使用 mutationcatalogresourcescreate GraphQL 端点。

发布新版本#

极狐GitLab CI/CD 组件可以使用而无需在 CI/CD catalog 中列出。然而，在 catalog 中发布组件的版本使其他用户可以发现它。

前提条件：

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

要发布组件的新版本到 catalog：

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

yaml
1create-release:
2  stage: release
3  image: registry.gitlab.com/gitlab-org/release-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"

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

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

语义版本#

History

引入于极狐GitLab 16.10。

当标记并发布新版本到 Catalog 时，您必须使用语义版本。语义版本是传达更改是主要、更改、补丁或其他类型更改的标准。

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

取消发布组件项目#

要从 catalog 中移除组件项目，在项目设置中关闭CI/CD Catalog resource 切换。

此操作将销毁有关组件项目及其在 catalog 中发布版本的元数据。项目及其仓库仍然存在，但在 catalog 中不可见。

要再次在 catalog 中发布组件项目，您需要发布新版本。

已验证的组件创建者#

History

引入于极狐GitLab 16.11。

一些极狐GitLab CI/CD 组件带有图标徽章，显示该组件是由极狐GitLab验证的用户创建和维护的：

极狐GitLab维护（
）：由极狐GitLab创建和维护的组件。
极狐GitLab合作伙伴（
）：由极狐GitLab验证的合作伙伴独立创建和维护的组件。

极狐GitLab合作伙伴可以联系极狐GitLab合作伙伴联盟成员，要求其命名空间标记为极狐GitLab验证，然后在命名空间中的任何极狐GitLab CI/CD 组件被标记为极狐GitLab合作伙伴组件。合作伙伴联盟成员代表验证合作伙伴创建内部请求问题（仅限极狐GitLab团队成员）：https://jihulab.com/gitlab-com/support/internal-requests/-/issues/new?issuable_template=CI%20Catalog%20Badge%20Request。

极狐GitLab合作伙伴创建的组件是按原样提供的，不提供任何形式的担保。最终用户使用极狐GitLab合作伙伴创建的组件需自行承担风险，极狐GitLab对最终用户使用组件不承担任何赔偿义务或责任。最终用户对这种内容的使用以及相关责任应在内容发布者与最终用户之间。

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

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

决定是否希望组件与其他组件一起分组为现有组件项目的一部分，或者创建新组件项目。
根据目录结构在组件项目中创建一个 YAML 文件。
将原始模板 YAML 文件的内容复制到新的组件 YAML 文件中。
重构新组件的配置以：
- 遵循编写组件的指导。
- 改进配置，例如启用合并请求流水线或使其更高效。
利用组件仓库中的 .gitlab-ci.yml 文件测试组件的更改。
标记并发布组件。

您可以通过遵循一个实际示例，了解有关将 Go CI/CD 模板迁移到极狐GitLab CI/CD 组件的更多信息。

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

Tier: Premium, Ultimate
Offering: 极狐GitLab私有化部署, 极狐GitLab Dedicated

极狐GitLab实例的新安装的 CI/CD catalog 起始时没有已发布的极狐GitLab CI/CD 组件。为了填充您的实例的 catalog，您可以：

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

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

确保允许对 jihulab.com 的网络出站请求。
创建一个群组来托管组件项目（推荐群组：components）。
在新群组中创建组件项目镜像。
为组件项目镜像编写项目描述，因为镜像仓库不会复制描述。
将自托管组件项目设置为 catalog 资源。
在自托管组件项目中通过运行流水线为标签（通常为最新标签）发布新版本。

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

对于组件用户#

由于任何人都可以将组件发布到 catalog，您应该在使用组件之前仔细检查组件。使用极狐GitLab CI/CD 组件需自行承担风险，极狐GitLab无法保证第三方组件的安全性。

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

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

对于组件维护者#

为了维护安全和可信的极狐GitLab CI/CD 组件，并确保您提供给用户的流水线配置的完整性，请遵循以下最佳实践：

使用双重身份验证 (2FA)：确保所有极狐GitLab CI/CD 组件项目的维护者和所有者启用双重身份验证 (2FA)，或强制对群组中的所有用户启用 2FA。
使用保护分支：
- 对组件项目发布使用保护分支。
- 保护默认分支，并保护所有发布分支，使用通配符规则。
- 要求每个人提交合并请求以更改保护分支。对保护分支设置允许推送和合并选项为没有人。
- 阻止对保护分支的强制推送。
签署所有提交：签署组件项目的所有提交。
不鼓励使用 latest：避免在 README.md 中包含使用 @latest 的示例。
限制对其他作业缓存和产物的依赖：仅在绝对必要时在极狐GitLab CI/CD 组件中使用其他作业的缓存和产物。
更新极狐GitLab CI/CD 组件依赖项：定期检查并应用更新以更新依赖项。
仔细审查更改：
- 在合并到默认或发布分支之前，仔细审查极狐GitLab CI/CD 组件流水线配置的所有更改。
- 对所有用户相关的更改使用合并请求审批到极狐GitLab CI/CD 组件 catalog 项目。

故障排除#

content not found 消息#

您可能会在使用 ~latest 版本限定符来引用由catalog 项目托管的组件时收到类似以下的错误消息：

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

在极狐GitLab 16.10 中，~latest 行为已更新。它现在指的是 catalog 资源的最新语义版本。要解决此问题，创建新发布。

错误：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