검토 게이트와 병합: 기록에서 머지 큐까지

이슈와 명세, 결정 기록, 설계 검토, 풀 리퀘스트, 보호 브랜치, 머지 큐와 머지 트레인까지, 병합 전에 필요한 기록과 검토 절차를 살펴본다.

개정 2판 · 최근 고침: 독자에게 보이는 문장과 용어를 다듬고 기존 근거 연결을 유지했다. · 고침 기록 보기

도구의 동작과 팀별 운영 정책을 구분한다. 검토 단계의 수와 순서, 큐의 순서를 바꿀 수 있는 조건은 각 팀이 정한다. 아래 팀 사례는 실제로 실행하지 않은 가상 예시다.

개별 검사를 통과해도 병합 후 오류가 생기는 이유

각각 검사를 통과한 두 변경도 합치면 오류가 생길 수 있다. 개별 변경만 검사하고 결합된 상태를 확인하지 않으면 이런 문제를 놓치기 쉽다. 기본 브랜치에 병합하기 전에 다른 변경과 함께 동작하는지 확인해야 하는 이유다.

누가 왜 그렇게 정했는지 기록하지 않으면 같은 논쟁을 되풀이하거나 이전 결정을 모르고 뒤집을 수도 있다. 병합 전 검토에는 결정의 이유를 남기는 일과 코드를 합친 결과를 확인하는 일이 함께 필요하다.

기록과 검토 절차가 담당하는 일

이슈에는 필요한 작업을 제안하고, 명세에는 구현할 내용을 적는다. 결정 기록은 주요 선택의 이유를 남기며 설계 검토는 구현 방향을 점검한다. 풀 리퀘스트에서 변경을 논의한 뒤에는 보호 브랜치의 규칙을 충족해야 한다. 머지 큐와 트레인은 다른 변경과 합친 상태를 검사한다.

설계 방향은 설계 검토에서 살피고, 요구사항 중 테스트로 표현한 조건은 자동 검사로 확인한다. 다른 변경과 합친 상태는 큐와 트레인에서 검사한다. 한 단계의 검사를 강화해도 다른 단계가 맡은 일을 모두 대신할 수는 없다. 이 역할 구분은 여러 출처를 종합한 편집자의 해석이다.

ADR에 결정의 이유 남기기

아키텍처 결정 기록(ADR)은 설계 과정에서 내린 주요 결정을 적는 문서다. 결정의 맥락, 결정한 내용, 예상되는 결과를 담는다. 구현 방법뿐 아니라 그 방법을 선택한 이유를 남기므로, 나중에 합류한 사람도 당시 논의와 판단 근거를 확인할 수 있다.

출처의 안내에 따르면 누구나 ADR을 작성할 수 있다. 담당자를 정하고 공통 템플릿을 사용한다. 처음 상태는 Proposed(제안)이며, 검토 결과에 따라 승인하거나 수정을 요청하거나 거부한다. 검토 모임은 읽는 시간부터 시작하며 평균 10분에서 15분이면 충분하다고 안내는 적는다. 승인된 기록은 이후에 수정하지 않는다. 생각이 바뀌면 옛 기록을 고치지 않고 새 기록을 써서 대체하며, 옛 기록의 상태는 Superseded(대체됨)로 바뀐다. 거부된 기록도 이유를 남기고 Rejected(거부됨)로 둔다.

이 절의 근거 S31

명세에 기대 동작과 완료 조건 적기

명세(specification)는 이번 작업에서 구현할 내용을 적는 문서다. 어떤 입력에 어떻게 반응해야 하는지, 완료 여부를 판단할 인수 기준(acceptance criteria)은 무엇인지, 이번에 하지 않거나 다음으로 미룬 작업은 무엇인지 적는다. 검토자는 이를 기준으로 요구사항 충족 여부를 확인하고, 작성자는 목표가 달라지면 명세에도 변경 내용을 반영한다.

명세를 함께 읽고 기준이 모호하거나 범위가 빠져 있으면 코드를 검토하기 전에 보완한다. Spec Kit의 명세 템플릿은 사용자 시나리오와 독립된 테스트, Given/When/Then 인수 조건, 경계 사례, 기능 요구사항, 성공 기준, 작업 범위에 관한 가정을 기록한다. 모든 팀이 이 서식을 그대로 쓸 필요는 없다. 명세는 무엇을 구현할지, ADR은 주요 설계를 왜 선택했는지, 설계 검토와 풀 리퀘스트 검토는 요구사항을 어떻게 충족할지를 다룬다. 이 순서는 아래 가상 팀의 선택이며 보편적인 규칙은 아니다.

이 절의 근거 S40 · S31 · S32

풀 리퀘스트에서 변경 검토하기

풀 리퀘스트는 코드 변경을 병합하기 전에 논의하고 검토하는 공간이다. 대화, 커밋, 검사, 변경된 파일이 탭으로 나뉘어 있어 검토에 필요한 내용을 함께 볼 수 있다. 병합 상태에서는 병합을 막는 조건과 부족한 승인도 확인할 수 있다.

초안 상태로 작업을 먼저 공유하고, 준비가 끝나면 정식 검토를 요청할 수 있다. 초안은 병합할 수 없으며 코드 소유자에게 자동으로 검토를 요청하지도 않는다. 검토받을 준비가 되면 초안 상태를 해제하고 소유자의 검토를 요청한다. 내부적으로는 임시 참조와 가상 병합 결과를 만들어 병합 가능 여부를 확인한다. 이 정보는 자동화나 병합 문제를 진단할 때 활용할 수 있다.

이 절의 근거 S32

보호 브랜치로 병합 조건 적용하기

보호 브랜치는 중요한 브랜치에 거는 규칙이다. 강제 푸시와 삭제를 기본으로 막고, 병합 전의 조건을 건다. 조건의 목록은 승인 수, 상태 검사, 대화 해결, 서명된 커밋, 선형 기록, 머지 큐, 배포 성공 등이다.

설정할 때는 다음 동작을 확인해야 한다. 첫째, 필요한 승인 인원을 정하고 코드 소유자의 승인도 요구할 수 있다. 코드 소유자가 있는 코드는 그 소유자의 승인이 있어야 병합한다. 둘째, 새 커밋을 추가하면 기존 승인을 무효화하는 옵션이 있다. 검토한 내용과 달라지면 다시 승인받게 하는 것이다. 셋째, 한 번에 적용되는 규칙은 하나뿐이다. 여러 규칙이 겹치면 어느 것이 적용될지 알기 어려우므로, 규칙 세트로 이전하는 방법을 문서는 안내한다.

이 절의 근거 S33

머지 큐와 머지 트레인의 병합 검사

GitHub의 머지 큐는 변경이 자주 병합되는 브랜치에서 사용하는 기능이다. 필수 검사를 마친 제안을 큐에 넣고, 대상 브랜치의 최신 커밋과 큐에서 앞선 변경을 합친 상태로 다시 검사한다. GitHub Actions로 필수 검사를 구현했다면 워크플로에 merge_group 이벤트를 추가해야 한다. 빠뜨리면 검사 결과가 보고되지 않아 병합이 실패한다. 제삼자 CI는 gh-readonly-queue/로 시작하는 임시 브랜치에 푸시되는 커밋을 처리하도록 설정한다. 병합 방식, 동시 실행 범위, 묶음의 최소·최대 크기와 대기 시간, 검사 타임아웃도 설정할 수 있다.

GitLab의 머지 트레인은 같은 병합 충돌 문제를 다른 방식으로 처리한다. 각 제안을 그 앞에 선 모든 제안과 합친 상태로 검사하며, 검사 작업은 병렬로 실행된다. 앞선 제안이 제외되면 뒤따르는 검사 작업을 취소하고 남은 변경을 다시 합쳐 검사한다. 트레인은 유료 요금제의 기능이며, 긴급 수정을 위한 즉시 병합 선택이 따로 있지만 대기 중인 다른 변경과 함께 검사하지 않았으므로 오류가 생길 수 있다. 두 도구의 고정된 단계 수나 앞지르기 금지를 보편 동작으로 읽으면 안 된다. 그런 운영은 각 팀의 정책이다.

