Merge branch 'selhorn-dupepipelines' into 'master'

Docs - Duplicate pipelines for MRs - Troubleshooting

See merge request gitlab-org/gitlab!29530

doc/ci/merge_request_pipelines/index.md

@@ -245,14 +245,68 @@ to integrate your job with [GitLab Merge Request API](../../api/merge_requests.m
 You can find the list of available variables in [the reference sheet](../variables/predefined_variables.md).
 The variable names begin with the `CI_MERGE_REQUEST_` prefix.
 
-<!-- ## Troubleshooting
+## 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.
+### Two pipelines created when pushing to a merge request
 
-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. -->
+If two pipelines are created when you push a new change to a merge request,
+check your CI configuration file.
+
+For example, with this `.gitlab-ci.yml` configuration:
+
+```yaml
+test:
+  script: ./test
+  rules:
+    - if: $CI_MERGE_REQUEST_ID                      # Include this job in pipelines for merge request
+    - if: $CI_COMMIT_BRANCH                         # Include this job in all branch pipelines
+  # Or, if you are using the `only:` keyword:
+  # only:
+  #  - merge_requests
+  #  - branches
+```
+
+Two pipelines are created when you push a commit to a branch that also has a pending
+merge request:
+
+- A merge request pipeline that runs for the changes in the merge request. In
+  **CI/CD > Pipelines**, the merge request icon (**{merge-request}**)
+  and the merge request ID are displayed. If you hover over the ID, the merge request name is displayed.
+
+  ![MR pipeline icon example](img/merge_request_pipelines_doubled_MR_v12_09.png)
+
+- A "branch" pipeline that runs for the commit pushed to the branch. In **CI/CD > Pipelines**,
+  the branch icon (**{branch}**) and branch name are displayed. This pipeline is
+  created even if no merge request exists.
+
+  ![branch pipeline icon example](img/merge_request_pipelines_doubled_branch_v12_09.png)
+
+With the example configuration above, there is overlap between these two events.
+When you push a commit to a branch that also has an open merge request pending,
+both types of pipelines are created.
+
+To fix this overlap, you must explicitly define which job should run for which
+purpose, for example:
+
+```yaml
+test:
+  script: ./test
+  rules:
+    - if: $CI_MERGE_REQUEST_ID                      # Include this job in pipelines for merge request
+    - if: $CI_COMMIT_BRANCH == 'master'             # Include this job in master branch pipelines
+```
+
+Similar `rules:` should be added to all jobs to avoid any overlapping pipelines. Alternatively,
+you can use the [`workflow:`](../yaml/README.md#exclude-jobs-with-rules-from-certain-pipelines)
+parameter to add the same rules to all jobs globally.
+
+### Two pipelines created when pushing an invalid CI configuration file
+
+Similar to above, pushing to a branch with an invalid CI configuration file can trigger
+the creation of two types of failed pipelines. One pipeline is a failed merge request
+pipeline, and the other is a failed branch pipeline, but both are caused by the same
+invalid configuration.
+
+In rare cases, duplicate pipelines are created.
+
+See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/201845) for details.