• 流水线执行策略迁移
  • 迁移现有的合规框架
• 对标记项目的影响
  • 多个合规框架
• 配置合规流水线
  • 示例配置
    • 合规流水线和托管在外部的自定义流水线配置
    • 在项目分叉中发起的合并请求中的合规流水线
    • 在没有配置文件的项目中的合规流水线
• 确保合规作业始终运行
• 故障排除
  • 合规作业被目标存储库覆盖
  • 预填充变量未显示
  • 错误：作业名称必须唯一

{{< details >}}

• Tier: 旗舰版
• Offering: JihuLab.com, 私有化部署

{{< /details >}}

{{< alert type=”warning” >}}

此功能在极狐GitLab 17.3 中被弃用，并计划在 19.0 中删除。使用流水线执行策略类型取而代之。此更改是一个破坏性变更。更多详情，可以查看迁移指南。

{{< /alert >}}

群组所有者可以在一个单独的项目中配置合规流水线，与其他项目分开。默认情况下，合规流水线配置（例如，.compliance-gitlab-ci.yml）会代替标记项目的流水线配置（例如，.gitlab-ci.yml）运行。

然而，合规流水线配置可以引用标记项目的 .gitlab-ci.yml 文件，以便：

• 合规流水线也可以运行标记项目流水线的作业。这允许集中控制流水线配置。
• 在合规流水线中定义的作业和变量不能被标记项目的 .gitlab-ci.yml 文件中的变量更改。

{{< alert type=”note” >}}

因为一个已知问题，项目流水线必须首先在合规流水线配置的顶部包含，以防止项目在下游覆盖设置。

{{< /alert >}}

有关更多信息，请参阅：

• 示例配置，帮助配置一个合规流水线来运行标记项目流水线配置的作业。
• 创建合规流水线教程。

流水线执行策略迁移

为整合和简化扫描和流水线强制，我们引入了流水线执行策略。我们在极狐GitLab 17.3 中弃用了合规流水线，并将在极狐GitLab 19.0 中移除合规流水线。

流水线执行策略通过链接在流水线执行策略中的单独 YAML 文件（例如，pipeline-execution.yml）扩展项目的 .gitlab-ci.yml 文件。

默认情况下，当创建新的合规框架时，您会被引导使用流水线执行策略类型，而不是合规流水线。

现有的合规流水线必须迁移。客户应尽快从合规流水线迁移到新的 流水线执行策略类型。

迁移现有的合规框架

要迁移现有的合规框架以使用流水线执行策略类型：

1. 在左侧边栏中选择 搜索或转到 并找到您的群组。
2. 选择 安全 > 合规中心。
3. 编辑 现有的合规框架。
4. 在出现的横幅中，选择 将流水线迁移到策略，以在安全策略中创建一个新策略。
5. 再次编辑合规框架以移除合规流水线。

有关更多信息，请参阅 安全策略项目。

如果在迁移过程中收到 流水线执行策略错误：作业名称必须唯一 错误，请参阅 相关故障排除信息。

对标记项目的影响

用户无法知道已配置合规流水线，可能会困惑为什么自己的流水线根本没有运行，或者包含他们自己没有定义的作业。

在标记项目上编写流水线时，没有指示已配置合规流水线。项目级别的唯一标记是合规框架标签本身，但标签并不说明框架是否已配置合规流水线。

因此，向项目用户传达合规流水线配置，以减少不确定性和困惑。

多个合规框架

您可以应用于单个项目 多个已配置合规流水线的合规框架。 在这种情况下，只有第一个应用于项目的合规框架包含其合规流水线在项目流水线中。

为确保正确的合规流水线包含在项目中：

1. 从项目中移除所有合规框架。
2. 将包含正确合规流水线的合规框架应用于项目。
3. 将其他合规框架应用于项目。

配置合规流水线

{{< history >}}

• 引入于极狐GitLab 15.11，合规框架移至合规中心。

{{< /history >}}

要配置合规流水线：

1. 在左侧边栏中选择 搜索或转到 并找到您的群组。
2. 选择 安全 > 合规中心。
3. 选择 框架 部分。

4. 选择 新框架 部分，添加合规框架的信息，包括合规框架配置的路径。使用 path/file.y[a]ml@group-name/project-name 格式。例如：

   • .compliance-ci.yml@gitlab-org/gitlab。
   • .compliance-ci.yaml@gitlab-org/gitlab。

此配置继承自应用合规框架标签的项目。在应用合规框架标签的项目中，合规流水线配置代替标记项目自己的流水线配置运行。

在标记项目中运行流水线的用户必须至少在合规项目中拥有 报告者 角色。

当用于强制扫描执行时，此功能与 扫描执行策略 有一些重叠。我们尚未统一这两个功能的用户体验。有关这两个功能之间的相似性和差异的详细信息，请参阅 强制执行扫描。

