Help us learn about your current experience with the documentation. Take the survey.

合规流水线（已弃用）

Tier: Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

此功能在 GitLab 17.3 中已弃用并计划在 19.0 中移除。请改用流水线执行策略类型。此更改是破坏性更改。有关更多信息，请参阅迁移指南。

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

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

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

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

有关更多信息，请参阅：

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

流水线执行策略迁移

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

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

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

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

迁移现有合规框架

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

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

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

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

对标记项目的影响

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

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

因此，请就合规流水线配置与项目用户沟通，以减少不确定性和混淆。

多个合规框架

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

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

从项目中移除所有合规框架。
将具有正确合规流水线的合规框架应用到项目。
将额外的合规框架应用到项目。

配置合规流水线

要配置合规流水线：

在左侧边栏，选择搜索或转到并找到您的群组。
选择安全 > 合规中心。
选择框架部分。
选择新框架部分，添加合规框架的信息，包括合规框架配置的路径。使用 path/file.y[a]ml@group-name/project-name 格式。例如：
- .compliance-ci.yml@gitlab-org/gitlab。
- .compliance-ci.yaml@gitlab-org/gitlab。

此配置被应用了合规框架标签的项目继承。在应用了合规框架标签的项目中，合规流水线配置会运行，而不是标记项目自身的流水线配置。

在标记项目中运行流水线的用户至少需要在合规项目上具有 Reporter 角色。

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

示例配置

以下 .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:
    - "# 没有 before 脚本。"
  script:
    - echo "running $FOO"
  after_script:
    - "# 没有 after 脚本。"

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:
    - "# 没有 before 脚本。"
  script:
    - echo "running $FOO"
  after_script:
    - "# 没有 after 脚本。"

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:
    - "# 没有 before 脚本。"
  script:
    - echo "running $FOO"
  after_script:
    - "# 没有 after 脚本。"

include 定义中的 rules 配置避免了合规流水线必须在宿主项目中运行时的循环包含。如果您的合规流水线只在标记项目中运行，可以省略它。

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

前面的示例假设所有项目都在同一项目中托管其流水线配置。如果任何项目使用托管在外部的配置，则示例配置不起作用。有关详细信息，请参阅问题 393960。

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

示例合规流水线配置中的 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：检索配置文件时要使用的 ref，例如 main。

来自项目分支的合并请求中的合规流水线

当合并请求来自分支时，要合并的分支通常只存在于分支中。当创建针对具有合规流水线的项目的此类合并请求时，前面的代码片段会失败并显示 项目 <项目名称> 引用 <分支名称> 不存在！错误消息。此错误发生是因为在目标项目的上下文中，$CI_COMMIT_REF_NAME 计算为不存在的分支名称。

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

例如，对于支持来自项目分支的合并请求流水线和分支流水线的配置，您需要将两个 include 指令与 rules:if 结合使用：

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。