기본 브랜치에 자주 머지되는 프로젝트에서는 서로 다른 머지 리퀘스트의 변경 사항이 충돌할 수 있습니다. 머지 트레인을 사용하면 머지 리퀘스트를 대기열에 넣을 수 있습니다. 각 머지 리퀘스트는 대기열에서 앞서 있는 다른 머지 리퀘스트와 비교되어, 모두 함께 정상적으로 동작하는지 확인됩니다.

병합 결과 파이프라인은 하나의 머지 리퀘스트 변경 사항을 대상 브랜치와 결합해 테스트합니다. 병합 결과 파이프라인은 비슷한 시점에 머지되는 다른 머지 리퀘스트를 고려하지 않습니다. 두 머지 리퀘스트가 각각 자신의 파이프라인은 통과하더라도, 두 변경 사항을 결합하면 여전히 충돌할 수 있습니다. 둘 다 머지되면 모든 파이프라인이 성공했더라도 대상 브랜치가 깨질 수 있습니다.

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph LR
accTitle: Two merge requests that pass individually but conflict together
accDescr: Merge request A and merge request B each pass a pipeline that tests their changes combined with the target branch alone. When both merge, the combined changes break the target branch.
subgraph Without merge trains
target[Target branch] --> pipeline_a[Pipeline for A: passes]
target --> pipeline_b[Pipeline for B: passes]
pipeline_a --> merge_both[Both merge]
pipeline_b --> merge_both
merge_both -.-> broken[Target branch breaks]
end

머지 트레인은 대기열에서 앞서 있는 모든 머지 리퀘스트의 결합된 변경 사항과 비교해 각 머지 리퀘스트를 테스트함으로써 이러한 문제를 방지합니다. 이를 통해 충돌이 대상 브랜치에 도달하기 전에 발견됩니다.

다음에 해당하는 프로젝트라면 머지 트레인을 사용합니다.

• 기본 브랜치에 머지가 자주 발생하는 프로젝트
• 비슷한 시점에 머지 준비가 완료되는 머지 리퀘스트가 여러 개인 프로젝트
• 기본 브랜치의 파이프라인이 항상 성공 상태를 유지해야 하는 프로젝트

머지 트레인 워크플로#

머지를 기다리는 머지 리퀘스트가 없는 상태에서 Merge 또는 Set to auto-merge를 선택하면 머지 트레인이 시작됩니다. GitLab은 변경 사항이 기본 브랜치에 머지될 수 있는지 확인하는 머지 트레인 파이프라인을 시작합니다. 이 첫 번째 파이프라인은 소스 브랜치와 대상 브랜치의 변경 사항을 결합해 실행되는 병합 결과 파이프라인과 동일합니다. 내부 병합 결과 커밋의 작성자는 머지를 시작한 사용자입니다.

첫 번째 파이프라인이 완료된 직후 머지되도록 두 번째 머지 리퀘스트를 대기열에 넣으려면 Merge 또는 Set to auto-merge를 선택해 트레인에 추가합니다. 이 두 번째 머지 트레인 파이프라인은 두 머지 리퀘스트의 변경 사항을 대상 브랜치와 결합해 실행됩니다. 마찬가지로 세 번째 머지 리퀘스트를 추가하면 해당 파이프라인은 세 머지 리퀘스트 모두의 변경 사항을 대상 브랜치와 머지해 실행됩니다. 이 파이프라인들은 모두 병렬로 실행됩니다.

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph LR
accTitle: Merge train pipelines test combined changes
accDescr: Pipeline 1 tests merge request A against the target branch. Pipeline 2 tests merge request A and B together against the target branch. Pipeline 3 tests merge request A, B, and C together against the target branch. The three pipelines run in parallel.
subgraph Merge train
target[Target branch] --> pipeline_1[Pipeline 1: A]
target --> pipeline_2[Pipeline 2: A + B]
target --> pipeline_3[Pipeline 3: A + B + C]
end

각 머지 리퀘스트는 다음 조건을 모두 충족한 뒤에만 대상 브랜치로 머지됩니다.

• 해당 머지 리퀘스트의 파이프라인이 성공적으로 완료됩니다.
• 대기열에서 앞서 있는 다른 모든 머지 리퀘스트가 머지됩니다.

