머지 트레인

머지 트레인 (Merge trains)

기본 브랜치로 병합이 잦은 프로젝트에서는 서로 다른 머지 리퀘스트의 변경 사항이 충돌할 수 있어요. 머지 트레인을 사용하면 머지 리퀘스트를 큐에 넣을 수 있어요. 각 머지 리퀘스트는 그보다 앞선 다른 머지 리퀘스트와 비교되어 모두 함께 잘 동작하는지 확인돼요.

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

%%{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)가 순서대로 머지 트레인에 추가되면, 병렬로 실행되는 세 개의 병합 결과 파이프라인이 만들어져요:

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

B의 파이프라인이 실패하면:

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

A가 성공적으로 완료되면 대상 브랜치로 병합되고 C는 계속 실행돼요. 트레인에 추가되는 새 머지 리퀘스트들은 이제 대상 브랜치에 있는 A 변경 사항과 머지 트레인의 C 변경 사항을 포함해요.

**머지 트레인의 병렬 실행이 커밋으로 기본 브랜치가 깨지는 것을 어떻게 방지하는지 데모 영상을 시청하세요.

자동 파이프라인 취소

GitLab CI/CD는 중복 파이프라인을 감지하고 리소스 보존을 위해 취소해요.

중복 머지 트레인 파이프라인은 다음 상황에서 발생해요:

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

이런 경우 GitLab은 트레인의 일부 또는 모든 머지 리퀘스트에 대해 새 머지 트레인 파이프라인을 만들어야 해요. 이전 파이프라인은 더 이상 유효하지 않은 머지 트레인의 이전 결합 변경 사항과 비교하고 있었으므로, 이전 파이프라인들은 취소돼요.

머지 트레인 활성화하기

전제 조건:

Maintainer 역할이 있어야 해요.
저장소가 GitLab 저장소여야 하며 외부 저장소가 아니어야 해요.
파이프라인이 머지 리퀘스트 파이프라인을 사용하도록 구성되어 있어야 해요. 그렇지 않으면 머지 리퀘스트가 해결되지 않은 상태로 멈추거나 파이프라인이 드롭될 수 있어요.
병합 결과 파이프라인이 활성화되어 있어야 해요.

머지 트레인을 활성화하려면:

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

머지 트레인 시작하기

전제 조건:

대상 브랜치에 병합하거나 push할 권한이 있어야 해요.

머지 트레인을 시작하려면:

머지 리퀘스트로 가세요.
다음 중 하나를 선택하세요:실행 중인 파이프라인이 없을 때는 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. 같은 메시지로 표시돼요. 링크를 선택해 머지 트레인을 볼 수 있어요.

이제 다른 머지 리퀘스트를 트레인에 추가할 수 있어요.

머지 트레인 보기

머지 트레인 시각화는 GitLab 17.3에서 도입됐어요.

머지 트레인을 보면 큐에 있는 머지 리퀘스트의 순서와 상태를 더 잘 파악할 수 있어요. 머지 트레인 상세 페이지에는 큐에 있는 활성 머지 리퀘스트와 트레인의 일부였던 병합된 머지 리퀘스트가 표시돼요.

머지 리퀘스트 목록에서 머지 트레인 상세 정보에 접근하려면:

상단 바에서 Search or go to를 선택하고 프로젝트를 찾으세요.
왼쪽 사이드바에서 Code > Merge requests를 선택하세요.
머지 리퀘스트 목록 위에서 Merge trains를 선택하세요.
선택 사항. 대상 브랜치별로 머지 트레인을 필터링하세요.

이 보기에는 다음에서 View merge train details를 선택해도 접근할 수 있어요:

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

머지 트레인 상세 뷰에서 머지 리퀘스트를 제거( close )할 수도 있어요.

머지 트레인에 머지 리퀘스트 추가하기

머지 트레인용 자동 병합은 GitLab 17.2에서 merge_when_checks_pass_merge_train 기능 플래그와 함께 도입됐어요. 기본적으로 비활성화.
GitLab 17.2에서 GitLab.com에 머지 트레인 자동 병합이 활성화됐어요.
GitLab 17.4에서 머지 트레인 자동 병합이 기본적으로 활성화됐어요.
GitLab 17.7에서 머지 트레인 자동 병합이 일반 공개(GA)됐어요. merge_when_checks_pass_merge_train 기능 플래그가 제거됐어요.

전제 조건:

대상 브랜치에 병합하거나 push할 권한이 있어야 해요.

머지 트레인에 머지 리퀘스트를 추가하려면:

머지 리퀘스트를 방문하세요.
다음 중 하나를 선택하세요:실행 중인 파이프라인이 없을 때는 Merge.파이프라인이 실행 중일 때는 Set to auto-merge.

머지 리퀘스트의 머지 트레인 상태가 파이프라인 위젯 아래에 This merge request is 2 of 3 in queue. 같은 메시지로 표시돼요.

