Add latest changes from gitlab-org/gitlab@master

20 files changed, 875 insertions, 1 deletions

diff --git a/doc/ci/pipelines/img/collapsible_log_v12_6.png b/doc/ci/pipelines/img/collapsible_log_v12_6.png
new file mode 100644
index 00000000000..24b2c83f7c1
--- /dev/null
+++ b/doc/ci/pipelines/img/collapsible_log_v12_6.png
diff --git a/doc/ci/pipelines/img/job_failure_reason.png b/doc/ci/pipelines/img/job_failure_reason.png
new file mode 100644
index 00000000000..d44b8e6d1be
--- /dev/null
+++ b/doc/ci/pipelines/img/job_failure_reason.png
diff --git a/doc/ci/pipelines/img/manual_job_variables.png b/doc/ci/pipelines/img/manual_job_variables.png
new file mode 100644
index 00000000000..a5ed351fdcd
--- /dev/null
+++ b/doc/ci/pipelines/img/manual_job_variables.png
diff --git a/doc/ci/pipelines/img/pipeline-delete.png b/doc/ci/pipelines/img/pipeline-delete.png
new file mode 100644
index 00000000000..d9dba1f455d
--- /dev/null
+++ b/doc/ci/pipelines/img/pipeline-delete.png
diff --git a/doc/ci/pipelines/img/pipeline_incremental_rollout.png b/doc/ci/pipelines/img/pipeline_incremental_rollout.png
new file mode 100644
index 00000000000..b3498e9a5a5
--- /dev/null
+++ b/doc/ci/pipelines/img/pipeline_incremental_rollout.png
diff --git a/doc/ci/pipelines/img/pipelines.png b/doc/ci/pipelines/img/pipelines.png
new file mode 100644
index 00000000000..a604fcb2587
--- /dev/null
+++ b/doc/ci/pipelines/img/pipelines.png
diff --git a/doc/ci/pipelines/img/pipelines_duration_chart.png b/doc/ci/pipelines/img/pipelines_duration_chart.png
new file mode 100644
index 00000000000..0be7539ba0a
--- /dev/null
+++ b/doc/ci/pipelines/img/pipelines_duration_chart.png
diff --git a/doc/ci/pipelines/img/pipelines_grouped.png b/doc/ci/pipelines/img/pipelines_grouped.png
new file mode 100644
index 00000000000..82814754747
--- /dev/null
+++ b/doc/ci/pipelines/img/pipelines_grouped.png
diff --git a/doc/ci/pipelines/img/pipelines_index.png b/doc/ci/pipelines/img/pipelines_index.png
new file mode 100644
index 00000000000..e168e7e23df
--- /dev/null
+++ b/doc/ci/pipelines/img/pipelines_index.png
diff --git a/doc/ci/pipelines/img/pipelines_mini_graph.png b/doc/ci/pipelines/img/pipelines_mini_graph.png
new file mode 100644
index 00000000000..8656b02f60d
--- /dev/null
+++ b/doc/ci/pipelines/img/pipelines_mini_graph.png
diff --git a/doc/ci/pipelines/img/pipelines_mini_graph_simple.png b/doc/ci/pipelines/img/pipelines_mini_graph_simple.png
new file mode 100644
index 00000000000..d00a8313088
--- /dev/null
+++ b/doc/ci/pipelines/img/pipelines_mini_graph_simple.png
diff --git a/doc/ci/pipelines/img/pipelines_mini_graph_sorting.png b/doc/ci/pipelines/img/pipelines_mini_graph_sorting.png
new file mode 100644
index 00000000000..3a4e5453360
--- /dev/null
+++ b/doc/ci/pipelines/img/pipelines_mini_graph_sorting.png
diff --git a/doc/ci/pipelines/img/pipelines_settings_badges.png b/doc/ci/pipelines/img/pipelines_settings_badges.png
new file mode 100644
index 00000000000..3bdc6374c15
--- /dev/null
+++ b/doc/ci/pipelines/img/pipelines_settings_badges.png
diff --git a/doc/ci/pipelines/img/pipelines_settings_test_coverage.png b/doc/ci/pipelines/img/pipelines_settings_test_coverage.png
new file mode 100644
index 00000000000..13ed69be810
--- /dev/null
+++ b/doc/ci/pipelines/img/pipelines_settings_test_coverage.png
diff --git a/doc/ci/pipelines/img/pipelines_success_chart.png b/doc/ci/pipelines/img/pipelines_success_chart.png
new file mode 100644
index 00000000000..10602b75eeb
--- /dev/null
+++ b/doc/ci/pipelines/img/pipelines_success_chart.png
diff --git a/doc/ci/pipelines/img/pipelines_test_coverage_build.png b/doc/ci/pipelines/img/pipelines_test_coverage_build.png
new file mode 100644
index 00000000000..7eaba1a256f
--- /dev/null
+++ b/doc/ci/pipelines/img/pipelines_test_coverage_build.png
diff --git a/doc/ci/pipelines/img/pipelines_test_coverage_mr_widget.png b/doc/ci/pipelines/img/pipelines_test_coverage_mr_widget.png
new file mode 100644
index 00000000000..fbcd612f3f2
--- /dev/null
+++ b/doc/ci/pipelines/img/pipelines_test_coverage_mr_widget.png
diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md
new file mode 100644
index 00000000000..a823793a995
--- /dev/null
+++ b/doc/ci/pipelines/index.md
@@ -0,0 +1,566 @@
+---
+type: reference
+---
+
+# Creating and using CI/CD pipelines
+
+> Introduced in GitLab 8.8.
+
+NOTE: **Tip:**
+Watch our
+["Mastering continuous software development"](https://about.gitlab.com/webcast/mastering-ci-cd/)
+webcast to see a comprehensive demo of GitLab CI/CD pipeline.
+
+## Introduction
+
+Pipelines are the top-level component of continuous integration, delivery, and deployment.
+
+Pipelines comprise:
+
+- Jobs that define what to run. For example, code compilation or test runs.
+- Stages that define when and how to run. For example, that tests run only after code compilation.
+
+Multiple jobs in the same stage are executed by [Runners](../runners/README.md) in parallel, if there are enough concurrent [Runners](../runners/README.md).
+
+If all the jobs in a stage:
+
+- Succeed, the pipeline moves on to the next stage.
+- Fail, the next stage is not (usually) executed and the pipeline ends early.
+
+NOTE: **Note:**
+If you have a [mirrored repository that GitLab pulls from](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository-starter),
+you may need to enable pipeline triggering in your project's
+**Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**.
+
+### Simple pipeline example
+
+As an example, imagine a pipeline consisting of four stages, executed in the following order:
+
+- `build`, with a job called `compile`.
+- `test`, with two jobs called `test` and `test2`.
+- `staging`, with a job called `deploy-to-stage`.
+- `production`, with a job called `deploy-to-prod`.
+
+## Visualizing pipelines
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5742) in GitLab 8.11.
+
+Pipelines can be complex structures with many sequential and parallel jobs.
+
+To make it easier to understand the flow of a pipeline, GitLab has pipeline graphs for viewing pipelines
+and their statuses.
+
+Pipeline graphs can be displayed in two different ways, depending on the page you
+access the graph from.
+
+NOTE: **Note:**
+GitLab capitalizes the stages' names when shown in the pipeline graphs (below).
+
+### Regular pipeline graphs
+
+Regular pipeline graphs show the names of the jobs of each stage. Regular pipeline graphs can
+be found when you are on a [single pipeline page](#accessing-pipelines). For example:
+
+![Pipelines example](img/pipelines.png)
+
+### Pipeline mini graphs
+
+Pipeline mini graphs take less space and can tell you at a
+quick glance if all jobs passed or something failed. The pipeline mini graph can
+be found when you navigate to:
+
+- The pipelines index page.
+- A single commit page.
+- A merge request page.
+
+Pipeline mini graphs allow you to see all related jobs for a single commit and the net result
+of each stage of your pipeline. This allows you to quickly see what failed and
+fix it.
+
+Stages in pipeline mini graphs are collapsible. Hover your mouse over them and click to expand their jobs.
+
+| Mini graph                                                   | Mini graph expanded                                            |
+|:-------------------------------------------------------------|:---------------------------------------------------------------|
+| ![Pipelines mini graph](img/pipelines_mini_graph_simple.png) | ![Pipelines mini graph extended](img/pipelines_mini_graph.png) |
+
+### Job ordering in pipeline graphs
+
+Job ordering depends on the type of pipeline graph. For [regular pipeline graphs](#regular-pipeline-graphs), jobs are sorted by name.
+
+For [pipeline mini graphs](#pipeline-mini-graphs) ([introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9760)
+in GitLab 9.0), jobs are sorted by severity and then by name.
+
+The order of severity is:
+
+- failed
+- warning
+- pending
+- running
+- manual
+- scheduled
+- canceled
+- success
+- skipped
+- created
+
+For example:
+
+![Pipeline mini graph sorting](img/pipelines_mini_graph_sorting.png)
+
+### Expanding and collapsing job log sections
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/14664) in GitLab
+> 12.0.
+
+Job logs are divided into sections that can be collapsed or expanded. Each section will display
+the duration.
+
+In the following example:
+
+- Two sections are collapsed and can be expanded.
+- Three sections are expanded and can be collapsed.
+
+![Collapsible sections](img/collapsible_log_v12_6.png)
+
+#### Custom collapsible sections
+
+You can create collapsible sections in job logs by manually outputting special codes
+that GitLab will use to determine what sections to collapse:
+
+- Section start marker: `section_start:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K` + `TEXT_OF_SECTION_HEADER`
+- Section end marker: `section_end:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K`
+
+You must add these codes to the script section of the CI configuration. For example,
+using `echo`:
+
+```yaml
+job1:
+  script:
+    - echo -e "section_start:`date +%s`:my_first_section\r\e[0KHeader of the 1st collapsible section"
+    - echo 'this line should be hidden when collapsed'
+    - echo -e "section_end:`date +%s`:my_first_section\r\e[0K"
+```
+
+In the example above:
+
+- `date +%s`: The Unix timestamp (for example `1560896352`).
+- `my_first_section`: The name given to the section.
+- `\r\e[0K`: Prevents the section markers from displaying in the rendered (colored)
+  job log, but they are displayed in the raw job log. To see them, in the top right
+  of the job log, click **{doc-text}** (**Show complete raw**).
+  - `\r`: carriage return.
+  - `\e[0K`: clear line ANSI escape code.
+
+Sample raw job log:
+
+```plaintext
+section_start:1560896352:my_first_section\r\e[0KHeader of the 1st collapsible section
+this line should be hidden when collapsed
+section_end:1560896353:my_first_section\r\e[0K
+```
+
+### Pipeline success and duration charts
+
+> - Introduced in GitLab 3.1.1 as Commit Stats, and later renamed to Pipeline Charts.
+> - [Renamed](https://gitlab.com/gitlab-org/gitlab/issues/38318) to CI / CD Analytics in GitLab 12.8.
+
+GitLab tracks the history of your pipeline successes and failures, as well as how long each pipeline ran. To view this information, go to **Analytics > CI / CD Analytics**.
+
+View successful pipelines:
+
+![Successful pipelines](img/pipelines_success_chart.png)
+
+View pipeline duration history:
+
+![Pipeline duration](img/pipelines_duration_chart.png)
+
+## Pipeline quotas
+
+Each user has a personal pipeline quota that tracks the usage of shared runners in all personal projects.
+Each group has a [usage quota](../../subscriptions/index.md#ci-pipeline-minutes) that tracks the usage of shared runners for all projects created within the group.
+
+When a pipeline is triggered, regardless of who triggered it, the pipeline quota for the project owner's [namespace](../../user/group/index.md#namespaces) is used. In this case, the namespace can be the user or group that owns the project.
+
+### How pipeline duration is calculated
+
+Total running time for a given pipeline excludes retries and pending
+(queued) time.
+
+Each job is represented as a `Period`, which consists of:
+
+- `Period#first` (when the job started).
+- `Period#last` (when the job finished).
+
+A simple example is:
+
+- A (1, 3)
+- B (2, 4)
+- C (6, 7)
+
+In the example:
+
+- A begins at 1 and ends at 3.
+- B begins at 2 and ends at 4.
+- C begins at 6 and ends at 7.
+
+Visually, it can be viewed as:
+
+```text
+0  1  2  3  4  5  6  7
+   AAAAAAA
+      BBBBBBB
+                  CCCC
+```
+
+The union of A, B, and C is (1, 4) and (6, 7). Therefore, the total running time is:
+
+```text
+(4 - 1) + (7 - 6) => 4
+```
+
+## Configuring pipelines
+
+Pipelines, and their component jobs and stages, are defined in the [`.gitlab-ci.yml`](../yaml/README.md) file for each project.
+
+In particular:
+
+- Jobs are the [basic configuration](../yaml/README.md#introduction) component.
+- Stages are defined using the [`stages`](../yaml/README.md#stages) keyword.
+
+For all available configuration options, see the [GitLab CI/CD Pipeline Configuration Reference](../yaml/README.md).
+
+### Settings and schedules
+
+In addition to configuring jobs through `.gitlab-ci.yml`, additional configuration options are available
+through the GitLab UI:
+
+- Pipeline settings for each project. For more information, see [Pipeline settings](settings.md).
+- Schedules for pipelines. For more information, see [Pipeline schedules](schedules.md).
+
+### Grouping jobs
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6242) in GitLab 8.12.
+
+If you have many similar jobs, your [pipeline graph](#visualizing-pipelines) becomes long and hard
+to read.
+
+For that reason, similar jobs can automatically be grouped together.
+If the job names are formatted in certain ways, they will be collapsed into
+a single group in regular pipeline graphs (not the mini graphs).
+
+You'll know when a pipeline has grouped jobs if you don't see the retry or
+cancel button inside them. Hovering over them will show the number of grouped
+jobs. Click to expand them.
+
+![Grouped pipelines](img/pipelines_grouped.png)
+
+#### Configuring grouping
+
+In the pipeline [configuration file](../yaml/README.md), job names must include two numbers separated with one of
+the following (you can even use them interchangeably):
+
+- A space.
+- A slash (`/`).
+- A colon (`:`).
+
+NOTE: **Note:**
+More specifically, it uses [this](https://gitlab.com/gitlab-org/gitlab/blob/2f3dc314f42dbd79813e6251792853bc231e69dd/app/models/commit_status.rb#L99) regular expression: `\d+[\s:\/\\]+\d+\s*`.
+
+#### How grouping works
+
+The jobs will be ordered by comparing those two numbers from left to right. You
+usually want the first to be the index and the second the total.
+
+For example, the following jobs will be grouped under a job named `test`:
+
+- `test 0 3`
+- `test 1 3`
+- `test 2 3`
+
+The following jobs will be grouped under a job named `test ruby`:
+
+- `test 1:2 ruby`
+- `test 2:2 ruby`
+
+The following jobs will be grouped under a job named `test ruby` as well:
+
+- `1/3 test ruby`
+- `2/3 test ruby`
+- `3/3 test ruby`
+
+### Pipelines for merge requests
+
+GitLab supports configuring pipelines that run only for merge requests. For more information, see
+[Pipelines for merge requests](../merge_request_pipelines/index.md).
+
+### Badges
+
+Pipeline status and test coverage report badges are available and configurable for each project.
+
+For information on adding pipeline badges to projects, see [Pipeline badges](settings.md#pipeline-badges).
+
+## Multi-project pipelines
+
+Pipelines for different projects can be combined together into [Multi-project pipelines](../multi_project_pipelines.md).
+
+[Multi-project pipeline graphs](../multi_project_pipelines.md#multi-project-pipeline-visualization-premium) help
+you visualize the entire pipeline, including all cross-project inter-dependencies. **(PREMIUM)**
+
+## Parent-child pipelines
+
+Complex pipelines can be broken down into one parent pipeline that can trigger
+multiple child sub-pipelines, which all run in the same project and with the same SHA.
+
+For more information, see [Parent-Child pipelines](../parent_child_pipelines.md).
+
+## Working with pipelines
+
+In general, pipelines are executed automatically and require no intervention once created.
+
+However, there are instances where you'll need to interact with pipelines. These are documented below.
+
+### Manually executing pipelines
+
+Pipelines can be manually executed, with predefined or manually-specified [variables](../variables/README.md).
+
+You might do this if the results of a pipeline (for example, a code build) is required outside the normal
+operation of the pipeline.
+
+To execute a pipeline manually:
+
+1. Navigate to your project's **CI/CD > Pipelines**.
+1. Click on the **Run Pipeline** button.
+1. On the **Run Pipeline** page:
+    1. Select the branch to run the pipeline for in the **Create for** field.
+    1. Enter any [environment variables](../variables/README.md) required for the pipeline run.
+    1. Click the **Create pipeline** button.
+
+The pipeline will execute the jobs as configured.
+
+#### Using a query string
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/24146) in GitLab 12.5.
+
+Variables on the **Run Pipeline** page can be pre-populated by passing variable keys and values
+in a query string appended to the `pipelines/new` URL. The format is:
+
+```plaintext
+.../pipelines/new?ref=<branch>&var[<variable_key>]=<value>&file_var[<file_key>]=<value>
+```
+
+The following parameters are supported:
+
+- `ref`: specify the branch to populate the **Run for** field with.
+- `var`: specify a `Variable` variable.
+- `file_var`: specify a `File` variable.
+
+For each `var` or `file_var`, a key and value are required.
+
+For example, the query string
+`.../pipelines/new?ref=my_branch&var[foo]=bar&file_var[file_foo]=file_bar` will pre-populate the
+**Run Pipeline** page as follows:
+
+- **Run for** field: `my_branch`.
+- **Variables** section:
+  - Variable:
+    - Key: `foo`
+    - Value: `bar`
+  - File:
+    - Key: `file_foo`
+    - Value: `file_bar`
+
+### Accessing pipelines
+
+You can find the current and historical pipeline runs under your project's
+**CI/CD > Pipelines** page. You can also access pipelines for a merge request by navigating
+to its **Pipelines** tab.
+
+![Pipelines index page](img/pipelines_index.png)
+
+Clicking on a pipeline will bring you to the **Pipeline Details** page and show
+the jobs that were run for that pipeline. From here you can cancel a running pipeline,
+retry jobs on a failed pipeline, or [delete a pipeline](#deleting-a-single-pipeline).
+
+### Accessing individual jobs
+
+When you access a pipeline, you can see the related jobs for that pipeline.
+
+Clicking on an individual job will show you its job log, and allow you to:
+
+- Cancel the job.
+- Retry the job.
+- Erase the job log.
+
+### Seeing the failure reason for jobs
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17782) in GitLab 10.7.
+
+When a pipeline fails or is allowed to fail, there are several places where you
+can quickly check the reason it failed:
+
+- In the pipeline graph, on the pipeline detail view.
+- In the pipeline widgets, in the merge requests and commit pages.
+- In the job views, in the global and detailed views of a job.
+
+In each place, if you hover over the failed job you can see the reason it failed.
+
+![Pipeline detail](img/job_failure_reason.png)
+
+From [GitLab 10.8](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17814),
+you can also see the reason it failed on the Job detail page.
+
+### Manual actions from pipeline graphs
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7931) in GitLab 8.15.
+
+Manual actions, configured using the [`when:manual`](../yaml/README.md#whenmanual) parameter,
+allow you to require manual interaction before moving forward in the pipeline.
+
+You can do this straight from the pipeline graph. Just click on the play button
+to execute that particular job.
+
+For example, your pipeline start automatically, but require manual action to
+[deploy to production](../environments.md#configuring-manual-deployments). In the example below, the `production`
+stage has a job with a manual action.
+
+![Pipelines example](img/pipelines.png)
+
+### Specifying variables when running manual jobs
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30485) in GitLab 12.2.
+
+When running manual jobs you can supply additional job specific variables.
+
+You can do this from the job page of the manual job you want to run with
+additional variables.
+
+This is useful when you want to alter the execution of a job by using
+environment variables.
+
+![Manual job variables](img/manual_job_variables.png)
+
+### Delay a job in a pipeline graph
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/21767) in GitLab 11.4.
+
+When you do not want to run a job immediately, you can use the [`when:delayed`](../yaml/README.md#whendelayed) parameter to
+delay a job's execution for a certain period.
+
+This is especially useful for timed incremental rollout where new code is rolled out gradually.
+
+For example, if you start rolling out new code and:
+
+- Users do not experience trouble, GitLab can automatically complete the deployment from 0% to 100%.
+- Users experience trouble with the new code, you can stop the timed incremental rollout by canceling the pipeline
+  and [rolling](../environments.md#retrying-and-rolling-back) back to the last stable version.
+
+![Pipelines example](img/pipeline_incremental_rollout.png)
+
+### Using the API
+
+GitLab provides API endpoints to:
+
+- Perform basic functions. For more information, see [Pipelines API](../../api/pipelines.md).
+- Maintain pipeline schedules. For more information, see [Pipeline schedules API](../../api/pipeline_schedules.md).
+- Trigger pipeline runs. For more information, see:
+  - [Triggering pipelines through the API](../triggers/README.md).
+  - [Pipeline triggers API](../../api/pipeline_triggers.md).
+
+### Start multiple manual actions in a stage
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27188) in GitLab 11.11.
+
+Multiple manual actions in a single stage can be started at the same time using the "Play all manual" button.
+Once the user clicks this button, each individual manual action will be triggered and refreshed
+to an updated status.
+
+This functionality is only available:
+
+- For users with at least Developer access.
+- If the the stage contains [manual actions](#manual-actions-from-pipeline-graphs).
+
+### Deleting a single pipeline
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/24851) in GitLab 12.7.
+
+Users with [owner permissions](../../user/permissions.md) in a project can delete a pipeline
+by clicking on the pipeline in the **CI/CD > Pipelines** to get to the **Pipeline Details**
+page, then using the **Delete** button.
+
+![Pipeline Delete Button](img/pipeline-delete.png)
+
+CAUTION: **Warning:**
+Deleting a pipeline will expire all pipeline caches, and delete all related objects,
+such as builds, logs, artifacts, and triggers. **This action cannot be undone.**
+
+## Most Recent Pipeline
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/50499) in GitLab 12.3.
+
+There's a link to the latest pipeline for the last commit of a given branch at `/project/pipelines/[branch]/latest`. Also, `/project/pipelines/latest` will redirect you to the latest pipeline for the last commit on the project's default branch.
+
+## Security on protected branches
+
+A strict security model is enforced when pipelines are executed on
+[protected branches](../../user/project/protected_branches.md).
+
+The following actions are allowed on protected branches only if the user is
+[allowed to merge or push](../../user/project/protected_branches.md#using-the-allowed-to-merge-and-allowed-to-push-settings)
+on that specific branch:
+
+- Run manual pipelines (using the [Web UI](#manually-executing-pipelines) or pipelines API).
+- Run scheduled pipelines.
+- Run pipelines using triggers.
+- Trigger manual actions on existing pipelines.
+- Retry or cancel existing jobs (using the Web UI or pipelines API).
+
+**Variables** marked as **protected** are accessible only to jobs that
+run on protected branches, preventing untrusted users getting unintended access to
+sensitive information like deployment credentials and tokens.
+
+**Runners** marked as **protected** can run jobs only on protected
+branches, avoiding untrusted code to be executed on the protected runner and
+preserving deployment keys and other credentials from being unintentionally
+accessed. In order to ensure that jobs intended to be executed on protected
+runners will not use regular runners, they must be tagged accordingly.
+
+## Persistent pipeline refs
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17043) in GitLab 12.4.
+
+Previously, you'd have encountered unexpected pipeline failures when you force-pushed
+a branch to its remote repository. To illustrate the problem, suppose you've had the current workflow:
+
+1. A user creates a feature branch named `example` and pushes it to a remote repository.
+1. A new pipeline starts running on the `example` branch.
+1. A user rebases the `example` branch on the latest `master` branch and force-pushes it to its remote repository.
+1. A new pipeline starts running on the `example` branch again, however,
+   the previous pipeline (2) fails because of `fatal: reference is not a tree:` error.
+
+This is because the previous pipeline cannot find a checkout-SHA (which associated with the pipeline record)
+from the `example` branch that the commit history has already been overwritten by the force-push.
+Similarly, [Pipelines for merged results](../merge_request_pipelines/pipelines_for_merged_results/index.md)
+might have failed intermittently due to [the same reason](../merge_request_pipelines/pipelines_for_merged_results/index.md#intermittently-pipelines-fail-by-fatal-reference-is-not-a-tree-error).
+
+As of GitLab 12.4, we've improved this behavior by persisting pipeline refs exclusively.
+To illustrate its life cycle:
+
+1. A pipeline is created on a feature branch named `example`.
+1. A persistent pipeline ref is created at `refs/pipelines/<pipeline-id>`,
+   which retains the checkout-SHA of the associated pipeline record.
+   This persistent ref stays intact during the pipeline execution,
+   even if the commit history of the `example` branch has been overwritten by force-push.
+1. GitLab Runner fetches the persistent pipeline ref and gets source code from the checkout-SHA.
+1. When the pipeline finished, its persistent ref is cleaned up in a background process.
+
+NOTE: **NOTE**: At this moment, this feature is on by default and can be manually disabled
+by disabling `depend_on_persistent_pipeline_ref` feature flag. If you're interested in
+manually disabling this behavior, please ask the administrator
+to execute the following commands in rails console.
+
+```shell
+> sudo gitlab-rails console                                        # Login to Rails console of GitLab instance.
+> project = Project.find_by_full_path('namespace/project-name')    # Get the project instance.
+> Feature.disable(:depend_on_persistent_pipeline_ref, project)     # Disable the feature flag for specific project
+> Feature.disable(:depend_on_persistent_pipeline_ref)              # Disable the feature flag system-wide
+```
diff --git a/doc/ci/pipelines/schedules.md b/doc/ci/pipelines/schedules.md
index ea98638ae53..92cf1985d86 100644
--- a/doc/ci/pipelines/schedules.md
+++ b/doc/ci/pipelines/schedules.md
@@ -12,7 +12,7 @@ Cron notation is parsed by [Fugit](https://github.com/floraison/fugit).
 
 Pipelines are normally run based on certain conditions being met. For example, when a branch is pushed to repository.
 
-Pipeline schedules can be used to also run [pipelines](../pipelines.md) at specific intervals. For example:
+Pipeline schedules can be used to also run [pipelines](index.md) at specific intervals. For example:
 
 - Every month on the 22nd for a certain branch.
 - Once every day.
diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md
new file mode 100644
index 00000000000..53a529493d2
--- /dev/null
+++ b/doc/ci/pipelines/settings.md
@@ -0,0 +1,308 @@
+---
+type: reference, howto
+---
+
+# Pipelines settings
+
+To reach the pipelines settings navigate to your project's
+**Settings > CI/CD**.
+
+The following settings can be configured per project.
+
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
+For an overview, watch the video [GitLab CI Pipeline, Artifacts, and Environments](https://www.youtube.com/watch?v=PCKDICEe10s).
+Watch also [GitLab CI pipeline tutorial for beginners](https://www.youtube.com/watch?v=Jav4vbUrqII).
+
+## Git strategy
+
+With Git strategy, you can choose the default way your repository is fetched
+from GitLab in a job.
+
+There are two options. Using:
+
+- `git clone`, which is slower since it clones the repository from scratch
+  for every job, ensuring that the local working copy is always pristine.
+- `git fetch`, which is faster as it re-uses the local working copy (falling
+  back to clone if it doesn't exist).
+
+The default Git strategy can be overridden by the [GIT_STRATEGY variable](../yaml/README.md#git-strategy)
+in `.gitlab-ci.yml`.
+
+## Git shallow clone
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/28919) in GitLab 12.0.
+
+NOTE: **Note**:
+As of GitLab 12.0, newly created projects will automatically have a default
+`git depth` value of `50`.
+
+It is possible to limit the number of changes that GitLab CI/CD will fetch when cloning
+a repository. Setting a limit to `git depth` can speed up Pipelines execution. Maximum
+allowed value is `1000`.
+
+To disable shallow clone and make GitLab CI/CD fetch all branches and tags each time,
+keep the value empty or set to `0`.
+
+This value can also be [overridden by `GIT_DEPTH`](../large_repositories/index.md#shallow-cloning) variable in `.gitlab-ci.yml` file.
+
+## Timeout
+
+Timeout defines the maximum amount of time in minutes that a job is able run.
+This is configurable under your project's **Settings > CI/CD > General pipelines settings**.
+The default value is 60 minutes. Decrease the time limit if you want to impose
+a hard limit on your jobs' running time or increase it otherwise. In any case,
+if the job surpasses the threshold, it is marked as failed.
+
+### Timeout overriding on Runner level
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17221) in GitLab 10.7.
+
+Project defined timeout (either specific timeout set by user or the default
+60 minutes timeout) may be [overridden on Runner level](../runners/README.md#setting-maximum-job-timeout-for-a-runner).
+
+## Maximum artifacts size **(CORE ONLY)**
+
+For information about setting a maximum artifact size for a project, see
+[Maximum artifacts size](../../user/admin_area/settings/continuous_integration.md#maximum-artifacts-size-core-only).
+
+## Custom CI configuration path
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12509) in GitLab 9.4.
+> - [Support for external `.gitlab-ci.yml` locations](https://gitlab.com/gitlab-org/gitlab/issues/14376) introduced in GitLab 12.6.
+
+By default we look for the `.gitlab-ci.yml` file in the project's root
+directory. If needed, you can specify an alternate path and file name, including locations outside the project.
+
+To customize the path:
+
+1. Go to the project's **Settings > CI / CD**.
+1. Expand the **General pipelines** section.
+1. Provide a value in the **Custom CI configuration path** field.
+1. Click **Save changes**.
+
+If the CI configuration is stored within the repository in a non-default
+location, the path must be relative to the root directory. Examples of valid
+paths and file names include:
+
+- `.gitlab-ci.yml` (default)
+- `.my-custom-file.yml`
+- `my/path/.gitlab-ci.yml`
+- `my/path/.my-custom-file.yml`
+
+If the CI configuration will be hosted on an external site, the URL link must end with `.yml`:
+
+- `http://example.com/generate/ci/config.yml`
+
+If the CI configuration will be hosted in a different project within GitLab, the path must be relative
+to the root directory in the other project, with the group and project name added to the end:
+
+- `.gitlab-ci.yml@mygroup/another-project`
+- `my/path/.my-custom-file.yml@mygroup/another-project`
+
+Hosting the configuration file in a separate project allows stricter control of the
+configuration file. For example:
+
+- Create a public project to host the configuration file.
+- Give write permissions on the project only to users who are allowed to edit the file.
+
+Other users and projects will be able to access the configuration file without being
+able to edit it.
+
+## Test coverage parsing
+
+If you use test coverage in your code, GitLab can capture its output in the
+job log using a regular expression. In the pipelines settings, search for the
+"Test coverage parsing" section.
+
+![Pipelines settings test coverage](img/pipelines_settings_test_coverage.png)
+
+Leave blank if you want to disable it or enter a ruby regular expression. You
+can use <https://rubular.com> to test your regex.
+
+If the pipeline succeeds, the coverage is shown in the merge request widget and
+in the jobs table.
+
+![MR widget coverage](img/pipelines_test_coverage_mr_widget.png)
+
+![Build status coverage](img/pipelines_test_coverage_build.png)
+
+A few examples of known coverage tools for a variety of languages can be found
+in the pipelines settings page.
+
+### Removing color codes
+
+Some test coverage tools output with ANSI color codes that won't be
+parsed correctly by the regular expression and will cause coverage
+parsing to fail.
+
+If your coverage tool doesn't provide an option to disable color
+codes in the output, you can pipe the output of the coverage tool through a
+small one line script that will strip the color codes off.
+
+For example:
+
+```shell
+lein cloverage | perl -pe 's/\e\[?.*?[\@-~]//g'
+```
+
+## Visibility of pipelines
+
+Pipeline visibility is determined by:
+
+- Your current [user access level](../../user/permissions.md).
+- The **Public pipelines** project setting under your project's **Settings > CI/CD > General pipelines**.
+
+NOTE: **Note:**
+If the project visibility is set to **Private**, the [**Public pipelines** setting will have no effect](../enable_or_disable_ci.md#per-project-user-setting).
+
+This also determines the visibility of these related features:
+
+- Job output logs
+- Job artifacts
+- The [pipeline security dashboard](../../user/application_security/security_dashboard/index.md#pipeline-security-dashboard) **(ULTIMATE)**
+
+If **Public pipelines** is enabled (default):
+
+- For **public** projects, anyone can view the pipelines and related features.
+- For **internal** projects, any logged in user can view the pipelines
+  and related features.
+- For **private** projects, any project member (guest or higher) can view the pipelines
+  and related features.
+
+If **Public pipelines** is disabled:
+
+- For **public** projects, anyone can view the pipelines, but only members
+  (reporter or higher) can access the related features.
+- For **internal** projects, any logged in user can view the pipelines.
+  However, only members (reporter or higher) can access the job related features.
+- For **private** projects, only project members (reporter or higher)
+  can view the pipelines or access the related features.
+
+## Auto-cancel pending pipelines
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9362) in GitLab 9.1.
+
+If you want all pending non-HEAD pipelines on branches to auto-cancel each time
+a new pipeline is created, such as after a Git push or manually from the UI,
+you can enable this in the project settings:
+
+1. Go to **{settings}** **Settings > CI / CD**.
+1. Expand **General Pipelines**.
+1. Check the **Auto-cancel redundant, pending pipelines** checkbox.
+1. Click **Save changes**.
+
+## Skip older, pending deployment jobs
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/25276) in GitLab 12.9.
+
+Your project may have multiple concurrent deployment jobs that are
+scheduled to run within the same time frame.
+
+This can lead to a situation where an older deployment job runs after a
+newer one, which may not be what you want.
+
+To avoid this scenario:
+
+1. Go to **{settings}** **Settings > CI / CD**.
+1. Expand **General pipelines**.
+1. Check the **Skip older, pending deployment jobs** checkbox.
+1. Click **Save changes**.
+
+The pending deployment jobs will be skipped.
+
+## Pipeline Badges
+
+In the pipelines settings page you can find pipeline status and test coverage
+badges for your project. The latest successful pipeline will be used to read
+the pipeline status and test coverage values.
+
+Visit the pipelines settings page in your project to see the exact link to
+your badges, as well as ways to embed the badge image in your HTML or Markdown
+pages.
+
+![Pipelines badges](img/pipelines_settings_badges.png)
+
+### Pipeline status badge
+
+Depending on the status of your job, a badge can have the following values:
+
+- pending
+- running
+- passed
+- failed
+- skipped
+- canceled
+- unknown
+
+You can access a pipeline status badge image using the following link:
+
+```text
+https://example.gitlab.com/<namespace>/<project>/badges/<branch>/pipeline.svg
+```
+
+### Test coverage report badge
+
+GitLab makes it possible to define the regular expression for [coverage report](#test-coverage-parsing),
+that each job log will be matched against. This means that each job in the
+pipeline can have the test coverage percentage value defined.
+
+The test coverage badge can be accessed using following link:
+
+```text
+https://example.gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg
+```
+
+If you would like to get the coverage report from a specific job, you can add
+the `job=coverage_job_name` parameter to the URL. For example, the following
+Markdown code will embed the test coverage report badge of the `coverage` job
+into your `README.md`:
+
+```markdown
+![coverage](https://gitlab.com/gitlab-org/gitlab-foss/badges/master/coverage.svg?job=coverage)
+```
+
+### Badge styles
+
+Pipeline badges can be rendered in different styles by adding the `style=style_name` parameter to the URL. Currently two styles are available:
+
+#### Flat (default)
+
+```text
+https://example.gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat
+```
+
+![Badge flat style](https://gitlab.com/gitlab-org/gitlab-foss/badges/master/coverage.svg?job=coverage&style=flat)
+
+#### Flat square
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/30120) in GitLab 11.8.
+
+```text
+https://example.gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat-square
+```
+
+![Badge flat square style](https://gitlab.com/gitlab-org/gitlab-foss/badges/master/coverage.svg?job=coverage&style=flat-square)
+
+## Environment Variables
+
+[Environment variables](../variables/README.md#gitlab-cicd-environment-variables) can be set in an environment to be available to a runner.
+
+## Deploy Keys
+
+With Deploy Keys, GitLab allows you to import SSH public keys. You can then have
+read only or read/write access to your project from the machines the keys were generated from.
+
+SSH keys added to your project settings will be used for continuous integration,
+staging, or production servers.
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->