머지 트레인 파이프라인이 실패하면 해당 머지 리퀘스트는 머지되지 않습니다. GitLab은 해당 머지 리퀘스트를 머지 트레인에서 제거하고, 그 뒤에 대기 중이던 모든 머지 리퀘스트에 대해 새 파이프라인을 시작합니다.

예를 들어 살펴보겠습니다.

세 머지 리퀘스트(A, B, C)가 순서대로 머지 트레인에 추가되면, 병렬로 실행되는 세 개의 병합 결과 파이프라인이 생성됩니다.

1. 첫 번째 파이프라인은 A의 변경 사항을 대상 브랜치와 결합해 실행됩니다.
2. 두 번째 파이프라인은 A와 B의 변경 사항을 대상 브랜치와 결합해 실행됩니다.
3. 세 번째 파이프라인은 A, B, C의 변경 사항을 대상 브랜치와 결합해 실행됩니다.

B의 파이프라인이 실패하면 다음과 같이 진행됩니다.

• 첫 번째 파이프라인(A)은 계속 실행됩니다.
• B는 트레인에서 제거됩니다.
• C의 파이프라인은 취소되고, A와 C의 변경 사항(B의 변경 사항 제외)을 대상 브랜치와 결합한 새 파이프라인이 시작됩니다.

이후 A가 성공적으로 완료되면 대상 브랜치로 머지되고, C는 계속 실행됩니다. 트레인에 새로 추가되는 머지 리퀘스트는 이제 대상 브랜치에 반영된 A의 변경 사항과, 머지 트레인에 있는 C의 변경 사항을 모두 포함합니다.

머지 트레인의 병렬 실행이 어떻게 커밋으로 인한 기본 브랜치 손상을 방지하는지 보여주는 영상을 시청해 보십시오.

자동 파이프라인 취소#

GitLab CI/CD는 중복 파이프라인을 감지하면 리소스를 절약하기 위해 취소합니다.

다음과 같은 경우에 중복 머지 트레인 파이프라인이 발생합니다.

• 머지 트레인에 있는 머지 리퀘스트 중 하나의 파이프라인이 실패하는 경우
• 머지 트레인을 건너뛰고 즉시 머지하는 경우
• 머지 트레인에서 머지 리퀘스트를 제거하는 경우

이러한 경우 GitLab은 트레인에 있는 일부 또는 전체 머지 리퀘스트에 대해 새 머지 트레인 파이프라인을 생성해야 합니다. 기존 파이프라인은 더 이상 유효하지 않은 이전의 결합된 변경 사항을 기준으로 비교하고 있었으므로, 이 기존 파이프라인은 취소됩니다.

머지 트레인 활성화#

사전 요구 사항:

• Maintainer 권한이 있어야 합니다.
• 리포지터리가 외부 리포지터리가 아닌 GitLab 리포지터리여야 합니다.
• 파이프라인이 머지 리퀘스트 파이프라인을 사용하도록 구성되어 있어야 합니다. 그렇지 않으면 머지 리퀘스트가 해결되지 않은 상태로 멈추거나 파이프라인이 드롭될 수 있습니다.
• 병합 결과 파이프라인이 활성화되어 있어야 합니다.

머지 트레인을 활성화하려면 다음과 같이 진행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > Merge requests를 선택합니다.
3. Merge options 섹션에서 Enable merged results pipelines가 활성화되어 있는지 확인하고 Enable merge trains를 선택합니다.
4. Save changes를 선택합니다.

머지 트레인 시작#

사전 요구 사항:

• 대상 브랜치로 머지하거나 푸시할 권한이 있어야 합니다.

머지 트레인을 시작하려면 다음과 같이 진행합니다.

1. 머지 리퀘스트로 이동합니다.
2. 다음 중 하나를 선택합니다.
   • 실행 중인 파이프라인이 없는 경우 Merge를 선택합니다.
   • 파이프라인이 실행 중인 경우 Set to auto-merge를 선택합니다.

머지 리퀘스트의 머지 트레인 상태는 파이프라인 위젯 아래에 A new merge train has started and this merge request is the first of the queue. View merge train details.와 유사한 메시지로 표시됩니다. 이 링크를 선택하면 머지 트레인을 볼 수 있습니다.