각 머지 트레인은 병렬로 실행할 수 있는 최대 파이프라인 수를 가질 수 있어요. 기본 제한은 20이에요. 머지 트레인에 제한보다 많은 머지 리퀘스트를 추가하면, 파이프라인 하나가 완료될 때까지 추가 머지 리퀘스트는 대기해요. 큐에 대기하는 머지 리퀘스트 수에는 제한이 없어요.

머지 리퀘스트가 머지 트레인에 합류한 후에는, 모든 스레드가 해결되어야 병합이 활성화되어 있어도, 새 대화 스레드가 그 머지 리퀘스트를 트레인에서 제거하거나 병합을 막지 않아요. 이 동작은 의도적이에요. 자세한 내용은 issue 220916을 참고하세요.

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

머지 트레인에서 머지 리퀘스트를 제거하면:

제거된 머지 리퀘스트 뒤로 큐에 있던 머지 리퀘스트의 모든 파이프라인이 다시 시작돼요.
중복 파이프라인은 취소돼요.

머지 리퀘스트는 나중에 다시 머지 트레인에 추가할 수 있어요.

머지 트레인에서 머지 리퀘스트를 제거하려면:

머지 리퀘스트에서 Cancel auto-merge를 선택하세요.
머지 트레인 상세에서 머지 리퀘스트 옆의 close 를 선택하세요.

머지 트레인을 건너뛰고 즉시 병합하기

반드시 긴급히 병합해야 하는 중요 패치처럼 우선순위가 높은 머지 리퀘스트가 있다면 Merge immediately를 선택할 수 있어요.

즉시 병합은 많은 CI/CD 리소스를 사용할 수 있어요. 이 옵션은 중요 상황에서만 사용하세요.

머지 리퀘스트를 즉시 병합하면:

머지 트레인 상태와 관계없이 머지 리퀘스트의 커밋이 병합돼요.
트레인에 있는 다른 모든 머지 리퀘스트의 머지 트레인 파이프라인은 취소돼요.
새 머지 트레인이 시작되고 원래 머지 트레인의 모든 머지 리퀘스트가 각각 새 머지 트레인 파이프라인과 함께 이 새 머지 트레인에 추가돼요. 이 새 머지 트레인 파이프라인들은 이제 즉시 병합된 머지 리퀘스트가 추가한 커밋을 포함해요.

프로젝트가 fast-forward 병합 방식을 사용하고 소스 브랜치가 대상 브랜치보다 뒤처져 있다면 merge immediately 옵션을 사용할 수 없을 수 있어요. 자세한 내용은 issue 434070을 참고하세요.

머지 트레인 파이프라인을 다시 시작하지 않고 즉시 병합하기

GitLab 16.5에서 merge_trains_skip_train 기능 플래그와 함께 도입됐어요. 기본적으로 비활성화.
GitLab 16.10에서 실험 기능으로 활성화됐어요.

GitLab Self-Managed에서 이 기능은 기본적으로 사용할 수 있어요. 기능을 숨기려면 관리자가 merge_trains_skip_train이라는 기능 플래그를 비활성화할 수 있어요. GitLab.com과 GitLab Dedicated에서는 이 기능을 사용할 수 있어요.

실행 중인 머지 트레인을 완전히 다시 시작하지 않고도 머지 리퀘스트가 병합되도록 허용할 수 있어요. 마이너 문서 업데이트처럼 파이프라인을 안전하게 건너뛸 수 있는 변경 사항을 빠르게 병합하는 데 이 기능을 사용하세요.

fast-forward 또는 semi-linear 병합 방식에서는 머지 트레인을 건너뛸 수 없어요. 자세한 내용은 issue 429009을 참고하세요.

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

이 기능으로 보안이나 버그 수정을 빠르게 병합할 수 있지만, 트레인을 건너뛴 머지 리퀘스트의 변경 사항은 트레인의 다른 머지 리퀘스트와 검증되지 않아요. 이 다른 머지 트레인 파이프라인들이 성공적으로 완료되어 병합된다면 결합된 변경 사항이 호환되지 않을 위험이 있어요. 그러면 대상 브랜치에서 새 실패를 해결하기 위해 추가 작업이 필요할 수 있어요.

전제 조건:

Maintainer 역할이 있어야 해요.
머지 트레인이 활성화되어 있어야 해요.

파이프라인 재시작 없이 트레인 건너뛰기를 활성화하려면:

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

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

머지 리퀘스트는 병합되고, 기존 머지 트레인 파이프라인은 취소되거나 다시 시작되지 않아요.

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

GitLab 19.0에서 도입됐어요.

기본적으로 각 머지 트레인은 최대 20개 파이프라인을 병렬로 실행할 수 있어요. 이 제한에 도달하면 파이프라인 슬롯이 생길 때까지 추가 머지 리퀘스트가 대기해요.

프로젝트의 이 제한을 수정하려면:

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

프로젝트 제한은 인스턴스 제한을 초과할 수 없어요.

프로젝트 API 또는 GraphQL API를 사용할 수도 있어요.

머지 트레인 강제 적용하기

