Inject custom pipeline execution policy stages

What does this MR do and why?

This feature allows custom stages defined in pipeline execution policies to be injected.

How does it work

The stages can be specified in the policy as per usual. Custom stages can be placed in the middle of the pipeline by defining stages before and after. For example, policy-test can be placed between test and deploy in the project pipeline:

stages: [test, policy-test, deploy]

policy-test-job:
  stage: policy-test
  script:
    - sleep 1

It is possible to specify any possible stages that projects might be using. Only stages with jobs will be present in the resulting pipeline. For example:

stages: [build, compile, test, check, policy-test, deploy, publish]

policy-test-job:
  stage: policy-test
  script:
    - sleep 1

In this case, policy-test will be placed after build, compile, test, check and before deploy, publish. If project was using stages: [compile, check, publish], the resulting pipeline would contain stages: [compile, check, policy-test, publish].

If policy stages only specify the custom stage, this will be placed at the end of the pipeline, just before .pipeline-policy-post (if used):

stages: [policy-test]

policy-test-job:
  stage: policy-test
  script:
    - sleep 1

With default project stages, this results in [build, test, deploy, policy-test].

When used in a project without .gitlab-ci.yml, the behavior is the same as injecting into default stages.

Behavior with other policies

• It is additive to other policies and the project
• When used together with override_project_ci policies, it merges into the override stages.

New strategy

Users can specify a new pipeline_config_strategy called inject_policy_ci which enables custom stages from the policy pipelines to be injected. It is made as a separate strategy so that users can opt-in and avoid breaking changes. inject_ci will be deprecated and customers will be encouraged to use the new strategy.

Possible pipeline errors

Depending on the policy stages configuration, the pipeline could fail with this strategy - in case the stages are defined as cyclic. Example:

Policy stages: [test, deploy] Project stages: [build, deploy, test]

In this example, deploy depends on test in the policy, but test depends on deploy in the project. This configuration results in a "cyclic dependencies" error:

References

Please include cross links to any resources that are relevant to this MR. This will give reviewers and future readers helpful context to give an efficient review of the changes introduced.

• Previous proposal with more complex configuration: Enforce required stages in pipeline execution p... (!170413 - closed)

MR acceptance checklist

Please evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Screenshots or screen recordings

Only injected PEP	Mix of injected and overriding PEP
CleanShot_2025-01-20_at_16.48.48	CleanShot_2025-01-20_at_17.13.04

How to set up and validate locally

1. Enable feature flag custom_pipeline_execution_policy_stages
2. Create a project
3. In the project, create a .gitlab-ci.yml:

   # .gitlab-ci.yml
   
   stages:
     - build
     - test
     - lint-test
     - deploy
   
   build-project:
     stage: build
     script:
       - sleep 1
   
   test-project:
     stage: test
     script:
       - sleep 1
   
   lint-project:
     stage: lint-test
     script:
       - sleep 1
   
   deploy-project:
     stage: deploy
     script:
       - sleep 1

4. Create a PEP CI configuration:

   # policy-ci.yml
   
   stages: [test, policy-test, deploy]
   
   policy-test-job:
     stage: policy-test
     script:
       - sleep 1

5. Create a policy, referencing the PEP CI configuration

   # policy.yml
   
   ---
   pipeline_execution_policy:
     - name: Inject stages
       description: ''
       enabled: true
       pipeline_config_strategy: inject_policy_ci
       content:
         include:
           - project: gitlab-org/pipeline-execution-policies/compliance-project
             file: policy-ci.yml
     

Related to #475152 (closed)