示例配置

以下示例 .compliance-gitlab-ci.yml 包含 include 关键字，以确保标记项目流水线配置也执行。

include:  # 执行单个项目的配置（如果项目包含 .gitlab-ci.yml）
  - project: '$CI_PROJECT_PATH'
    file: '$CI_CONFIG_PATH'
    ref: '$CI_COMMIT_SHA' # 必须定义，否则 MR 流水线总是使用默认分支
    rules:
      - if: $CI_PROJECT_PATH != "my-group/project-1" # 必须在托管此配置的项目之外运行。

# 允许合规团队控制阶段/作业的排序和交织。
# 没有定义作业的阶段将保持隐藏。
stages:
  - pre-compliance
  - build
  - test
  - pre-deploy-compliance
  - deploy
  - post-compliance

variables:  # 可以通过在项目的本地 .gitlab-ci.yml 中设置作业特定变量来覆盖
  FOO: sast

sast:  # 这些属性都不能被项目的本地 .gitlab-ci.yml 覆盖
  variables:
    FOO: sast
  image: ruby:2.6
  stage: pre-compliance
  rules:
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push"
      when: never
    - when: always  # 或者 when: on_success
  allow_failure: false
  before_script:
    - "# 没有前置脚本。"
  script:
    - echo "running $FOO"
  after_script:
    - "# 没有后置脚本。"

sanity check:
  image: ruby:2.6
  stage: pre-deploy-compliance
  rules:
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push"
      when: never
    - when: always  # 或者 when: on_success
  allow_failure: false
  before_script:
    - "# 没有前置脚本。"
  script:
    - echo "running $FOO"
  after_script:
    - "# 没有后置脚本。"

audit trail:
  image: ruby:2.7
  stage: post-compliance
  rules:
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push"
      when: never
    - when: always  # 或者 when: on_success
  allow_failure: false
  before_script:
    - "# 没有前置脚本。"
  script:
    - echo "running $FOO"
  after_script:
    - "# 没有后置脚本。"

include 定义中的 rules 配置避免循环包含，以防合规流水线必须能够在托管项目本身中运行。 如果您的合规流水线只运行在标记项目中，可以省略它。

合规流水线和托管在外部的自定义流水线配置

上面的示例假设所有项目都在同一个项目中托管其流水线配置。 如果任何项目使用托管在外部的配置，则示例配置不起作用。

对于使用外部托管配置的项目，您可以尝试以下解决方案：

• 必须调整示例合规流水线配置中的 include 部分。 例如，使用 include:rules:

  include:
    # 如果自定义路径变量已定义，则包含项目的外部配置文件。
    - project: '$PROTECTED_PIPELINE_CI_PROJECT_PATH'
      file: '$PROTECTED_PIPELINE_CI_CONFIG_PATH'
      ref: '$PROTECTED_PIPELINE_CI_REF'
      rules:
        - if: $PROTECTED_PIPELINE_CI_PROJECT_PATH && $PROTECTED_PIPELINE_CI_CONFIG_PATH && $PROTECTED_PIPELINE_CI_REF
    # 如果任何自定义路径变量未定义，则正常包含项目的内部配置文件。
    - project: '$CI_PROJECT_PATH'
      file: '$CI_CONFIG_PATH'
      ref: '$CI_COMMIT_SHA'
      rules:
        - if: $PROTECTED_PIPELINE_CI_PROJECT_PATH == null || $PROTECTED_PIPELINE_CI_CONFIG_PATH == null || $PROTECTED_PIPELINE_CI_REF == null
  

• 必须向使用外部流水线配置的项目添加 CI/CD 变量。在这个示例中：

  • PROTECTED_PIPELINE_CI_PROJECT_PATH：托管配置文件的项目路径，例如 group/subgroup/project。
  • PROTECTED_PIPELINE_CI_CONFIG_PATH：项目中的配置文件路径，例如 path/to/.gitlab-ci.yml。
  • PROTECTED_PIPELINE_CI_REF：检索配置文件时使用的引用，例如 main。

在项目分叉中发起的合并请求中的合规流水线

当合并请求源自分叉时，要合并的分支通常仅存在于分叉中。 当针对具有合规流水线的项目创建此类合并请求时，上述代码片段会因 项目 <project-name> 引用 <branch-name> 不存在！ 错误消息而失败。 此错误发生是因为在目标项目的上下文中，$CI_COMMIT_REF_NAME 评估为不存在的分支名称。

要获取正确的上下文，请使用 $CI_MERGE_REQUEST_SOURCE_PROJECT_PATH 而不是 $CI_PROJECT_PATH。 此变量仅在 合并请求流水线 中可用。

例如，对于支持项目分叉中发起的合并请求和分支流水线的配置，需要使用 rules:if 结合两个 include 指令:

include:  # 执行单个项目的配置（如果项目包含 .gitlab-ci.yml）
  - project: '$CI_MERGE_REQUEST_SOURCE_PROJECT_PATH'
    file: '$CI_CONFIG_PATH'
    ref: '$CI_COMMIT_REF_NAME'
    rules:
      - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
  - project: '$CI_PROJECT_PATH'
    file: '$CI_CONFIG_PATH'
    ref: '$CI_COMMIT_REF_NAME'
    rules:
      - if: $CI_PIPELINE_SOURCE != 'merge_request_event'

在没有配置文件的项目中的合规流水线

上述示例配置假设所有项目都包含一个流水线配置文件（默认情况下为 .gitlab-ci.yml）。然而，在没有配置文件的项目中（因此默认情况下没有流水线），合规流水线失败，因为 include:project 中指定的文件是必需的。

要仅在目标项目中存在时包含配置文件，请使用 rules:exists:project:

include:  # 执行单个项目的配置
  - project: '$CI_PROJECT_PATH'
    file: '$CI_CONFIG_PATH'
    ref: '$CI_COMMIT_SHA'
    rules:
      - exists:
          paths:
            - '$CI_CONFIG_PATH'
          project: '$CI_PROJECT_PATH'
          ref: '$CI_COMMIT_SHA'

在这个示例中，只有当给定 ref 在 exists:project: $CI_PROJECT_PATH' 中的项目存在时，才会包含配置文件。

如果在合规流水线配置中未指定 exists:project，它将在定义 include 的项目中搜索文件。在合规流水线中，示例中的 include 定义在托管合规流水线配置文件的项目中，而不是运行流水线的项目。

确保合规作业始终运行

合规流水线使用极狐GitLab CI/CD，为您定义任何类型的合规作业提供了极大的灵活性。根据您的目标，这些作业可以配置为：

• 被用户修改。
• 不可修改。

通常，如果合规作业中的值：

• 已设置，则不能被项目级配置更改或覆盖。
• 未设置，则可能在项目级配置中设置。

根据您的使用情况，这两者可能是想要或不想要的。

以下是确保这些作业始终按照您定义的方式运行，并且下游项目级流水线配置不能更改它们的一些最佳实践：

• 为每个合规作业添加 rules:when:always 块。这确保它们不可修改并始终运行。
• 显式设置作业引用的任何变量。这：
  • 确保项目级流水线配置不会设置它们并改变其行为。例如，请参阅示例配置中的 before_script 和 after_script 配置。
  • 包括任何驱动作业逻辑的作业。
• 显式设置运行作业的容器镜像。这确保您的脚本步骤在正确的环境中执行。
• 显式设置任何相关的极狐GitLab预定义作业关键字。这确保您的作业使用您想要的设置，并且不会被项目级流水线覆盖。

故障排除

合规作业被目标存储库覆盖

如果在合规流水线配置中使用 extends 语句，合规作业会被目标存储库作业覆盖。例如，您可能拥有以下 .compliance-gitlab-ci.yml 配置：

"compliance job":
  extends:
    - .compliance_template
  stage: build

.compliance_template:
  script:
    - echo "take compliance action"

您可能还拥有以下 .gitlab-ci.yml 配置：

"compliance job":
  stage: test
  script:
    - echo "overwriting compliance action"

此配置导致目标存储库流水线覆盖合规流水线，并显示以下消息： overwriting compliance action。

为了避免覆盖合规作业，请不要在合规流水线配置中使用 extends 关键字。例如，您可能拥有以下 .compliance-gitlab-ci.yml 配置：

"compliance job":
  stage: build
  script:
    - echo "take compliance action"

您可能还拥有以下 .gitlab-ci.yml 配置：

"compliance job":
  stage: test
  script:
    - echo "overwriting compliance action"

此配置不会覆盖合规流水线，并显示以下消息： take compliance action。

预填充变量未显示

由于一个已知问题，极狐GitLab 15.3 及更高版本中的合规流水线可能会阻止预填充变量在手动启动流水线时出现。

要解决此问题，请在执行单个项目配置的 include: 语句中使用 ref: '$CI_COMMIT_SHA'，而不是 ref: '$CI_COMMIT_REF_NAME'。

示例配置已更新为此更改：

include:
  - project: '$CI_PROJECT_PATH'
    file: '$CI_CONFIG_PATH'
    ref: '$CI_COMMIT_SHA'

错误：作业名称必须唯一

要配置合规流水线，示例配置建议使用 include.project 包括单个项目配置。

该配置可能导致运行项目流水线时出现错误：流水线执行策略错误：作业名称必须唯一。 此错误发生是因为流水线执行策略包括项目的 .gitlab-ci.yml 并尝试插入作业，而作业已在流水线中声明。

要解决此错误，请从链接在流水线执行策略中的单独 YAML 文件中移除 include.project。