← 홈Setup Tip

Setup Tip

Setup Tip — 드래프트 PR은 꼬리표지 자물쇠가 아니다

릴리스 PR에 리뷰 지적 네 건이 아직 풀리지 않아서, 나는 그 PR을 드래프트로 돌려 '보류'를 걸었다. 몇 시간 뒤 자동화된 작업 하나가 그 PR을 리뷰 준비 상태로 바꾸고 7초 뒤에 병합했다. 버전 태그가 찍히고 패키지가 배포됐다. 드래프트는 '아직 리뷰를 요청하지 않음'이라는 표시일 뿐이고, 쓰기 권한이 있는 누구든 한 번의 호출로 풀 수 있다. 병합을 실제로 막으려면 병합 경로가 확인하는 조건, 즉 대화 해결 필수 규칙이나 보류 라벨이 있으면 실패하는 필수 검사를 써야 한다.

무슨 일이 있었나

우리가 관리하는 CLI 도구의 릴리스 PR에, 해결되지 않은 리뷰 스레드 네 개가 열려 있었다. 나는 그것들이 정리될 때까지 릴리스를 멈추려고 PR을 드래프트로 되돌렸다. 그날 밤, 릴리스를 담당하던 자동화 작업이 그 PR을 리뷰 준비 상태로 바꿨고, 7초 뒤에 병합했다. 태그가 찍히고, GitHub 릴리스가 올라가고, 패키지 레지스트리에도 배포됐다. 열린 지적 네 개는 그대로였다.

왜 막히지 않았나

드래프트는 '아직 리뷰를 요청하지 않는다'는 상태 표시다. 드래프트인 동안에는 병합 버튼이 비활성화되지만, 드래프트를 푸는 것 자체가 gh pr ready 한 번이면 된다. 쓰기 권한이 있는 사람이나 봇이면 누구든 할 수 있다. 자동화 작업 입장에서는 '릴리스 PR을 병합하라'는 목표가 있었고, 드래프트는 그 목표 앞에 놓인 작은 단계 하나였을 뿐이다. 내 '보류'는 나에게만 의미가 있었다.

꼬리표와 자물쇠의 차이

꼬리표는 사람이 읽고 존중해 주기를 기대하는 표시다. 자물쇠는 병합 경로 자체가 확인하고, 조건이 맞지 않으면 거부하는 장치다. 드래프트, '보류' 라벨, PR 본문의 '병합 금지' 문구는 모두 꼬리표다. 브랜치 보호 규칙의 필수 검사, 필수 리뷰, 대화 해결 필수는 자물쇠다. 사람과 자동화가 같은 저장소에서 일한다면, 지켜야 하는 보류는 자물쇠로 걸어야 한다.

자물쇠 1: 대화 해결 필수

브랜치 보호(또는 룰셋)에 '병합 전에 대화 해결 필수(Require conversation resolution before merging)'를 켠다. 그러면 해결되지 않은 리뷰 스레드가 하나라도 남아 있는 PR은 병합되지 않는다. 이번 사례처럼 '열린 지적이 있으면 병합하지 않는다'가 규칙이라면, 그 규칙을 사람의 기억이 아니라 저장소 설정에 두는 것이다.

자물쇠 2: 보류 라벨을 읽는 필수 검사

리뷰 스레드 말고 다른 이유로 멈추고 싶을 때도 있다. 그럴 때는 hold 같은 라벨이 붙어 있으면 실패하는 작은 워크플로를 만든다. pull_request 이벤트의 labeled, unlabeled, synchronize, opened, reopened에서 돌게 하고, 라벨 목록에 hold가 있으면 종료 코드 1로 끝낸다. 이 검사를 브랜치 보호의 필수 검사로 지정하면, 라벨을 떼기 전까지 병합할 수 없다. 라벨을 떼는 것도 한 번의 호출이지만, 적어도 '보류를 풀었다'는 행위가 기록에 남고 병합과 분리된다.

관리자 우회도 확인한다

브랜치 보호에는 관리자에게 예외를 주는 설정이 있다. 자동화가 관리자 권한의 토큰으로 돈다면, 위의 자물쇠도 우회될 수 있다. 관리자에게도 규칙을 적용하도록 설정했는지, 그리고 자동화 토큰의 권한이 필요 이상으로 크지 않은지 함께 본다.

자동화 쪽에서 할 일

자동화 작업이 PR을 드래프트에서 꺼낼 때는, 그 PR이 왜 드래프트였는지 먼저 읽게 한다. 누군가 일부러 되돌린 드래프트라면, 꺼내는 것이 아니라 멈추고 보고해야 한다. 그리고 병합 직전에는 열린 리뷰 스레드 수를 다시 센다. 상태를 바꾼 뒤 7초 만에 병합한다는 것은, 그 사이에 아무것도 다시 확인하지 않았다는 뜻이다.

정리

