CI/CD 组件（实验功能）

引入于 16.0 版本，作为实验功能。

在私有化部署版上，此功能默认不可用。要使其可用，需要管理员启用功能标志 ci_namespace_catalog_experimental。 在 SaaS 版上，此功能不可用。此功能尚未准备好用于生产。

组件库

组件库是一个极狐GitLab 项目，托管一个或多个流水线组件。流水线组件是可重用的单个流水线配置单元。您可以使用它们来组成整个流水线配置或更大流水线的一小部分。它可以选择采用输入参数。

创建组件库

要创建组件库，您必须：

  1. 创建一个新项目，带有 README.md 文件。

  2. 在项目的根目录中创建一个 template.yml 文件，其中包含您要作为组件提供的配置。例如： 

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

目录结构

组件库可以托管一个或多个组件。

组件库必须遵循强制文件结构，其中包含：

  • template.yml：组件配置，每个组件一个文件。如果只有一个组件，这个文件可以放在项目的根目录下。如果有多个组件，每个文件必须位于单独的子目录中。
  • README.md：解释库中所有组件详细信息的文档文件。

例如项目名为 my-component，并且位于名为 my-username 的个人命名空间中：

  • 包含单个组件和用于测试组件的简单流水线，则文件结构可能是： 

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

    该组件可以使用路径 gitlab.example.com/my-username/my-component@<version> 引用。

  • 包含一个默认组件和多个子组件，则文件结构可能是： 

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

    这些组件由以下路径标识：

    • gitlab.example.com/my-username/my-component
    • gitlab.example.com/my-username/my-component/unit
    • gitlab.example.com/my-username/my-component/integration

在根目录中没有 template.yml 的情况下，您可以拥有一个没有默认组件的组件仓库。

补充说明：

不支持组件嵌套，例如： 

├── unit/
│   └── template.yml
│   └── another_folder/
│       └── nested_template.yml

测试组件

强烈建议将测试组件作为开发工作流程的一部分，以确保质量保持高标准。

与任何其他项目一样，您可以通过在根目录中创建 .gitlab-ci.yml 来测试 CI/CD 流水线中的更改。

例如： 

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

stages: [build, test, release]

# Expect `component-job` is added.
# This is an example of testing that the included component works as expected.
# You can leverage GitLab API endpoints or 3rd party tools to inspect data generated by the component.
ensure-job-added:
  stage: test
  image: badouralix/curl-jq
  script:
    - |
      route="https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/pipelines/$CI_PIPELINE_ID/jobs"
      count=`curl --silent --header "PRIVATE-TOKEN: $API_TOKEN" $route | jq 'map(select(.name | contains("component-job"))) | length'`
      if [ "$count" != "1" ]; then
        exit 1
      fi

# If we are tagging a release with a specific convention ("v" + number) and all
# previous checks succeeded, we proceed with creating a release automatically.
create-release:
  stage: release
  image: registry.gitlab.com/gitlab-org/release-cli:latest
  rules:
    - if: $CI_COMMIT_TAG =~ /^v\d+/
  script: echo "Creating release $CI_COMMIT_TAG"
  release:
    tag_name: $CI_COMMIT_TAG
    description: "Release $CI_COMMIT_TAG of components repository $CI_PROJECT_PATH"

提交和推送更改后，流水线会测试组件，如果测试通过则发布。

发布组件

组件库在 CI 流水线中使用 release 关键字发布。

与上面的示例一样，在为标签引用运行的流水线中通过所有测试后，我们可以发布组件库的新版本。

组件库的所有发布版本都显示在特定资源的组件目录页面中，为用户提供有关官方发布的信息。

在 CI/CD 配置中使用组件

流水线组件由格式为 <fully-qualified-doman-name>/<component-path>@<version> 的唯一地址标识，其中包含：

  • 完全限定域名 (FQDN)：FQDN 必须与极狐GitLab 主机匹配。
  • 特定：组件的版本可以是（按照优先级高的顺序）：
    • 提交 SHA，例如 jihulab.com/gitlab-cn/dast@e3262fdd0914fa823210cdb79a8c421e2cef79d8。
    • 标签，例如 gitlab.com/gitlab-org/dast@1.0。
    • ~latest，这是一个特殊版本，它始终指向最新发布的标签，例如 jihulab.com/gitlab-cn/dast@~latest。
    • 分支名称，例如 jihulab.com/gitlab-cn/dast@main。
  • 组件路径：包含项目的完整路径和组件 YAML 文件 template.yml 所在目录。

例如，对于位于 jihulab.com 上的 gitlab-cn/dast 的组件库：

  • 路径 jihulab.com/gitlab-cn/dast 尝试从根目录加载 template.yml。
  • 路径 jihulab.com/gitlab-cn/dast/api-scan 尝试从 /api-scan 目录加载 template.yml。

补充说明：

  • 如果存在同名的标签和分支，则标签优先于分支。
  • 如果标签的名称与存在的提交 SHA 相同，例如 e3262fdd0914fa823210cdb79a8c421e2cef79d8，则提交 SHA 优先于标签。

CI/CD 目录

CI/CD 目录是组件库的列表，每个库都包含您可以添加到 CI/CD 流水线的资源。

将项目标记为目录资源

将组件添加到组件库后，可以立即用于在其他项目中构建流水线。

但是，此仓库不可发现。您必须将此项目标记为目录资源，使其在 CI 目录中可见，以便其他用户可以发现它。

要将项目标记为目录资源，请运行以下 graphQL mutation： 

mutation {
    catalogResourcesCreate(input: { projectPath: "path-to-project"}) {
      errors
  }
}