diff options
Diffstat (limited to 'doc/user/group/compliance_frameworks.md')
| -rw-r--r-- | doc/user/group/compliance_frameworks.md | 101 |
1 files changed, 93 insertions, 8 deletions
diff --git a/doc/user/group/compliance_frameworks.md b/doc/user/group/compliance_frameworks.md index 84cca5800c2..2fca8b7b678 100644 --- a/doc/user/group/compliance_frameworks.md +++ b/doc/user/group/compliance_frameworks.md @@ -94,7 +94,8 @@ mutation { > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/331231) in GitLab 14.2. Group owners can configure a compliance pipeline in a project separate to other projects. By default, the compliance -pipeline configuration (`.gitlab-ci.yml` file) is run instead of the pipeline configuration of labeled projects. +pipeline configuration (for example, `.compliance-gitlab-ci.yml`) is run instead of the pipeline configuration (for example, `.gitlab-ci.yml`) of labeled +projects. However, the compliance pipeline configuration can reference the `.gitlab-ci.yml` file of the labeled projects so that: @@ -103,8 +104,11 @@ However, the compliance pipeline configuration can reference the `.gitlab-ci.yml - Jobs and variables defined in the compliance pipeline can't be changed by variables in the labeled project's `.gitlab-ci.yml` file. -See [example configuration](#example-configuration) for help configuring a compliance pipeline that runs jobs from -labeled project pipeline configuration. +For more information, see: + +- [Example configuration](#example-configuration) for help configuring a compliance pipeline that runs jobs from + labeled project pipeline configuration. +- The [Create a compliance pipeline](../../tutorials/compliance_pipeline/index.md) tutorial. ### Effect on labeled projects @@ -208,16 +212,47 @@ audit trail: - "# No after scripts." include: # Execute individual project's configuration (if project contains .gitlab-ci.yml) - project: '$CI_PROJECT_PATH' - file: '$CI_CONFIG_PATH' - ref: '$CI_COMMIT_SHA' # Must be defined or MR pipelines always use the use default branch - rules: - - if: $CI_PROJECT_PATH != "my-group/project-1" # Must be the hardcoded path to the project that hosts this configuration. + - project: '$CI_PROJECT_PATH' + file: '$CI_CONFIG_PATH' + ref: '$CI_COMMIT_SHA' # Must be defined or MR pipelines always use the use default branch + rules: + - if: $CI_PROJECT_PATH != "my-group/project-1" # Must be the hardcoded path to the project that hosts this configuration. ``` The `rules` configuration in the `include` definition avoids circular inclusion in case the compliance pipeline must be able to run in the host project itself. You can leave it out if your compliance pipeline only ever runs in labeled projects. +#### Compliance pipelines and custom pipeline configuration hosted externally + +The example above assumes that all projects host their pipeline configuration in the same project. +If any projects use [configuration hosted externally to the project](../../ci/pipelines/settings.md#specify-a-custom-cicd-configuration-file): + +- The `include` section in the example compliance pipeline configuration must be adjusted. + For example, using [`include:rules`](../../ci/yaml/includes.md#use-rules-with-include): + + ```yaml + include: + # If the custom path variables are defined, include the project's external config file. + - 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 + # If any custom path variable is not defined, include the project's internal config file as normal. + - 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 variables](../../ci/variables/index.md) must be added to projects with external + pipeline configuration. In this example: + + - `PROTECTED_PIPELINE_CI_PROJECT_PATH`: The path to the project hosting the configuration file, for example `group/subgroup/project`. + - `PROTECTED_PIPELINE_CI_CONFIG_PATH`: The path to the configuration file in the project, for example `path/to/.gitlab-ci.yml`. + - `PROTECTED_PIPELINE_CI_REF`: The ref to use when retrieving the configuration file, for example `main`. + #### Compliance pipelines in merge requests originating in project forks When a merge request originates in a fork, the branch to be merged usually only exists in the fork. @@ -312,3 +347,53 @@ mutation { } } ``` + +### Compliance jobs are overwritten by target repository + +If you use the `extends` statement in a compliance pipeline configuration, compliance jobs are overwritten by the target repository job. For example, +you could have the following `.compliance-gitlab-ci.yml` configuration: + +```yaml +"compliance job": + extends: + - .compliance_template + stage: build + +.compliance_template: + script: + - echo "take compliance action" +``` + +You could also have the following `.gitlab-ci.yml` configuration: + +```yaml +"compliance job": + stage: test + script: + - echo "overwriting compliance action" +``` + +This configuration results in the target repository pipeline overwriting the compliance pipeline, and you get the following message: +`overwriting compliance action`. + +To avoid overwriting a compliance job, don't use the `extends` keyword in compliance pipeline configuration. For example, +you could have the following `.compliance-gitlab-ci.yml` configuration: + +```yaml +"compliance job": + stage: build + script: + - echo "take compliance action" +``` + +You could also have the following `.gitlab-ci.yml` configuration: + +```yaml +"compliance job": + stage: test + script: + - echo "overwriting compliance action" +``` + +This configuration doesn't overwrite the compliance pipeline and you get the following message: +`take compliance action`. |