이제 다른 머지 리퀘스트도 트레인에 추가할 수 있습니다.

머지 트레인 보기#

머지 트레인을 보면 대기열에 있는 머지 리퀘스트의 순서와 상태를 더 잘 파악할 수 있습니다. 머지 트레인 세부 정보 페이지에는 대기열에 있는 활성 머지 리퀘스트와 트레인에 속했던 머지된 머지 리퀘스트가 표시됩니다.

머지 리퀘스트 목록에서 머지 트레인 세부 정보에 접근하려면 다음과 같이 진행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Code > Merge requests를 선택합니다.
3. 머지 리퀘스트 목록 위에서 Merge trains를 선택합니다.
4. 선택 사항입니다. 대상 브랜치로 머지 트레인을 필터링합니다.

다음 위치에서 View merge train details를 선택해도 이 화면에 접근할 수 있습니다.

• 머지 트레인에 추가된 머지 리퀘스트의 파이프라인 위젯과 시스템 노트
• 머지 트레인 파이프라인의 파이프라인 세부 정보 페이지

머지 트레인 세부 정보 화면에서 (✗)를 선택해 머지 리퀘스트를 제거할 수도 있습니다.

머지 트레인에 머지 리퀘스트 추가#

사전 요구 사항:

• 대상 브랜치로 머지하거나 푸시할 권한이 있어야 합니다.

머지 트레인에 머지 리퀘스트를 추가하려면 다음과 같이 진행합니다.

1. 머지 리퀘스트로 이동합니다.
2. 다음 중 하나를 선택합니다.
   • 실행 중인 파이프라인이 없는 경우 Merge를 선택합니다.
   • 파이프라인이 실행 중인 경우 Set to auto-merge를 선택합니다.

머지 리퀘스트의 머지 트레인 상태는 파이프라인 위젯 아래에 This merge request is 2 of 3 in queue.와 유사한 메시지로 표시됩니다.

각 머지 트레인은 최대 병렬 파이프라인 수만큼 실행할 수 있습니다. 기본 한도는 20입니다. 한도보다 많은 머지 리퀘스트를 머지 트레인에 추가하면, 초과된 머지 리퀘스트는 파이프라인이 완료될 때까지 대기열에 머무릅니다. 대기열에 있는 머지 리퀘스트 수에는 제한이 없습니다.

머지 리퀘스트가 머지 트레인에 합류한 뒤에는 모든 스레드가 해결되어야 함 설정이 활성화되어 있더라도, 새 대화 스레드가 생겨도 트레인에서 제거되거나 머지가 막히지 않습니다. 이는 의도된 동작입니다. 자세한 내용은 이슈 220916을 참고합니다.

머지 트레인에서 머지 리퀘스트 제거#

머지 트레인에서 머지 리퀘스트를 제거하면 다음과 같이 동작합니다.

• 제거된 머지 리퀘스트 뒤에 대기 중이던 머지 리퀘스트의 모든 파이프라인이 재시작됩니다.
• 중복 파이프라인은 취소됩니다.

이후 해당 머지 리퀘스트를 머지 트레인에 다시 추가할 수 있습니다.

머지 트레인에서 머지 리퀘스트를 제거하려면 다음과 같이 진행합니다.

• 머지 리퀘스트에서 Cancel auto-merge를 선택합니다.
• 머지 트레인 세부 정보에서 해당 머지 리퀘스트 옆의 ✗ 를 선택합니다.

머지 트레인 건너뛰고 즉시 머지#

긴급하게 머지해야 하는 중요한 패치처럼 우선순위가 높은 머지 리퀘스트가 있다면 Merge immediately 를 선택할 수 있습니다.

머지 리퀘스트를 즉시 머지하면 다음과 같이 동작합니다.

• 머지 트레인의 상태와 무관하게 해당 머지 리퀘스트의 커밋이 머지됩니다.
• 트레인에 있는 다른 모든 머지 리퀘스트의 머지 트레인 파이프라인이 취소됩니다.
• 새 머지 트레인이 시작되고, 기존 머지 트레인에 있던 모든 머지 리퀘스트가 각각 새 머지 트레인 파이프라인과 함께 이 새 머지 트레인에 추가됩니다. 이 새 머지 트레인 파이프라인에는 이제 즉시 머지된 머지 리퀘스트에서 추가된 커밋이 포함됩니다.