이 절의 근거 S34 · S35

가상 예시: 한 팀의 검토와 병합 절차

아래는 실행하지 않은 가상의 한 팀 예시이며, 이 팀이 정한 정책이지 보편 규칙이 아니다. 이 팀은 다음 순서로 변경을 검토한다. 먼저 이슈에 할 일과 완료 조건을 적는다. 이어서 명세에 기대 동작과 인수 기준, 이번 작업에 포함되는 범위를 적고 함께 읽는다. 중요한 설계 결정이 있으면 결정 기록을 Proposed(제안) 상태로 올리고 15분 동안 함께 읽으며 검토한다. 병합 전에는 설계의 방향을 한 번 살핀다. 풀 리퀘스트의 초안 상태를 해제해 정식 검토를 요청하고 코드 소유자의 승인을 받으며, 새 커밋에는 승인을 다시 받는다.

상태 검사를 통과하고 검토 대화를 해결해야 병합할 수 있게 설정한다. 변경이 자주 합쳐지는 기본 브랜치에는 머지 큐를 적용한다. 긴급 수정은 대기열 맨 앞으로 보내는 예외로만 다루며, 두 사람의 합의가 있을 때만 쓴다. 맨 앞으로 올리면 뒤에 선 항목들은 순서가 밀려 병합 결과 검사를 다시 돌리므로, 순서를 바꾼 이유는 팀의 예외 기록에 남긴다. 단계의 수와 순서, 예외의 조건은 모두 이 팀의 선택이다. 다른 팀은 다르게 정해도 되며, 다르게 정했다면 그 이유를 결정 기록에 남긴다.

실패 양상과 한계

검토와 병합 과정에서는 대기와 실행 중단이 문제가 된다. 큐가 길어지면 병합 대기 시간이 늘고, 검사 타임아웃이 너무 짧으면 정상적인 변경도 실패로 처리되며, 워크플로에 필요한 이벤트를 등록하지 않으면 검사가 보고되지 않아 줄이 멈춘다. 트레인에서는 앞선 제안이 실패하면 뒤의 파이프라인을 다시 생성하느라 자원을 쓴다.

자동 검사는 병합한 코드가 정해둔 조건을 충족하는지 확인한다. 설계 방향까지 타당한지는 기록과 사람의 검토로 판단해야 한다. 절차가 복잡해지면 이를 우회하려는 시도가 생길 수 있으므로, 예외를 허용할 조건을 미리 정해둔다.

이 절의 근거 S34 · S35

검토 절차의 효과 확인하기

풀 리퀘스트를 제출한 뒤 병합까지 걸린 시간, 각 검토 단계에서 통과하지 못한 비율과 이유, 중단된 큐의 수와 복구 시간, 병합 후 기본 브랜치에서 발생한 오류 수를 측정한다. 특히 병합 후 오류가 줄었는지는 전체 절차가 효과를 내는지 판단하는 기준이다. 단계만 늘고 오류가 줄지 않았다면 검토 절차를 다시 살펴야 한다.

기록이 실제로 쓰이는지도 확인한다. 결정 기록이 실제로 읽히는지, Superseded로 표시된 기록의 연결이 끊기지 않는지를 본다. 아무도 읽지 않는 기록은 검토에 도움을 주기 어렵다.

팀에 맞는 검토 절차 정하기

결정의 이유를 기록하고, 다른 변경과 합친 상태를 큐와 파이프라인에서 검사한다. 기록이 없으면 같은 논의를 반복하기 쉽고, 병합 결과를 확인하지 않으면 개별 검사에서 드러나지 않은 오류를 놓칠 수 있다.

검토 단계의 수와 순서는 팀의 정책에 맞춰 정한다. 변경에 따른 테스트 범위를 정하는 방법은 「도메인 경계와 영향 범위 CI」에서, 평가 기준과 결과의 해석은 「AI 평가」에서 이어서 살펴볼 수 있다.