Add latest changes from gitlab-org/gitlab@master

9 files changed, 187 insertions, 14 deletions

diff --git a/doc/ci/components/index.md b/doc/ci/components/index.md
index c6659e7b7de..6df258d117b 100644
--- a/doc/ci/components/index.md
+++ b/doc/ci/components/index.md
@@ -178,6 +178,167 @@ For example, for a component repository located at `gitlab-org/dast` on `gitlab.
 - If a tag is named the same as a commit SHA that exists, like `e3262fdd0914fa823210cdb79a8c421e2cef79d8`,
   the commit SHA takes precedence over the tag.
 
+### Best practices
+
+#### Avoid using global keywords
+
+When using [global keywords](../yaml/index.md#global-keywords) all jobs in the
+pipeline are affected. Using these keywords in a component affects all jobs in a
+pipeline, whether they are directly defined in the main `.gitlab-ci.yml` or
+in any included components.
+
+To make the composition of pipelines more deterministic, either:
+
+- Duplicate the default configuration for each job.
+- Use [`extends`](../yaml/index.md#extends) feature within the component.
+
+```yaml
+##
+# BAD
+default:
+  image: ruby:3.0
+
+rspec:
+  script: bundle exec rspec
+```
+
+```yaml
+##
+# GOOD
+rspec:
+  image: ruby:3.0
+  script: bundle exec rspec
+```
+
+#### Replace hard-coded values with inputs
+
+A typical hard-coded value found in CI templates is `stage:` value. Such hard coded values may force the user
+of the component to know and adapt the pipeline to such implementation details.
+
+For example, if `stage: test` is hard-coded for a job in a component, the pipeline using the component must
+define the `test` stage. Additionally, if the user of the component want to customize the stage value it has
+to override the configuration:
+
+```yaml
+##
+# BAD: In order to use different stage name you need to override all the jobs
+# included by the component.
+include:
+  - component: gitlab.com/gitlab-org/ruby-test@1.0
+
+stages: [verify, deploy]
+
+unit-test:
+  stage: verify
+
+integration-test:
+  stage: verify
+```
+
+```yaml
+##
+# BAD: In order to use the component correctly you need to define the stage
+# that is hard-coded in it.
+include:
+  - component: gitlab.com/gitlab-org/ruby-test@1.0
+
+stages: [test, deploy]
+```
+
+To improve this we can use [input parameters](../yaml/includes.md#define-input-parameters-with-specinputs)
+allowing the user of a component to inject values that can be customized:
+
+```yaml
+##
+# GOOD: We don't need to know the implementation details of a component and instead we can
+# rely on the inputs.
+include:
+  - component: gitlab.com/gitlab-org/ruby-test@1.0
+    inputs:
+      stage: verify
+
+stages: [verify, deploy]
+
+##
+# inside the component YAML:
+spec:
+  inputs:
+    stage:
+      default: test
+---
+unit-test:
+  stage: $[[ inputs.stage ]]
+  script: echo unit tests
+
+integration-test:
+  stage: $[[ inputs.stage ]]
+  script: echo integration tests
+```
+
+#### Prefer inputs over variables
+
+If variables are only used for YAML evaluation (for example `rules`) and not by the Runner
+execution, it's advised to use inputs instead.
+Inputs are explicitly defined in the component's contract and they are better validated
+than variables.
+
+For example, if a required input is not passed an error is returned as soon as the component
+is being used. By contrast, if a variable is not defined, it's value is empty.
+
+```yaml
+##
+# BAD: you need to configure an environment variable for a custom value that doesn't need
+# to be used on the Runner 
+unit-test:
+  image: $MY_COMPONENT_X_IMAGE
+  script: echo unit tests
+
+integration-test:
+  image: $MY_COMPONENT_X_IMAGE
+  script: echo integration tests
+
+##
+# Usage:
+include:
+  - component: gitlab.com/gitlab-org/ruby-test@1.0
+
+variables:
+  MY_COMPONENT_X_IMAGE: ruby:3.2
+```
+
+```yaml
+##
+# GOOD: we define a customizable value and accept it as input
+spec:
+  inputs:
+    image:
+      default: ruby:3.0
+---
+unit-test:
+  image: $[[ inputs.image ]]
+  script: echo unit tests
+
+integration-test:
+  image: $[[ inputs.image ]]
+  script: echo integration tests
+
+##
+# Usage:
+include:
+  - component: gitlab.com/gitlab-org/ruby-test@1.0
+    inputs:
+      image: ruby:3.2
+```
+
+#### Use semantic versioning
+
+When tagging and releasing new versions of components we recommend using [semantic versioning](https://semver.org)
+which is the standard for communicating bugfixes, minor and major or breaking changes.
+
+We recommend adopting at least the `MAJOR.MINOR` format.
+
+For example: `2.1`, `1.0.0`, `1.0.0-alpha`, `2.1.3`, `3.0.0-rc.1`.
+
 ## CI/CD Catalog
 
 The CI/CD Catalog is a list of [components repositories](#components-repository),
@@ -201,3 +362,15 @@ To mark a project as a catalog resource:
 
 NOTE:
 This action is not reversible.
+
+## Convert a CI template to component
+
+Any existing CI template, that you share with other projects via `include:` syntax, can be converted to a CI component.
+
+1. Decide whether you want the component to be part of an existing [components repository](#components-repository), 
+   if you want to logically group components together. Create and setup a [components repository](#components-repository) otherwise.
+1. Create a YAML file in the components repository according to the expected [directory structure](#directory-structure).
+1. Copy the content of the template YAML file into the new component YAML file.
+1. Refactor the component YAML to follow the [best practices](#best-practices) for components.
+1. Leverage the `.gitlab-ci.yml` in the components repository to [test changes to the component](#test-a-component).
+1. Tag and [release the component](#release-a-component).
diff --git a/doc/ci/index.md b/doc/ci/index.md
index bc50df620e5..a3106a2475c 100644
--- a/doc/ci/index.md
+++ b/doc/ci/index.md
@@ -104,7 +104,7 @@ GitLab CI/CD features, grouped by DevOps stage, include:
 | [Dynamic Application Security Testing](../user/application_security/dast/index.md)           | Test your application's runtime behavior for vulnerabilities. |
 | [Dependency Scanning](../user/application_security/dependency_scanning/index.md)             | Analyze your dependencies for known vulnerabilities. |
 | [Infrastructure as Code scanning](../user/application_security/iac_scanning/index.md)        | Scan your IaC configuration files for known vulnerabilities. |
-| [License Scanning](../user/compliance/license_scanning_of_cyclonedx_files/index.md)                         | Search your project dependencies for their licenses. |
+| [License Compliance](../user/compliance/license_compliance/index.md)                         | Search your project dependencies for their licenses. |
 | [Secret Detection](../user/application_security/secret_detection/index.md)                   | Search your application's source code for secrets. |
 | [Static Application Security Testing](../user/application_security/sast/index.md)            | Test your application's source code for known vulnerabilities. |
 | [Web API fuzz testing](../user/application_security/api_fuzzing/index.md)                    | Test your application's API behavior by providing randomized input. |
diff --git a/doc/ci/jobs/job_artifacts.md b/doc/ci/jobs/job_artifacts.md
index 770722a0713..3dd43a9760c 100644
--- a/doc/ci/jobs/job_artifacts.md
+++ b/doc/ci/jobs/job_artifacts.md
@@ -61,7 +61,7 @@ pdf:
     expire_in: 1 week
 ```
 