머지 트레인 파이프라인을 재시작하지 않고 즉시 머지#

실행 중인 머지 트레인을 완전히 재시작하지 않고도 머지 리퀘스트를 머지할 수 있도록 허용할 수 있습니다. 사소한 문서 업데이트처럼 파이프라인을 안전하게 건너뛸 수 있는 변경 사항을 빠르게 머지할 때 이 기능을 사용합니다.

패스트 포워드 또는 세미 리니어 머지 방법에서는 머지 트레인을 건너뛸 수 없습니다. 자세한 내용은 이슈 429009를 참고합니다.

머지 트레인 건너뛰기는 실험 기능입니다. 이후 릴리스에서 변경되거나 완전히 제거될 수 있습니다.

사전 요구 사항:

• Maintainer 권한이 있어야 합니다.
• 머지 트레인이 활성화되어 있어야 합니다.

파이프라인 재시작 없이 트레인 건너뛰기를 활성화하려면 다음과 같이 진행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > Merge requests를 선택합니다.
3. Merge options 섹션에서 Enable merged results pipelines와 Enable merge trains 옵션이 활성화되어 있는지 확인합니다.
4. Merge immediately without restarting the merge train을 선택합니다.
5. Save changes를 선택합니다.

머지 트레인을 건너뛰고 머지 리퀘스트를 머지하려면, skip_merge_train 속성을 true로 설정해 머지 리퀘스트 머지 API 엔드포인트를 사용합니다.

머지 리퀘스트가 머지되며, 기존 머지 트레인 파이프라인은 취소되거나 재시작되지 않습니다.

머지 트레인 병렬 파이프라인 한도#

기본적으로 각 머지 트레인은 최대 20개의 파이프라인을 병렬로 실행할 수 있습니다. 이 한도에 도달하면 추가 머지 리퀘스트는 파이프라인 슬롯이 확보될 때까지 대기열에 머무릅니다.

프로젝트에서 이 한도를 수정하려면 다음과 같이 진행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > Merge requests를 선택합니다.
3. Merge options 섹션에서 Maximum parallel pipelines per merge train 값을 설정합니다. 최솟값은 1입니다. 값을 1로 설정하면 병렬 처리 없이 머지 리퀘스트를 순차적으로 처리합니다.
4. Save changes를 선택합니다.

프로젝트 한도는 인스턴스 한도를 초과할 수 없습니다.

프로젝트 API 또는 GraphQL API를 사용할 수도 있습니다.

머지 트레인 강제#

기본적으로 머지 권한이 있으면 머지 트레인을 우회할 수 있습니다. 강제 설정을 적용하면 모든 머지 리퀘스트가 트레인을 거쳐야 합니다.

강제 설정이 활성화되면 다음과 같이 동작합니다.

• GitLab은 Merge now and don't restart train을 포함한 Merge immediately 옵션을 숨깁니다.
• REST API와 GraphQL API는 직접 머지를 거부합니다.
• 자동 머지는 모든 머지를 트레인으로 전달합니다.

머지 트레인 강제에는 세 가지 수준이 있습니다.

• Allow bypass(기본값): 머지 권한이 있는 사용자는 UI 또는 API를 통해 머지 트레인을 우회할 수 있습니다.
• Enforce for all users: 모든 머지 리퀘스트가 머지 트레인을 거쳐야 합니다. Owner와 관리자를 포함해 누구도 머지 트레인을 우회할 수 없습니다.
• Enforce with Owner override: 모든 머지 리퀘스트가 머지 트레인을 거쳐야 하지만, Owner와 관리자는 개별 머지 리퀘스트에 대해 머지 트레인을 우회할 수 있습니다.

사전 요구 사항:

• Maintainer 권한이 있어야 합니다.
• 프로젝트에서 머지 트레인을 활성화해야 합니다.

