글로벌 오버라이드(Global Overrides) 소개: 조직 전체에 코드 리뷰 정책을 강제하는 방법
해당 블로그는 Konrad Sopala 원저자의 글 'Introducing Global Overrides'을 번역한 것입니다. 더 나은 이해를 위해서 약간의 의역이 반영되었습니다.
새로운 코드 리뷰 정책을 도입하셨다고 가정해 보겠습니다. 모든 SQL 파일에 적용되는 필수 경로 지시문을 추가했을 수도 있고, 인증(auth) 관련 코드에 더 엄격한 리뷰 프로파일을 적용하기로 결정했을 수도 있습니다. 이 정책을 문서로 정리하고, 슬랙으로 공지하고, 온보딩 자료에도 반영하셨을 겁니다.
그리고 3개월 뒤에 확인해 봅니다. 절반의 레포지토리만 정책을 적용하고 있고, 4분의 1은 자체적으로 변형된 버전을 쓰고 있으며, 나머지는 조용히 .coderabbit.yaml을 수정해서 정책에서 빠져나갔습니다.
조직을 관리해 본 분이라면 누구나 겪어 본 풍경입니다. "설정 표류(config drift)는 버그가 아닙니다. 수십 개의 팀이 각자 자신의 설정 파일을 소유할 때 자연스럽게 일어나는 현상입니다."
글로벌 오버라이드(Global Overrides)를 소개합니다
글로벌 오버라이드(Global Overrides)는 조직(organization) 관리자가 조직 내 모든 레포지토리와 모든 PR 리뷰에 대해 설정 값을 강제(enforce)할 수 있게 해 주는 기능입니다. 개별 레포지토리의 .coderabbit.yaml에 무엇이 적혀 있든, 레포 단위 UI 설정이 어떻게 되어 있든, 또는 다른 어디에 설정이 있든 상관없이 동일하게 적용됩니다.
설정 방법
- CodeRabbit UI에서 Organization Settings(조직 설정)를 엽니다.
- 좌측 사이드바 하단의 모드 스위처에서 Global Overrides를 선택합니다.
.coderabbit.yaml과 동일한 스키마의 YAML을 작성합니다. 강제하고 싶은 키만 포함하시면 됩니다.- 저장합니다.
저장한 오버라이드는 다음 PR 리뷰부터 조직 내 모든 레포지토리에 적용됩니다.
한 가지 짚고 넘어갈 점이 있습니다. YAML 에디터와는 달리, 글로벌 오버라이드 페이지는 정의된 모든 설정을 표시합니다. 기본값(default value)까지 함께 보여 주기 때문에, 지금 이 순간 정확히 무엇이 강제되고 있는지 한눈에 확인하실 수 있습니다.
오버라이드가 기존 설정과 만나면 어떻게 될까요
오버라이드가 기존 레포지토리 설정과 만나면 데이터 타입에 따라 세 가지 방식으로 처리됩니다.
- 객체(Objects): 깊은 병합(deep merge)이 일어납니다. 오버라이드 속성이 같은 이름의 속성을 각 중첩 단계에서 대체합니다.
- 배열(Arrays): 키 기반으로 병합됩니다. 키가 일치하면 오버라이드 항목이 우선하며(예:
path_instructions의path키), 다른 출처에 있는 고유 항목은 그대로 유지됩니다. - 스칼라(Scalars): 단순히 덮어씁니다.
세 가지 중에서는 배열이 가장 까다로우니 조금 더 자세히 살펴보겠습니다. 글로벌 오버라이드는 설정 상속(configuration inheritance)에서 사용하는 것과 동일한 키 기반 병합 방식을 사용합니다. 즉, 키가 일치하는 항목이 있으면 오버라이드 항목이 이깁니다. 그리고 레포지토리에만 존재하는 고유한 항목은 그대로 남습니다. 이 말은 곧, 오버라이드에서 더 짧은 배열을 정의한다고 해서 레포의 배열을 통째로 비워 버릴 수는 없다는 뜻입니다. 특정 항목을 교체하고 싶으시다면, 오버라이드의 항목 키가 기존 항목의 키와 일치해야 합니다.
배열 병합 동작이 어떻게 작동하는지 더 자세히 알고 싶으시다면 코드래빗(CodeRabbit) 설정 완벽 가이드에서 .coderabbit.yaml의 옵션 구조를 함께 보시면 이해가 쉽습니다.
누가 사용할 수 있나요
글로벌 오버라이드는 조직 관리자(organization admin)만 보거나 편집할 수 있습니다. "이 기능은 공유 기본값(shared defaults)을 위한 메커니즘이 아니라 강제(enforcement)를 위한 메커니즘입니다." 레포지토리에서 자유롭게 커스터마이징할 수 있는 공유 기본값이 필요하시다면 중앙 설정(central configuration)을 사용하셔야 합니다.
언제 써야 하고 언제 쓰지 말아야 할까요
글로벌 오버라이드는 "항상, 모든 곳에" 적용되어야 하는 정책을 위해 설계되었습니다. 다음과 같은 경우에 적합합니다.
- 컴플라이언스(compliance) 기반의 리뷰 프로파일
- 민감한 코드(SQL, 인증, 결제)에 대한 필수 경로 지시문(path instructions)
- 비활성화할 수 없는 필수 검사(required checks)
- 조직 차원에서 모든 곳에 적용을 보장해야 하는 보안 규칙
반대로, 일반적인 기본값(general defaults) 용도로는 적합하지 않습니다. 보통은 레포지토리가 따라야 하지만 가끔 다르게 설정해도 괜찮은 항목이라면, 조직 설정(organization settings)이나 중앙 설정에 두시는 게 맞습니다. 글로벌 오버라이드는 반드시, 항상, 모든 곳에 적용되어야 하는 항목만을 위해 남겨 두세요.
특히 보안과 관련된 강제 정책이 왜 중요한지 궁금하시다면 Vercel 침해 사고로 본 엔터프라이즈 코드 보안도 함께 읽어 보시길 추천드립니다. 코드 리뷰 단계에서 보안 정책이 일관되게 적용되지 않으면 어떤 결과로 이어질 수 있는지 잘 보여 줍니다.
사용해 보시기
조직 관리자이시라면 Organization Settings → Global Overrides로 이동하셔서 그동안 적용을 강제하고 싶으셨던 정책을 등록해 보시기 바랍니다. 1분이면 충분합니다. 다음 PR 리뷰부터 곧바로 반영됩니다.
자주 묻는 질문
Q. 글로벌 오버라이드와 중앙 설정(central configuration)은 무엇이 다른가요?
핵심 차이는 유연성을 허용할지 여부입니다. 중앙 설정은 조직 차원의 공유 기본값을 제공하지만, 각 레포지토리가 자신의 .coderabbit.yaml에서 자유롭게 덮어쓸 수 있습니다. 반면 글로벌 오버라이드는 레포지토리 설정을 덮어 누릅니다. 즉, 레포가 무엇을 적든 오버라이드가 우선합니다. 보통은 레포가 따라야 하지만 예외가 허용되는 정책은 중앙 설정에, 예외 없이 강제해야 하는 정책은 글로벌 오버라이드에 두시는 것을 추천드립니다.
Q. 글로벌 오버라이드를 적용하면 기존 .coderabbit.yaml은 무시되나요?
오버라이드에 명시된 키만 강제됩니다. 명시되지 않은 키는 기존처럼 레포의 .coderabbit.yaml이나 UI 설정을 따릅니다. 또한 객체는 깊은 병합, 배열은 키 기반 병합으로 처리되기 때문에, 레포의 고유 설정 중 오버라이드와 충돌하지 않는 부분은 그대로 살아남습니다.
Q. 배열에서 특정 항목만 강제하고 싶을 때 어떻게 해야 하나요?
배열 병합은 키 기준으로 동작합니다. 예를 들어 path_instructions 배열은 path 값이 키 역할을 합니다. 강제하고 싶은 항목과 동일한 path를 오버라이드에 적으시면 그 항목만 교체됩니다. 나머지 레포 고유 항목은 그대로 유지됩니다. 반대로, 레포의 배열을 비우고 싶다면 단순히 짧은 배열을 적는 걸로는 부족합니다. 키가 일치하는 항목을 정확히 작성해 주셔야 합니다.
Q. 누가 글로벌 오버라이드를 보거나 편집할 수 있나요?
조직 관리자(organization admin)만 가능합니다. 일반 멤버는 페이지 자체를 볼 수 없습니다. 강제(enforcement) 메커니즘이라는 성격상, 정책 결정 권한을 가진 사람만 다룰 수 있도록 의도된 설계입니다.
Q. 한국어 리뷰 설정도 글로벌 오버라이드로 강제할 수 있나요?
네, 가능합니다. language: ko처럼 단순한 스칼라 값도 오버라이드에 포함하시면 모든 레포지토리의 PR 리뷰가 한국어로 출력됩니다. 다만 한국어 리뷰는 보통 기본값에 가까운 항목이라, 일부 글로벌 팀이 영어 리뷰를 원할 가능성이 있다면 글로벌 오버라이드보다는 조직 설정 쪽에 두시는 편이 더 적합할 수 있습니다.
CodeRabbit의 다른 핵심 기능과 도입 가이드가 궁금하시다면 코드래빗(CodeRabbit) 소개와 2026 AI 코드 리뷰 도구 가이드도 함께 살펴보시면 좋습니다.