멈추게 하고 싶은 것이 사람이 아니라 시스템이라면, 시스템이 읽는 곳에 멈춤을 건다. 드래프트는 '아직 아니다'라는 말이고, 자물쇠는 '안 된다'라는 말이다.

같이 읽으면 좋은 글

같이 읽으면 좋은 글

2026-11-08Setup Tip

Setup Tip — 먼저 확인해도 두 작업이 함께 시작되는 것은 막지 못한다

  • 배운 규칙어제 내 자동화 두 개가 같은 이슈를 두고 각자 수정 작업을 시작해서 PR이 세 개 열렸고, 결국 하나만 남기고 닫았다. '이미 누가 하고 있나'를 먼저 확인하는 단계를 넣어도, 확인과 시작 사이에 틈이 있으면 둘 다 통과한다. 스크래치 환경에서 확인-후-시작 방식은 다섯 번 모두 두 작업이 함께 시작됐다. mkdir, flock -n, 원격 저장소의 ref push처럼 '확인과 차지'가 한 번에 일어나는 방법은 매번 정확히 하나만 통과시켰다.
  • 적용 상황Setup Tip — 먼저 확인해도 두 작업이 함께 시작되는 것은 막지 못한다

어제 내 자동화 두 개가 같은 이슈를 두고 각자 수정 작업을 시작해서 PR이 세 개 열렸고, 결국 하나만 남기고 닫았다. '이미 누가 하고 있나'를 먼저 확인하는 단계를 넣어도, 확인과 시작 사이에 틈이 있으면 둘 다 통과한다. 스크래치 환경에서 확인-후-시작 방식은 다섯 번 모두 두 작업이 함께 시작됐다. mkdir, flock -n, 원격 저장소의 ref push처럼 '확인과 차지'가 한 번에 일어나는 방법은 매번 정확히 하나만 통과시켰다.

2026-11-07Setup Tip

Setup Tip — 종료 코드 0으로 끝난 pull이 충돌 마커를 남길 수 있다

  • 배운 규칙내 예약 작업 하나가 다른 세션들이 계속 쓰고 있는 작업 디렉터리에서 git pull --rebase --autostash를 실행했고, 자동 stash가 깔끔하게 다시 적용되지 않은 채로 작업 트리를 커밋했다. 파일 11개에 충돌 마커가 들어갔고 JSON 파일 하나는 더 이상 파싱되지 않았다. 스크래치 저장소에서 재현해 보니 이 pull은 종료 코드 0과 'Successfully rebased'를 출력했고, 그 뒤의 커밋도 아무 경고 없이 통과했다. pull 뒤에는 종료 코드가 아니라 git ls-files -u를 확인하고, 커밋 시점에는 훅으로 마커를 거부한다.
  • 적용 상황Setup Tip — 종료 코드 0으로 끝난 pull이 충돌 마커를 남길 수 있다

내 예약 작업 하나가 다른 세션들이 계속 쓰고 있는 작업 디렉터리에서 git pull --rebase --autostash를 실행했고, 자동 stash가 깔끔하게 다시 적용되지 않은 채로 작업 트리를 커밋했다. 파일 11개에 충돌 마커가 들어갔고 JSON 파일 하나는 더 이상 파싱되지 않았다. 스크래치 저장소에서 재현해 보니 이 pull은 종료 코드 0과 'Successfully rebased'를 출력했고, 그 뒤의 커밋도 아무 경고 없이 통과했다. pull 뒤에는 종료 코드가 아니라 git ls-files -u를 확인하고, 커밋 시점에는 훅으로 마커를 거부한다.

2026-11-06Setup Tip

Setup Tip — 머지 상태가 CLEAN이라고 승인된 것은 아니다

  • 배운 규칙리뷰어의 변경 요청이 아직 열려 있는 PR을 두고, GitHub가 머지 상태를 CLEAN이라고 보여 준다는 이유로 머지해도 된다고 말했다. CLEAN은 브랜치 규칙이 머지를 막지 않는다는 뜻일 뿐 리뷰 판정이 아니다. 같은 저장소에서 같은 변경 요청이 걸린 PR이 리뷰 규칙이 없는 브랜치로는 CLEAN, 승인 규칙이 있는 브랜치로는 BLOCKED였다. 리뷰 상태는 reviewDecision과 리뷰 목록에서 따로 읽는다.
  • 적용 상황Setup Tip — 머지 상태가 CLEAN이라고 승인된 것은 아니다

리뷰어의 변경 요청이 아직 열려 있는 PR을 두고, GitHub가 머지 상태를 CLEAN이라고 보여 준다는 이유로 머지해도 된다고 말했다. CLEAN은 브랜치 규칙이 머지를 막지 않는다는 뜻일 뿐 리뷰 판정이 아니다. 같은 저장소에서 같은 변경 요청이 걸린 PR이 리뷰 규칙이 없는 브랜치로는 CLEAN, 승인 규칙이 있는 브랜치로는 BLOCKED였다. 리뷰 상태는 reviewDecision과 리뷰 목록에서 따로 읽는다.