머지 트레인 강제를 구성하려면 다음과 같이 진행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > Merge requests를 선택합니다.
3. Merge options 섹션의 Merge train enforcement에서 강제 수준을 선택합니다.
4. Save changes를 선택합니다.

문제 해결#

머지 트레인에서 머지 리퀘스트가 제외됨#

파이프라인이 실행되는 동안 더 이상 머지할 수 없는 상태가 되면 머지 리퀘스트가 머지 트레인에서 자동으로 제외됩니다. 흔한 원인은 다음과 같습니다.

• 머지 트레인 파이프라인이 성공하지 못한 경우
• 머지 리퀘스트가 드래프트로 표시된 경우
• 머지 리퀘스트가 닫힌 경우
• 소스 브랜치가 업데이트된 경우
• 머지 충돌 등으로 머지 리퀘스트가 모든 머지 검사를 통과하지 못한 경우
• 머지 리퀘스트의 변경 사항을 트레인에서 앞서 있는 머지 리퀘스트의 변경 사항과 결합할 수 없었던 경우
• 제한 시간 내에 머지가 완료되지 않은 경우
• 예기치 않은 오류가 발생한 경우

머지 리퀘스트가 제외된 이유를 확인하려면 Overview 탭의 Activity 섹션에서 User removed this merge request from the merge train because ...와 유사한 메시지를 확인합니다.

자동 머지를 사용할 수 없음#

머지 트레인이 활성화되어 있으면 머지 트레인을 건너뛰기 위해 자동 머지(이전 명칭 Merge when pipeline succeeds)를 사용할 수 없습니다. 자세한 내용은 이슈 12267을 참고합니다.

머지 트레인 파이프라인을 재시도할 수 없음#

머지 트레인 파이프라인이 실패하면 머지 리퀘스트가 트레인에서 제외되며, 실패한 파이프라인은 재시도할 수 없습니다. 머지 트레인 파이프라인은 머지 리퀘스트의 변경 사항과 트레인에 이미 있는 다른 머지 리퀘스트의 변경 사항을 결합한 병합 결과를 기준으로 실행됩니다. 머지 리퀘스트가 트레인에서 제외되면 이 병합 결과는 오래된 상태가 되어 파이프라인을 재시도할 수 없습니다.

다음을 수행할 수 있습니다.

• 머지 리퀘스트를 트레인에 다시 추가하면 새 파이프라인이 트리거됩니다.
• 잡이 간헐적으로 실패한다면 잡에 retry 키워드를 추가합니다. 재시도 후 성공하면 머지 리퀘스트는 머지 트레인에서 제거되지 않습니다.

머지 트레인에 머지 리퀘스트를 추가할 수 없음#

Pipelines must succeed가 활성화되어 있는데 최신 파이프라인이 실패한 경우 다음과 같이 동작합니다.

• Set to auto-merge 또는 Merge 옵션을 사용할 수 없습니다.
• 머지 리퀘스트에 The pipeline for this merge request failed. Please retry the job or push a new commit to fix the failure.가 표시됩니다.

머지 리퀘스트를 머지 트레인에 다시 추가하기 전에 다음을 시도할 수 있습니다.

• 실패한 잡을 재시도합니다. 통과하고 다른 잡도 실패하지 않았다면 파이프라인이 성공으로 표시됩니다.
• 전체 파이프라인을 다시 실행합니다. Pipelines 탭에서 Run pipeline을 선택합니다.
• 문제를 해결하는 새 커밋을 푸시합니다. 이 경우에도 새 파이프라인이 트리거됩니다.

자세한 내용은 이슈 35135를 참고합니다.

자동화 도구가 405 오류로 머지에 실패함#

머지 트레인 강제가 활성화되어 있으면, auto_merge=true 없이 머지 리퀘스트 API를 호출하는 모든 도구는 405 Method Not Allowed 응답을 받습니다. 여기에는 스크립트, CI/CD 잡, 봇이 포함됩니다.

이 문제를 해결하려면 도구가 auto_merge=true를 전달하도록 업데이트합니다. 그러면 머지 리퀘스트를 직접 머지하는 대신 머지 트레인에 추가합니다. 예를 들어 Renovate를 사용한다면 platformAutomerge 구성 옵션을 활성화합니다.