Merge branch 'docs-for-mr-pipelines' into 'master'

Documentation for "`only/except: merge-requests` for merge request pipelines"

Closes #54511 and #15310

See merge request gitlab-org/gitlab-ce!23397

7 files changed, 201 insertions, 76 deletions

diff --git a/doc/ci/README.md b/doc/ci/README.md
index dba1f38abe2..4e066a0df97 100644
--- a/doc/ci/README.md
+++ b/doc/ci/README.md
@@ -71,6 +71,7 @@ learn how to leverage its potential even more.
 - [Caching dependencies](caching/index.md)
 - [Git submodules](git_submodules.md) - How to run your CI jobs when Git
   submodules are involved
+- [Pipelines for merge requests](merge_request_pipelines/index.md)
 - [Use SSH keys in your build environment](ssh_keys/README.md)
 - [Trigger pipelines through the GitLab API](triggers/README.md)
 - [Trigger pipelines on a schedule](../user/project/pipelines/schedules.md)
diff --git a/doc/ci/merge_request_pipelines/img/merge_request.png b/doc/ci/merge_request_pipelines/img/merge_request.png
new file mode 100644
index 00000000000..1fe2eec2008
--- /dev/null
+++ b/doc/ci/merge_request_pipelines/img/merge_request.png
diff --git a/doc/ci/merge_request_pipelines/img/pipeline_detail.png b/doc/ci/merge_request_pipelines/img/pipeline_detail.png
new file mode 100644
index 00000000000..def1781dd75
--- /dev/null
+++ b/doc/ci/merge_request_pipelines/img/pipeline_detail.png
diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md
new file mode 100644
index 00000000000..706e83abf44
--- /dev/null
+++ b/doc/ci/merge_request_pipelines/index.md
@@ -0,0 +1,84 @@
+# Pipelines for merge requests
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/15310) in GitLab 11.6
+
+Usually, when a developer creates a new merge request, a pipeline runs on the
+new change and checks if it's qualified to be merged into a target branch. This
+pipeline should contain only necessary jobs for checking the new changes.
+For example, unit tests, lint checks, and Review Apps are often used in this cycle.
+
+With pipelines for merge requests, you can design a specific pipeline structure
+for merge requests. All you need to do is just adding `only: [merge_requests]` to
+the jobs that you want it to run for only merge requests.
+Every time, when developers create or update merge requests, a pipeline runs on
+their new commits at every push to GitLab.
+
+NOTE: **Note**:
+If you use both this feature and the [Merge When Pipeline Succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md)
+feature, pipelines for merge requests take precendence over the other regular pipelines.
+
+For example, consider a GitLab CI/CD configuration in .gitlab-ci.yml as follows:
+
+```yaml
+build:
+  stage: build
+  script: ./build
+  only:
+  - branches
+  - tags
+  - merge_requests
+
+test:
+  stage: test
+  script: ./test
+  only:
+  - merge_requests
+
+deploy:
+  stage: deploy
+  script: ./deploy
+```
+
+After a developer updated code in a merge request with whatever methods (e.g. `git push`),
+GitLab detects that the code is updated and create a new pipeline for the merge request.
+The pipeline fetches the latest code from the source branch and run tests against it.
+In this example, the pipeline contains only `build` and `test` jobs.
+Since `deploy` job does not have the `only: [merge_requests]` rule,
+deployment jobs will not happen in the merge request.
+
+Consider this pipeline list viewed from the **Pipelines** tab in a merge request:
+
+![Merge request page](img/merge_request.png)
+
+Note that pipelines tagged as **merge request** indicate that they were triggered
+when a merge request was created or updated.
+
+The same tag is shown on the pipeline's details:
+
+![Pipeline's details](img/pipeline_detail.png)
+
+## Important notes about merge requests from forked projects
+
+Note that the current behavior is subject to change. In the usual contribution
+flow, external contributors follow the following steps:
+
+1. Fork a parent project.
+1. Create a merge request from the forked project that targets the `master` branch
+in the parent project.
+1. A pipeline runs on the merge request.
+1. A mainatiner from the parent project checks the pipeline result, and merge
+into a target branch if the latest pipeline has passed.
+
+Currently, those pipelines are created in a **forked** project, not in the
+parent project. This means you cannot completely trust the pipeline result,
+because, technically, external contributors can disguise their pipeline results
+by tweaking their GitLab Runner in the forked project.
+
+There are multiple reasons about why GitLab doesn't allow those pipelines to be
+created in the parent project, but one of the biggest reasons is security concern.
+External users could steal secret variables from the parent project by modifying
+.gitlab-ci.yml, which could be some sort of credentials. This should not happen.
+
+We're discussing a secure solution of running pipelines for merge requests
+that submitted from forked projects,
+see [the issue about the permission extension](https://gitlab.com/gitlab-org/gitlab-ce/issues/23902).
diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md
index fd81a67dca0..87799be8ab4 100644
--- a/doc/ci/variables/README.md
+++ b/doc/ci/variables/README.md
@@ -40,73 +40,84 @@ Starting with GitLab 9.0, we have deprecated some variables. Read the
 strongly advised to use the new variables as we will remove the old ones in
 future GitLab releases.**
 
-| Variable                        | GitLab | Runner | Description |
-|-------------------------------- |--------|--------|-------------|
-| **ARTIFACT_DOWNLOAD_ATTEMPTS**  | 8.15   | 1.9    | Number of attempts to download artifacts running a job |
-| **CI**                          | all    | 0.4    | Mark that job is executed in CI environment |
-| **CI_COMMIT_REF_NAME**          | 9.0    | all    | The branch or tag name for which project is built |
-| **CI_COMMIT_REF_SLUG**          | 9.0    | all    | `$CI_COMMIT_REF_NAME` lowercased, shortened to 63 bytes, and with everything except `0-9` and `a-z` replaced with `-`. No leading / trailing `-`. Use in URLs, host names and domain names. |
-| **CI_COMMIT_SHA**               | 9.0    | all    | The commit revision for which project is built |
-| **CI_COMMIT_BEFORE_SHA**        | 11.2   | all    | The previous latest commit present on a branch before a push request. |
-| **CI_COMMIT_TAG**               | 9.0    | 0.5    | The commit tag name. Present only when building tags. |
-| **CI_COMMIT_MESSAGE**           | 10.8   | all    | The full commit message. |
-| **CI_COMMIT_TITLE**             | 10.8   | all    | The title of the commit - the full first line of the message |
-| **CI_COMMIT_DESCRIPTION**       | 10.8   | all    | The description of the commit: the message without first line, if the title is shorter than 100 characters; full message in other case. |
-| **CI_CONFIG_PATH**              | 9.4    | 0.5    | The path to CI config file. Defaults to `.gitlab-ci.yml` |
-| **CI_DEBUG_TRACE**              | all    | 1.7    | Whether [debug tracing](#debug-tracing) is enabled |
-| **CI_DEPLOY_USER**              | 10.8   | all    | Authentication username of the [GitLab Deploy Token][gitlab-deploy-token], only present if the Project has one related.|
-| **CI_DEPLOY_PASSWORD**          | 10.8   | all    | Authentication password of the [GitLab Deploy Token][gitlab-deploy-token], only present if the Project has one related.|
-| **CI_DISPOSABLE_ENVIRONMENT**   | all    | 10.1   | Marks that the job is executed in a disposable environment (something that is created only for this job and disposed of/destroyed after the execution - all executors except `shell` and `ssh`). If the environment is disposable, it is set to true, otherwise it is not defined at all. |
-| **CI_ENVIRONMENT_NAME**         | 8.15   | all    | The name of the environment for this job |
-| **CI_ENVIRONMENT_SLUG**         | 8.15   | all    | A simplified version of the environment name, suitable for inclusion in DNS, URLs, Kubernetes labels, etc. |
-| **CI_ENVIRONMENT_URL**          | 9.3    | all    | The URL of the environment for this job |
-| **CI_JOB_ID**                   | 9.0    | all    | The unique id of the current job that GitLab CI uses internally |
-| **CI_JOB_MANUAL**               | 8.12   | all    | The flag to indicate that job was manually started |
-| **CI_JOB_NAME**                 | 9.0    | 0.5    | The name of the job as defined in `.gitlab-ci.yml` |
-| **CI_JOB_STAGE**                | 9.0    | 0.5    | The name of the stage as defined in `.gitlab-ci.yml` |
-| **CI_JOB_TOKEN**                | 9.0    | 1.2    | Token used for authenticating with the [GitLab Container Registry][registry] and downloading [dependent repositories][dependent-repositories] |
-| **CI_NODE_INDEX**               | 11.5   | all    | Index of the job in the job set. If the job is not parallelized, this variable is not set. |
-| **CI_NODE_TOTAL**               | 11.5   | all    | Total number of instances of this job running in parallel. If the job is not parallelized, this variable is set to `1`. |
-| **CI_JOB_URL**                  | 11.1   | 0.5    | Job details URL |
-| **CI_REPOSITORY_URL**           | 9.0    | all    | The URL to clone the Git repository |
-| **CI_RUNNER_DESCRIPTION**       | 8.10   | 0.5    | The description of the runner as saved in GitLab |
-| **CI_RUNNER_ID**                | 8.10   | 0.5    | The unique id of runner being used |
-| **CI_RUNNER_TAGS**              | 8.10   | 0.5    | The defined runner tags |
-| **CI_RUNNER_VERSION**           | all    | 10.6   | GitLab Runner version that is executing the current job |
-| **CI_RUNNER_REVISION**          | all    | 10.6   | GitLab Runner revision that is executing the current job |
-| **CI_RUNNER_EXECUTABLE_ARCH**   | all    | 10.6   | The OS/architecture of the GitLab Runner executable (note that this is not necessarily the same as the environment of the executor) |
-| **CI_PIPELINE_ID**              | 8.10   | 0.5    | The unique id of the current pipeline that GitLab CI uses internally |
-| **CI_PIPELINE_IID**             | 11.0   | all    | The unique id of the current pipeline scoped to project |
-| **CI_PIPELINE_TRIGGERED**       | all    | all    | The flag to indicate that job was [triggered] |
-| **CI_PIPELINE_SOURCE**          | 10.0   | all    | Indicates how the pipeline was triggered. Possible options are: `push`, `web`, `trigger`, `schedule`, `api`, and `pipeline`. For pipelines created before GitLab 9.5, this will show as `unknown` |
-| **CI_PROJECT_DIR**              | all    | all    | The full path where the repository is cloned and where the job is run |
-| **CI_PROJECT_ID**               | all    | all    | The unique id of the current project that GitLab CI uses internally |
-| **CI_PROJECT_NAME**             | 8.10   | 0.5    | The project name that is currently being built (actually it is project folder name) |
-| **CI_PROJECT_NAMESPACE**        | 8.10   | 0.5    | The project namespace (username or groupname) that is currently being built |
-| **CI_PROJECT_PATH**             | 8.10   | 0.5    | The namespace with project name |
-| **CI_PROJECT_PATH_SLUG**        | 9.3    | all    | `$CI_PROJECT_PATH` lowercased and with everything except `0-9` and `a-z` replaced with `-`. Use in URLs and domain names. |
-| **CI_PIPELINE_URL**             | 11.1   | 0.5    | Pipeline details URL |
-| **CI_PROJECT_URL**              | 8.10   | 0.5    | The HTTP address to access project |
-| **CI_PROJECT_VISIBILITY**       | 10.3   | all    | The project visibility (internal, private, public) |
-| **CI_REGISTRY**                 | 8.10   | 0.5    | If the Container Registry is enabled it returns the address of GitLab's Container Registry |
-| **CI_REGISTRY_IMAGE**           | 8.10   | 0.5    | If the Container Registry is enabled for the project it returns the address of the registry tied to the specific project |
-| **CI_REGISTRY_PASSWORD**        | 9.0    | all    | The password to use to push containers to the GitLab Container Registry |
-| **CI_REGISTRY_USER**            | 9.0    | all    | The username to use to push containers to the GitLab Container Registry |
-| **CI_SERVER**                   | all    | all    | Mark that job is executed in CI environment |
-| **CI_SERVER_NAME**              | all    | all    | The name of CI server that is used to coordinate jobs |
-| **CI_SERVER_REVISION**          | all    | all    | GitLab revision that is used to schedule jobs |
-| **CI_SERVER_VERSION**           | all    | all    | GitLab version that is used to schedule jobs |
-| **CI_SERVER_VERSION_MAJOR**     | 11.4   | all    | GitLab version major component |
-| **CI_SERVER_VERSION_MINOR**     | 11.4   | all    | GitLab version minor component |
-| **CI_SERVER_VERSION_PATCH**     | 11.4   | all    | GitLab version patch component |
-| **CI_SHARED_ENVIRONMENT**       | all    | 10.1   | Marks that the job is executed in a shared environment (something that is persisted across CI invocations like `shell` or `ssh` executor). If the environment is shared, it is set to true, otherwise it is not defined at all. |
-| **GET_SOURCES_ATTEMPTS**        | 8.15   | 1.9    | Number of attempts to fetch sources running a job |
-| **GITLAB_CI**                   | all    | all    | Mark that job is executed in GitLab CI environment |
-| **GITLAB_USER_EMAIL**           | 8.12   | all    | The email of the user who started the job |
-| **GITLAB_USER_ID**              | 8.12   | all    | The id of the user who started the job |
-| **GITLAB_USER_LOGIN**           | 10.0   | all    | The login username of the user who started the job |
-| **GITLAB_USER_NAME**            | 10.0   | all    | The real name of the user who started the job |
-| **RESTORE_CACHE_ATTEMPTS**      | 8.15   | 1.9    | Number of attempts to restore the cache running a job |
+| Variable                                  | GitLab | Runner | Description |
+|-------------------------------------------|--------|--------|-------------|
+| **ARTIFACT_DOWNLOAD_ATTEMPTS**            | 8.15   | 1.9    | Number of attempts to download artifacts running a job |
+| **CI**                                    | all    | 0.4    | Mark that job is executed in CI environment |
+| **CI_COMMIT_REF_NAME**                    | 9.0    | all    | The branch or tag name for which project is built |
+| **CI_COMMIT_REF_SLUG**                    | 9.0    | all    | `$CI_COMMIT_REF_NAME` lowercased, shortened to 63 bytes, and with everything except `0-9` and `a-z` replaced with `-`. No leading / trailing `-`. Use in URLs, host names and domain names. |
+| **CI_COMMIT_SHA**                         | 9.0    | all    | The commit revision for which project is built |
+| **CI_COMMIT_BEFORE_SHA**                  | 11.2   | all    | The previous latest commit present on a branch before a push request. |
+| **CI_COMMIT_TAG**                         | 9.0    | 0.5    | The commit tag name. Present only when building tags. |
+| **CI_COMMIT_MESSAGE**                     | 10.8   | all    | The full commit message. |
+| **CI_COMMIT_TITLE**                       | 10.8   | all    | The title of the commit - the full first line of the message |
+| **CI_COMMIT_DESCRIPTION**                 | 10.8   | all    | The description of the commit: the message without first line, if the title is shorter than 100 characters; full message in other case. |
+| **CI_CONFIG_PATH**                        | 9.4    | 0.5    | The path to CI config file. Defaults to `.gitlab-ci.yml` |
+| **CI_DEBUG_TRACE**                        | all    | 1.7    | Whether [debug tracing](#debug-tracing) is enabled |
+| **CI_DEPLOY_USER**                        | 10.8   | all    | Authentication username of the [GitLab Deploy Token][gitlab-deploy-token], only present if the Project has one related.|
+| **CI_DEPLOY_PASSWORD**                    | 10.8   | all    | Authentication password of the [GitLab Deploy Token][gitlab-deploy-token], only present if the Project has one related.|
+| **CI_DISPOSABLE_ENVIRONMENT**             | all    | 10.1   | Marks that the job is executed in a disposable environment (something that is created only for this job and disposed of/destroyed after the execution - all executors except `shell` and `ssh`). If the environment is disposable, it is set to true, otherwise it is not defined at all. |
+| **CI_ENVIRONMENT_NAME**                   | 8.15   | all    | The name of the environment for this job |
+| **CI_ENVIRONMENT_SLUG**                   | 8.15   | all    | A simplified version of the environment name, suitable for inclusion in DNS, URLs, Kubernetes labels, etc. |
+| **CI_ENVIRONMENT_URL**                    | 9.3    | all    | The URL of the environment for this job |
+| **CI_JOB_ID**                             | 9.0    | all    | The unique id of the current job that GitLab CI uses internally |
+| **CI_JOB_MANUAL**                         | 8.12   | all    | The flag to indicate that job was manually started |
+| **CI_JOB_NAME**                           | 9.0    | 0.5    | The name of the job as defined in `.gitlab-ci.yml` |
+| **CI_JOB_STAGE**                          | 9.0    | 0.5    | The name of the stage as defined in `.gitlab-ci.yml` |
+| **CI_JOB_TOKEN**                          | 9.0    | 1.2    | Token used for authenticating with the [GitLab Container Registry][registry] and downloading [dependent repositories][dependent-repositories] |
+| **CI_MERGE_REQUEST_ID**                   | 11.6   | all    | The ID of the merge request if it's [pipelines for merge requests](../merge_request_pipelines/index.md) |
+| **CI_MERGE_REQUEST_IID**                  | 11.6   | all    | The IID of the merge request if it's [pipelines for merge requests](../merge_request_pipelines/index.md) |
+| **CI_MERGE_REQUEST_REF_PATH**             | 11.6   | all    | The ref path of the merge request if it's [pipelines for merge requests](../merge_request_pipelines/index.md). (e.g. `refs/merge-requests/1/head`) |
+| **CI_MERGE_REQUEST_PROJECT_ID**           | 11.6   | all    | The ID of the project of the merge request if it's [pipelines for merge requests](../merge_request_pipelines/index.md) |
+| **CI_MERGE_REQUEST_PROJECT_PATH**         | 11.6   | all    | The path of the project of the merge request if it's [pipelines for merge requests](../merge_request_pipelines/index.md) (e.g. `namespace/awesome-project`) |
+| **CI_MERGE_REQUEST_PROJECT_URL**          | 11.6   | all    | The URL of the project of the merge request if it's [pipelines for merge requests](../merge_request_pipelines/index.md) (e.g. `http://192.168.10.15:3000/namespace/awesome-project`) |
+| **CI_MERGE_REQUEST_TARGET_BRANCH_NAME**   | 11.6   | all    | The target branch name of the merge request if it's [pipelines for merge requests](../merge_request_pipelines/index.md) |
+| **CI_MERGE_REQUEST_SOURCE_PROJECT_ID**    | 11.6   | all    | The ID of the source project of the merge request if it's [pipelines for merge requests](../merge_request_pipelines/index.md) |
+| **CI_MERGE_REQUEST_SOURCE_PROJECT_PATH**  | 11.6   | all    | The path of the source project of the merge request if it's [pipelines for merge requests](../merge_request_pipelines/index.md) |
+| **CI_MERGE_REQUEST_SOURCE_PROJECT_URL**   | 11.6   | all    | The URL of the source project of the merge request if it's [pipelines for merge requests](../merge_request_pipelines/index.md) |
+| **CI_MERGE_REQUEST_SOURCE_BRANCH_NAME**   | 11.6   | all    | The source branch name of the merge request if it's [pipelines for merge requests](../merge_request_pipelines/index.md) |
+| **CI_NODE_INDEX**                         | 11.5   | all    | Index of the job in the job set. If the job is not parallelized, this variable is not set. |
+| **CI_NODE_TOTAL**                         | 11.5   | all    | Total number of instances of this job running in parallel. If the job is not parallelized, this variable is set to `1`. |
+| **CI_JOB_URL**                            | 11.1   | 0.5    | Job details URL |
+| **CI_REPOSITORY_URL**                     | 9.0    | all    | The URL to clone the Git repository |
+| **CI_RUNNER_DESCRIPTION**                 | 8.10   | 0.5    | The description of the runner as saved in GitLab |
+| **CI_RUNNER_ID**                          | 8.10   | 0.5    | The unique id of runner being used |
+| **CI_RUNNER_TAGS**                        | 8.10   | 0.5    | The defined runner tags |
+| **CI_RUNNER_VERSION**                     | all    | 10.6   | GitLab Runner version that is executing the current job |
+| **CI_RUNNER_REVISION**                    | all    | 10.6   | GitLab Runner revision that is executing the current job |
+| **CI_RUNNER_EXECUTABLE_ARCH**             | all    | 10.6   | The OS/architecture of the GitLab Runner executable (note that this is not necessarily the same as the environment of the executor) |
+| **CI_PIPELINE_ID**                        | 8.10   | 0.5    | The unique id of the current pipeline that GitLab CI uses internally |
+| **CI_PIPELINE_IID**                       | 11.0   | all    | The unique id of the current pipeline scoped to project |
+| **CI_PIPELINE_TRIGGERED**                 | all    | all    | The flag to indicate that job was [triggered] |
+| **CI_PIPELINE_SOURCE**                    | 10.0   | all    | Indicates how the pipeline was triggered. Possible options are: `push`, `web`, `trigger`, `schedule`, `api`, and `pipeline`. For pipelines created before GitLab 9.5, this will show as `unknown` |
+| **CI_PROJECT_DIR**                        | all    | all    | The full path where the repository is cloned and where the job is run |
+| **CI_PROJECT_ID**                         | all    | all    | The unique id of the current project that GitLab CI uses internally |
+| **CI_PROJECT_NAME**                       | 8.10   | 0.5    | The project name that is currently being built (actually it is project folder name) |
+| **CI_PROJECT_NAMESPACE**                  | 8.10   | 0.5    | The project namespace (username or groupname) that is currently being built |
+| **CI_PROJECT_PATH**                       | 8.10   | 0.5    | The namespace with project name |
+| **CI_PROJECT_PATH_SLUG**                  | 9.3    | all    | `$CI_PROJECT_PATH` lowercased and with everything except `0-9` and `a-z` replaced with `-`. Use in URLs and domain names. |
+| **CI_PIPELINE_URL**                       | 11.1   | 0.5    | Pipeline details URL |
+| **CI_PROJECT_URL**                        | 8.10   | 0.5    | The HTTP address to access project |
+| **CI_PROJECT_VISIBILITY**                 | 10.3   | all    | The project visibility (internal, private, public) |
+| **CI_REGISTRY**                           | 8.10   | 0.5    | If the Container Registry is enabled it returns the address of GitLab's Container Registry |
+| **CI_REGISTRY_IMAGE**                     | 8.10   | 0.5    | If the Container Registry is enabled for the project it returns the address of the registry tied to the specific project |
+| **CI_REGISTRY_PASSWORD**                  | 9.0    | all    | The password to use to push containers to the GitLab Container Registry |
+| **CI_REGISTRY_USER**                      | 9.0    | all    | The username to use to push containers to the GitLab Container Registry |
+| **CI_SERVER**                             | all    | all    | Mark that job is executed in CI environment |
+| **CI_SERVER_NAME**                        | all    | all    | The name of CI server that is used to coordinate jobs |
+| **CI_SERVER_REVISION**                    | all    | all    | GitLab revision that is used to schedule jobs |
+| **CI_SERVER_VERSION**                     | all    | all    | GitLab version that is used to schedule jobs |
+| **CI_SERVER_VERSION_MAJOR**               | 11.4   | all    | GitLab version major component |
+| **CI_SERVER_VERSION_MINOR**               | 11.4   | all    | GitLab version minor component |
+| **CI_SERVER_VERSION_PATCH**               | 11.4   | all    | GitLab version patch component |
+| **CI_SHARED_ENVIRONMENT**                 | all    | 10.1   | Marks that the job is executed in a shared environment (something that is persisted across CI invocations like `shell` or `ssh` executor). If the environment is shared, it is set to true, otherwise it is not defined at all. |
+| **GET_SOURCES_ATTEMPTS**                  | 8.15   | 1.9    | Number of attempts to fetch sources running a job |
+| **GITLAB_CI**                             | all    | all    | Mark that job is executed in GitLab CI environment |
+| **GITLAB_USER_EMAIL**                     | 8.12   | all    | The email of the user who started the job |
+| **GITLAB_USER_ID**                        | 8.12   | all    | The id of the user who started the job |
+| **GITLAB_USER_LOGIN**                     | 10.0   | all    | The login username of the user who started the job |
+| **GITLAB_USER_NAME**                      | 10.0   | all    | The real name of the user who started the job |
+| **RESTORE_CACHE_ATTEMPTS**                | 8.15   | 1.9    | Number of attempts to restore the cache running a job |
 
 ## GitLab 9.0 renaming
 
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index af7e41db443..1277d1fdf8b 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -342,15 +342,16 @@ In addition, `only` and `except` allow the use of special keywords:
 
 | **Value** |  **Description**  |
 | --------- |  ---------------- |
-| `branches`  | When a branch is pushed.  |
-| `tags`      | When a tag is pushed.  |
-| `api`       | When pipeline has been triggered by a second pipelines API (not triggers API).  |
-| `external`  | When using CI services other than GitLab. |
-| `pipelines` | For multi-project triggers, created using the API with `CI_JOB_TOKEN`. |
-| `pushes`    | Pipeline is triggered by a `git push` by the user. |
-| `schedules` | For [scheduled pipelines][schedules]. |
-| `triggers`  | For pipelines created using a trigger token. |
-| `web`       | For pipelines created using **Run pipeline** button in GitLab UI (under your project's **Pipelines**). |
+| `branches`       | When a git reference of a pipeline is a branch.  |
+| `tags`           | When a git reference of a pipeline is a tag.  |
+| `api`            | When pipeline has been triggered by a second pipelines API (not triggers API).  |
+| `external`       | When using CI services other than GitLab. |
+| `pipelines`      | For multi-project triggers, created using the API with `CI_JOB_TOKEN`. |
+| `pushes`         | Pipeline is triggered by a `git push` by the user. |
+| `schedules`      | For [scheduled pipelines][schedules]. |
+| `triggers`       | For pipelines created using a trigger token. |
+| `web`            | For pipelines created using **Run pipeline** button in GitLab UI (under your project's **Pipelines**). |
+| `merge_requests` | When a merge request is created or updated (See [pipelines for merge requests](../merge_request_pipelines/index.md)). |
 
 In the example below, `job` will run only for refs that start with `issue-`,
 whereas all branches will be skipped:
@@ -391,6 +392,24 @@ job:
 The above example will run `job` for all branches on `gitlab-org/gitlab-ce`,
 except master.
 
+If a job does not have neither `only` nor `except` rule,
+`only: ['branches', 'tags']` is set by default.
+
+For example,
+
+```yaml
+job:
+  script: echo 'test'
+```
+
+is translated to
+
+```yaml
+job:
+  script: echo 'test'
+  only: ['branches', 'tags']
+```
+
 ## `only` and `except` (complex)
 
 > `refs` and `kubernetes` policies introduced in GitLab 10.0
diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md
index 5b54b6ecdd5..85d8d804133 100644
--- a/doc/user/project/merge_requests/index.md
+++ b/doc/user/project/merge_requests/index.md
@@ -259,6 +259,16 @@ all your changes will be available to preview by anyone with the Review Apps lin
 
 [Read more about Review Apps.](../../../ci/review_apps/index.md)
 
+## Pipelines for merge requests
+
+When a developer updates a merge request, a pipeline should quickly report back
+its result to the developer, but often pipelines take long time to complete
+because general branch pipelines contain unnecessary jobs from the merge request standpoint.
+You can customize a specific pipeline structure for merge requests in order to
+speed the cycle up by running only important jobs.
+
+Learn more about [pipelines for merge requests](../../../ci/merge_request_pipelines/index.md).
+
 ## Pipeline status in merge requests
 
 If you've set up [GitLab CI/CD](../../../ci/README.md) in your project,