GitLab 19.2에서 merge_train_enforcement 기능 플래그와 함께 도입됐어요. 기본적으로 비활성화.
GitLab 19.3에서 일반 공개(GA)됐어요. merge_train_enforcement 기능 플래그가 제거됐어요.

기본적으로 병합 권한이 있으면 머지 트레인을 우회할 수 있어요. 강제 적용은 모든 머지 리퀘스트가 트레인을 거치도록 요구해요.

강제 적용이 활성화되면:

GitLab이 Merge immediately 옵션들( Merge now and don't restart train 포함)을 숨겨요.
REST API와 GraphQL API가 직접 병합을 거부해요.
자동 병합이 모든 병합을 트레인으로 라우팅해요.

머지 트레인 강제 적용에는 세 가지 수준이 있어요:

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

전제 조건:

Maintainer 역할이 있어야 해요.
프로젝트에 머지 트레인을 활성화해야 해요.

머지 트레인 강제 적용을 구성하려면:

상단 바에서 Search or go to를 선택하고 프로젝트를 찾으세요.
왼쪽 사이드바에서 Settings > Merge requests를 선택하세요.
Merge options 섹션의 Merge train enforcement 아래에서 강제 수준을 선택하세요.
Save changes를 선택하세요.

문제 해결

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

파이프라인이 실행되는 동안 더 이상 병합할 수 없게 되면 머지 리퀘스트가 머지 트레인에서 자동으로 제거돼요. 일반적인 원인은:

머지 트레인 파이프라인이 성공하지 못한 경우.
머지 리퀘스트가 draft로 표시된 경우.
머지 리퀘스트가 닫힌 경우.
소스 브랜치가 업데이트된 경우.
머지 충돌처럼 머지 리퀘스트가 모든 머지 검사를 통과하지 못한 경우.
머지 리퀘스트의 변경 사항을 트레인의 앞선 머지 리퀘스트 변경 사항과 결합할 수 없었던 경우.
병합이 제때 완료되지 않은 경우.
예기치 않은 오류가 발생한 경우.

머지 리퀘스트가 제거된 이유를 알아보려면 Overview 탭의 Activity 섹션에서 User removed this merge request from the merge train because ... 같은 메시지를 확인하세요.

System note text	What it means	What to do
`the merge could not be completed. Merge request is not mergeable. Explanation: The pipeline must succeed.`	머지 검사에 실패했어요. "Merge request is not mergeable"은 이유를 알려주지 않아요. 진짜 이유는 "Explanation:" 뒤에 있어요. 머지 충돌이 한 예시예요.	원인을 고친 다음 머지 리퀘스트를 머지 트레인에 다시 추가하세요.
`the merge train pipeline could not be prepared: Failed to create merge commit for source_sha ... and target_sha ...`	변경 사항을 트레인의 앞선 머지 리퀘스트 변경 사항과 결합할 수 없었어요. 원인은 보통 다른 머지 리퀘스트와의 충돌이에요.	소스 브랜치를 대상 브랜치에 리베이스하고 충돌을 해결한 다음 머지 리퀘스트를 머지 트레인에 다시 추가하세요.
`the merge train pipeline could not be prepared: merging commits: merge: there are conflicting files. Conflicts in: ...`	변경 사항이 트레인의 앞선 머지 리퀘스트의 변경 사항과 충돌해요. 시스템 노트는 충돌하는 파일 최대 10개를 나열하고 추가 파일 수를 더해요.	소스 브랜치를 대상 브랜치에 리베이스하고 충돌을 해결한 다음 머지 리퀘스트를 머지 트레인에 다시 추가하세요.
`an unexpected error occurred. Correlation ID: <id>`	병합 중 예기치 않은 오류가 발생했어요.	상관 ID를 관리자나 GitLab Support에 전달하고 머지 리퀘스트를 머지 트레인에 다시 추가하세요.
`the merge did not complete in time. [Learn more](...)`	병합이 시작됐지만 보통 백그라운드 실패 때문에 끝나기 전에 멈췄어요. 멈춘 상태가 감지되어 머지 리퀘스트가 제거됐어요.	머지 리퀘스트를 머지 트레인에 다시 추가하세요. 계속 발생하면 관리자나 GitLab Support에 연락하세요.

자동 병합을 사용할 수 없음

머지 트레인이 활성화되어 있을 때는 자동 병합(이전 Merge when pipeline succeeds)으로 머지 트레인을 건너뛸 수 없어요. 자세한 내용은 issue 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을 선택하세요.
문제를 고치는 새 커밋을 푸시하세요. 이 역시 새 파이프라인을 트리거해요.

자세한 내용은 issue 35135을 참고하세요.

자동화 도구가 405 오류로 병합 실패

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

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

더 알아보기

다음으로는 병합 결과 파이프라인과 자동 병합 문서를 함께 보면, 머지 트레인과 자동화를 결합해 기본 브랜치를 항상 안정적으로 유지하는 방법을 익힐 수 있어요.