-If `expire_in` is not defined, the [instance-wide setting](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration)
+If `expire_in` is not defined, the [instance-wide setting](../../administration/settings/continuous_integration.md#default-artifacts-expiration)
 is used.
 
 To prevent artifacts from expiring, you can select **Keep** from the job details page.
@@ -351,7 +351,7 @@ Artifacts in old pipelines continue to be kept until a new pipeline runs for the
 Then the artifacts in the earlier pipeline for that ref are allowed to expire too.
 
 You can disable this behavior for all projects on a self-managed instance in the
-[instance's CI/CD settings](../../user/admin_area/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines).
+[instance's CI/CD settings](../../administration/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines).
 
 When **Keep artifacts from most recent successful jobs** is enabled, artifacts are always kept for [blocked](job_control.md#types-of-manual-jobs)
 pipelines. These artifacts expire only after the blocking job is triggered and the pipeline completes.
diff --git a/doc/ci/runners/runners_scope.md b/doc/ci/runners/runners_scope.md
index 8551a783af4..664d255dcac 100644
--- a/doc/ci/runners/runners_scope.md
+++ b/doc/ci/runners/runners_scope.md
@@ -88,7 +88,7 @@ On GitLab.com, [shared runners](index.md) are enabled in all projects by
 default.
 
 On self-managed instances of GitLab, an administrator can
-[enable them for all new projects](../../user/admin_area/settings/continuous_integration.md#enable-shared-runners-for-new-projects).
+[enable them for all new projects](../../administration/settings/continuous_integration.md#enable-shared-runners-for-new-projects).
 
 For existing projects, an administrator must
 [install](https://docs.gitlab.com/runner/install/index.html) and
@@ -434,7 +434,7 @@ You can edit a project runner from any of the projects it's enabled for.
 The modifications, which include unlocking and editing tags and the description,
 affect all projects that use the runner.
 
-An administrator can [enable the runner for multiple projects](../../user/admin_area/settings/continuous_integration.md#enable-a-project-runner-for-multiple-projects).
+An administrator can [enable the runner for multiple projects](../../administration/settings/continuous_integration.md#enable-a-project-runner-for-multiple-projects).
 
 ### Prevent a project runner from being enabled for other projects
 
diff --git a/doc/ci/testing/index.md b/doc/ci/testing/index.md
index 852dcaf206d..a8fb6d688d7 100644
--- a/doc/ci/testing/index.md
+++ b/doc/ci/testing/index.md
@@ -18,7 +18,7 @@ display reports or link to important information directly from [merge requests](
 | [Code Quality](code_quality.md)                                         | Analyze your source code quality using the [Code Climate](https://codeclimate.com/) analyzer and show the Code Climate report right in the merge request widget area. |
 | [Display arbitrary job artifacts](../yaml/index.md#artifactsexpose_as)  | Configure CI pipelines with the `artifacts:expose_as` parameter to directly link to selected [artifacts](../jobs/job_artifacts.md) in merge requests. |
 | [Unit test reports](unit_test_reports.md)                               | Configure your CI jobs to use Unit test reports, and let GitLab display a report on the merge request so that it's easier and faster to identify the failure without having to check the entire job log. |
-| [License Scanning](../../user/compliance/license_scanning_of_cyclonedx_files/index.md) | Manage the licenses of your dependencies. |
+| [License Compliance](../../user/compliance/license_compliance/index.md) | Manage the licenses of your dependencies. |
 | [Metrics Reports](metrics_reports.md)                                   | Display the Metrics Report on the merge request so that it's fast and easier to identify changes to important metrics. |
 | [Test Coverage visualization](test_coverage_visualization.md)           | See test coverage results for merge requests, in the file diff. |
 | [Fail fast testing](fail_fast_testing.md)                               | Run a subset of your RSpec test suite, so failed tests stop the pipeline before the full suite of tests run, saving resources. |
diff --git a/doc/ci/troubleshooting.md b/doc/ci/troubleshooting.md
index e94ccfa6b2b..623589e2cbc 100644
--- a/doc/ci/troubleshooting.md
+++ b/doc/ci/troubleshooting.md
@@ -164,7 +164,7 @@ blocked the pipeline, or allowed the wrong pipeline type.
 
 ### Pipeline with many jobs fails to start
 
-A Pipeline that has more jobs than the instance's defined [CI/CD limits](../user/admin_area/settings/continuous_integration.md#set-cicd-limits)
+A Pipeline that has more jobs than the instance's defined [CI/CD limits](../administration/settings/continuous_integration.md#set-cicd-limits)
 fails to start.
 
 To reduce the number of jobs in your pipeline, you can split your `.gitlab-ci.yml`
diff --git a/doc/ci/yaml/artifacts_reports.md b/doc/ci/yaml/artifacts_reports.md
index 4882532f98f..37cb7efdf94 100644
--- a/doc/ci/yaml/artifacts_reports.md
+++ b/doc/ci/yaml/artifacts_reports.md
@@ -249,12 +249,12 @@ concatenate them into a single file. Use either:
 
 > Introduced in GitLab 12.8.
 
-The License Compliance report collects [Licenses](../../user/compliance/license_scanning_of_cyclonedx_files/index.md). The License
+The License Compliance report collects [Licenses](../../user/compliance/license_compliance/index.md). The License
 Compliance report uploads to GitLab as an artifact.
 
 GitLab can display the results of one or more reports in:
 
-- The merge request [license compliance widget](../../user/compliance/license_scanning_of_cyclonedx_files/index.md).
+- The merge request [license compliance widget](../../user/compliance/license_compliance/index.md).
 - The [license list](../../user/compliance/license_list.md).
 
 ## `artifacts:reports:load_performance` **(PREMIUM)**
diff --git a/doc/ci/yaml/includes.md b/doc/ci/yaml/includes.md
index 503b9f164dd..3b6419dbff2 100644
--- a/doc/ci/yaml/includes.md
+++ b/doc/ci/yaml/includes.md
@@ -630,4 +630,4 @@ limit is reached. You can remove one included file at a time to try to narrow do
 which configuration file is the source of the loop or excessive included files.
 
 In [GitLab 16.0 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/207270) self-managed users can
-change the [maximum includes](../../user/admin_area/settings/continuous_integration.md#maximum-includes) value.
+change the [maximum includes](../../administration/settings/continuous_integration.md#maximum-includes) value.
diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md
index c261c7d05d1..f946a7fd7a9 100644
--- a/doc/ci/yaml/index.md
+++ b/doc/ci/yaml/index.md
@@ -163,7 +163,7 @@ The time limit to resolve all files is 30 seconds.
     pipeline run, the new pipeline uses the changed configuration.
 - You can have up to 150 includes per pipeline by default, including [nested](includes.md#use-nested-includes). Additionally:
   - In [GitLab 16.0 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/207270) self-managed users can
-    change the [maximum includes](../../user/admin_area/settings/continuous_integration.md#maximum-includes) value.
+    change the [maximum includes](../../administration/settings/continuous_integration.md#maximum-includes) value.
   - In [GitLab 15.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/367150) you can have up to 150 includes.
     In nested includes, the same file can be included multiple times, but duplicated includes
     count towards the limit.
@@ -353,7 +353,7 @@ The order of the items in `stages` defines the execution order for jobs:
 
 If a pipeline contains only jobs in the `.pre` or `.post` stages, it does not run.
 There must be at least one other job in a different stage. `.pre` and `.post` stages
-can be used in [required pipeline configuration](../../user/admin_area/settings/continuous_integration.md#required-pipeline-configuration)
+can be used in [required pipeline configuration](../../administration/settings/continuous_integration.md#required-pipeline-configuration)
 to define compliance jobs that must run before or after project pipeline jobs.
 
 **Keyword type**: Global keyword.
@@ -843,7 +843,7 @@ they expire and are deleted. The `expire_in` setting does not affect:
 
 - Artifacts from the latest job, unless keeping the latest job artifacts is disabled
   [at the project level](../jobs/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs).
-  or [instance-wide](../../user/admin_area/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines).
+  or [instance-wide](../../administration/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines).
 
 After their expiry, artifacts are deleted hourly by default (using a cron job), and are not
 accessible anymore.
@@ -875,7 +875,7 @@ job:
 **Additional details**:
 
 - The expiration time period begins when the artifact is uploaded and stored on GitLab.
-  If the expiry time is not defined, it defaults to the [instance wide setting](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration).
+  If the expiry time is not defined, it defaults to the [instance wide setting](../../administration/settings/continuous_integration.md#default-artifacts-expiration).
 - To override the expiration date and protect artifacts from being automatically deleted:
   - Select **Keep** on the job page.
   - [In GitLab 13.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/22761), set the value of