Commit 22f5c068 authored by Shinya Maeda's avatar Shinya Maeda Committed by Evan Read

Add trouble shooting for Merge Train

Add trouble shooting sections
parent 11b5c921
...@@ -62,18 +62,32 @@ CAUTION: **Warning:** ...@@ -62,18 +62,32 @@ CAUTION: **Warning:**
Make sure your `gitlab-ci.yml` file is [configured properly for pipelines for merge requests](../index.md#configuring-pipelines-for-merge-requests), Make sure your `gitlab-ci.yml` file is [configured properly for pipelines for merge requests](../index.md#configuring-pipelines-for-merge-requests),
otherwise pipelines for merged results won't run and your merge requests will be stuck in an unresolved state. otherwise pipelines for merged results won't run and your merge requests will be stuck in an unresolved state.
## Merge Trains **(PREMIUM)** ## Troubleshooting
Read the [documentation on Merge Trains](merge_trains/index.md). ### Pipelines for merged results not created even with new change pushed to merge request
<!-- ## Troubleshooting Can be caused by some disabled feature flags. Please make sure that
the following feature flags are enabled on your GitLab instance:
Include any troubleshooting steps that you can foresee. If you know beforehand what issues - `:ci_use_merge_request_ref`
one might have when setting this up, or when something is changed, or on upgrading, it's - `:merge_ref_auto_sync`
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`. To check these feature flag values, please ask administrator to execute the following commands:
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. --> ```shell
> sudo gitlab-rails console # Login to Rails console of GitLab instance.
> Feature.enabled?(:ci_use_merge_request_ref) # Check if it's enabled or not.
> Feature.enable(:ci_use_merge_request_ref) # Enable the feature flag.
```
## Using Merge Trains **(PREMIUM)**
By enabling [Pipelines for merged results](#pipelines-for-merged-results-premium),
GitLab will [automatically display](merge_trains/index.md#how-to-add-a-merge-request-to-a-merge-train)
a **Start/Add Merge Train button** as the most recommended merge strategy.
Generally, this is a safer option than merging merge requests immediately as your
merge request will be evaluated with an expected post-merge result before the actual
merge happens.
For more information, read the [documentation on Merge Trains](merge_trains/index.md).
...@@ -80,14 +80,65 @@ button while the latest pipeline is running. ...@@ -80,14 +80,65 @@ button while the latest pipeline is running.
![Add to merge train when pipeline succeeds](img/merge_train_start_when_pipeline_succeeds_v12_0.png) ![Add to merge train when pipeline succeeds](img/merge_train_start_when_pipeline_succeeds_v12_0.png)
<!-- ## Troubleshooting ## Immediately merge a merge request with a merge train
Include any troubleshooting steps that you can foresee. If you know beforehand what issues In case, you have a high-priority merge request (e.g. critical patch) to be merged urgently,
one might have when setting this up, or when something is changed, or on upgrading, it's you can use **Merge Immediately** option for bypassing the merge train.
important to describe those, too. Think of things that may go wrong and include them here. This is the fastest option to get the change merged into the target branch.
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`. ![Merge Immediately](img/merge_train_immediate_merge.png)
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. --> However, every time you merge a merge request immediately, it could affect the
existing merge train to be reconstructed, specifically, it regenerates expected
merge commits and pipelines. This means, merging immediately essentially wastes
CI resources.
## Troubleshooting
### Merge request dropped from the merge train immediately
If a merge request is not mergeable (for example, it's WIP, there is a merge
conflict, etc), your merge request will be dropped from the merge train automatically.
In these cases, the reason for dropping the merge request is in the **system notes**.
To check the reason:
1. Open the merge request that was dropped from the merge train.
1. Open the **Discussion** tab.
1. Find a system note that includes either:
- The text **... removed this merge request from the merge train because ...**
- **... aborted this merge request from the merge train because ...**
The reason is given in the text after the **because ...** phrase.
![Merge Train Failure](img/merge_train_failure.png)
### Merge When Pipeline Succeeds cannot be chosen
[Merge When Pipeline Succeeds](../../../../user/project/merge_requests/merge_when_pipeline_succeeds.md)
is unavailable when
[Pipelines for Merged Results is enabled](../index.md#enabling-pipelines-for-merged-results).
Follow [this issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/12267) to
track progress on this issue.
### Merge Train disturbs your workflow
First of all, please check if [merge immediately](#immediately-merge-a-merge-request-with-a-merge-train)
is available as a workaround in your workflow. This is the most recommended
workaround you'd be able to take immediately. If it's not available or acceptable,
please read through this section.
Merge train is enabled by default when you enable [Pipelines for merged results](../index.md),
however, you can forcibly disable this feature by disabling the feature flag `:merge_trains_enabled`.
After you disabled this feature, all the existing merge trains will be aborted and
you will no longer see the **Start/Add Merge Train** button in merge requests.
To check if the feature flag is enabled on your GitLab instance,
please ask administrator to execute the following commands:
```shell
> sudo gitlab-rails console # Login to Rails console of GitLab instance.
> Feature.enabled?(:merge_trains_enabled) # Check if it's enabled or not.
> Feature.disable(:merge_trains_enabled) # Disable the feature flag.
```
\ No newline at end of file
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment