Merge branch 'docs-pipeline-efficiency-updates' into 'master'

Add crosslinks to the pipeline efficiency doc

Closes #250273

See merge request gitlab-org/gitlab!42549

doc/ci/README.md

@@ -86,30 +86,31 @@ GitLab CI/CD and [shared runners](runners/README.md#shared-runners) are enabled
 
 GitLab CI/CD uses a number of concepts to describe and run your build and deploy.
 
-| Concept | Description  |
-|:--------------|:-------------|
-| [Pipelines](pipelines/index.md) | Structure your CI/CD process through pipelines. |
-| [Environment variables](variables/README.md) | Reuse values based on a variable/value key pair. |
-| [Environments](environments/index.md) | Deploy your application to different environments (e.g., staging, production). |
-| [Job artifacts](pipelines/job_artifacts.md) | Output, use, and reuse job artifacts. |
-| [Cache dependencies](caching/index.md) | Cache your dependencies for a faster execution. |
-| [GitLab Runner](https://docs.gitlab.com/runner/) | Configure your own runners to execute your scripts. |
+| Concept                                                 | Description                                                                    |
+|:--------------------------------------------------------|:-------------------------------------------------------------------------------|
+| [Pipelines](pipelines/index.md)                         | Structure your CI/CD process through pipelines.                                |
+| [Environment variables](variables/README.md)            | Reuse values based on a variable/value key pair.                               |
+| [Environments](environments/index.md)                   | Deploy your application to different environments (e.g., staging, production). |
+| [Job artifacts](pipelines/job_artifacts.md)             | Output, use, and reuse job artifacts.                                          |
+| [Cache dependencies](caching/index.md)                  | Cache your dependencies for a faster execution.                                |
+| [GitLab Runner](https://docs.gitlab.com/runner/)        | Configure your own runners to execute your scripts.                            |
+| [Pipeline efficiency](pipelines/pipeline_efficiency.md) | Configure your pipelines to run quickly and effienctly.                        |
 
 ## Configuration
 
 GitLab CI/CD supports numerous configuration options:
 
-| Configuration | Description  |
-|:--------------|:-------------|
-| [Schedule pipelines](pipelines/schedules.md) | Schedule pipelines to run as often as you need. |
-| [Custom path for `.gitlab-ci.yml`](pipelines/settings.md#custom-ci-configuration-path) | Define a custom path for the CI/CD configuration file. |
-| [Git submodules for CI/CD](git_submodules.md) | Configure jobs for using Git submodules.|
-| [SSH keys for CI/CD](ssh_keys/README.md) | Using SSH keys in your CI pipelines. |
-| [Pipeline triggers](triggers/README.md) | Trigger pipelines through the API. |
-| [Pipelines for Merge Requests](merge_request_pipelines/index.md) | Design a pipeline structure for running a pipeline in merge requests. |
-| [Integrate with Kubernetes clusters](../user/project/clusters/index.md) | Connect your project to Google Kubernetes Engine (GKE) or an existing Kubernetes cluster. |
-| [Optimize GitLab and GitLab Runner for large repositories](large_repositories/index.md) | Recommended strategies for handling large repositories. |
-| [`.gitlab-ci.yml` full reference](yaml/README.md) | All the attributes you can use with GitLab CI/CD. |
+| Configuration                                                                           | Description                                                                               |
+|:----------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------|
+| [Schedule pipelines](pipelines/schedules.md)                                            | Schedule pipelines to run as often as you need.                                           |
+| [Custom path for `.gitlab-ci.yml`](pipelines/settings.md#custom-ci-configuration-path)  | Define a custom path for the CI/CD configuration file.                                    |
+| [Git submodules for CI/CD](git_submodules.md)                                           | Configure jobs for using Git submodules.                                                  |
+| [SSH keys for CI/CD](ssh_keys/README.md)                                                | Using SSH keys in your CI pipelines.                                                      |
+| [Pipeline triggers](triggers/README.md)                                                 | Trigger pipelines through the API.                                                        |
+| [Pipelines for Merge Requests](merge_request_pipelines/index.md)                        | Design a pipeline structure for running a pipeline in merge requests.                     |
+| [Integrate with Kubernetes clusters](../user/project/clusters/index.md)                 | Connect your project to Google Kubernetes Engine (GKE) or an existing Kubernetes cluster. |
+| [Optimize GitLab and GitLab Runner for large repositories](large_repositories/index.md) | Recommended strategies for handling large repositories.                                   |
+| [`.gitlab-ci.yml` full reference](yaml/README.md)                                       | All the attributes you can use with GitLab CI/CD.                                         |
 
 Note that certain operations can only be performed according to the
 [user](../user/permissions.md#gitlab-cicd-permissions) and [job](../user/permissions.md#job-permissions) permissions.
@@ -191,41 +192,25 @@ been necessary. These are:
 
 #### 13.0
 
-- [Remove Backported
-  `os.Expand`](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4915)
-- [Remove Fedora 29 package
-  support](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/16158)
-- [Remove macOS 32-bit
-  support](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/25466)
-- [Removed `debug/jobs/list?v=1`
-  endpoint](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6361)
-- [Remove support for array of strings when defining services for Docker
-  executor](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4922)
-- [Remove `--docker-services` flag on register
-  command](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6404)
-- [Remove legacy build directory
-  caching](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4180)
-- [Remove `FF_USE_LEGACY_VOLUMES_MOUNTING_ORDER` feature
-  flag](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6581)
-- [Remove support for Windows Server
-  1803](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6553)
+- [Remove Backported `os.Expand`](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4915).
+- [Remove Fedora 29 package support](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/16158).
+- [Remove macOS 32-bit support](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/25466).
+- [Removed `debug/jobs/list?v=1` endpoint](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6361).
+- [Remove support for array of strings when defining services for Docker executor](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4922).
+- [Remove `--docker-services` flag on register command](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6404).
+- [Remove legacy build directory caching](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4180).
+- [Remove `FF_USE_LEGACY_VOLUMES_MOUNTING_ORDER` feature flag](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6581).
+- [Remove support for Windows Server 1803](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6553).
 
 #### 12.0
 
-- [Use refspec to clone/fetch Git
-  repository](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4069).
-- [Old cache
-  configuration](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4070).
-- [Old metrics server
-  configuration](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4072).
-- [Remove
-  `FF_K8S_USE_ENTRYPOINT_OVER_COMMAND`](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4073).
-- [Remove Linux distributions that reach
-  EOL](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1130).
-- [Update command line API for helper
-  images](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4013).
-- [Remove old `git clean`
-  flow](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4175).
+- [Use refspec to clone/fetch Git repository](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4069).
+- [Old cache configuration](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4070).
+- [Old metrics server configuration](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4072).
+- [Remove `FF_K8S_USE_ENTRYPOINT_OVER_COMMAND`](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4073).
+- [Remove Linux distributions that reach EOL](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1130).
+- [Update command line API for helper images](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4013).
+- [Remove old `git clean` flow](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4175).
 
 #### 11.0
 

doc/ci/introduction/index.md

@@ -237,3 +237,6 @@ existing one) for any application.
 
 For a deep view of GitLab's CI/CD configuration options, check the
 [`.gitlab-ci.yml` full reference](../yaml/README.md).
+
+For help making your pipelines faster and more efficient, see the
+[pipeline efficiency documentation](../pipelines/pipeline_efficiency.md).

doc/ci/migration/jenkins.md

@@ -26,6 +26,8 @@ that were able to quickly complete this migration:
    1. Migrate the deployment jobs using [cloud deployment templates](../cloud_deployment/index.md), adding [environments](../environments/index.md), and [deploy boards](../..//user/project/deploy_boards.md).
    1. Work to unwrap any jobs still running with the use of the Jenkins wrapper.
 1. Take stock of any common CI/CD job definitions then create and share [templates](#templates) for them.
+1. Check the [pipeline efficiency documentation](../pipelines/pipeline_efficiency.md)
+   to learn how to make your GitLab CI/CD pipelines faster and more efficient.
 
 For an example of how to convert a Jenkins pipeline into a GitLab CI/CD pipeline,
 or how to use Auto DevOps to test your code automatically, watch the
@@ -354,3 +356,8 @@ our very powerful [`only/except` rules system](../yaml/README.md#onlyexcept-basi
 my_job:
   only: [branches]
 ```
+
+## Additional resources
+
+For help making your pipelines faster and more efficient, see the
+[pipeline efficiency documentation](../pipelines/pipeline_efficiency.md).

doc/ci/pipelines/pipeline_efficiency.md

@@ -28,17 +28,17 @@ The easiest indicators to check for inefficient pipelines are the runtimes of th
 stages, and the total runtime of the pipeline itself. The total pipeline duration is
 heavily influenced by the:
 
-- Total number of stages and jobs
-- Dependencies between jobs
+- Total number of stages and jobs.
+- Dependencies between jobs.
 - The ["critical path"](#directed-acyclic-graphs-dag-visualization), which represents
-  the minimum and maximum pipeline duration
+  the minimum and maximum pipeline duration.
 
 Additional points to pay attention relate to [GitLab Runners](../runners/README.md):
 
-- Availability of the runners and the resources they are provisioned with
-- Build dependencies and their installation time
-- [Container image size](#docker-images)
-- Network latency and slow connections
+- Availability of the runners and the resources they are provisioned with.
+- Build dependencies and their installation time.
+- [Container image size](#docker-images).
+- Network latency and slow connections.
 
 Pipelines frequently failing unnecessarily also causes slowdowns in the development
 lifecycle. You should look for problematic patterns with failed jobs:
@@ -54,9 +54,9 @@ lifecycle. You should look for problematic patterns with failed jobs:
 Analyze the performance of your pipeline to find ways to improve efficiency. Analysis
 can help identify possible blockers in the CI/CD infrastructure. This includes analyzing:
 
-- Job workloads
-- Bottlenecks in the execution times
-- The overall pipeline architecture
+- Job workloads.
+- Bottlenecks in the execution times.
+- The overall pipeline architecture.
 
 It's important to understand and document the pipeline workflows, and discuss possible
 actions and changes. Refactoring pipelines may need careful interaction between teams
@@ -212,7 +212,8 @@ that download and run faster.
 
 Try to use custom Docker images with the software pre-installed. It's usually much
 faster to download a larger pre-configured image than to use a common image and install
-software on it each time.
+software on it each time. Docker's [Best practices for writing Dockerfiles](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/)
+has more information about building efficient Docker images.
 
 Methods to reduce Docker image size:
 

doc/ci/quick_start/README.md

@@ -216,7 +216,10 @@ you expected.
 You are also able to view the status of any commit in the various pages in
 GitLab, such as **Commits** and **Merge requests**.
 
-## Examples
+## Additional resources
 
 Visit the [examples README](../examples/README.md) to see a list of examples using GitLab
 CI with various languages.
+
+For help making your new pipelines faster and more efficient, see the
+[pipeline efficiency documentation](../pipelines/pipeline_efficiency.md).