codeowners 이해하기
Source: Dev.to
CODEOWNERS 파일이란?
CODEOWNERS 파일은 GitHub 저장소에서 특정 디렉터리, 파일 또는 패턴에 대한 책임자를 자동으로 정의하는 특수 파일입니다.
Pull Request가 CODEOWNERS 규칙이 적용된 코드를 수정하면, 지정된 소유자가 해당 Pull Request의 필수 리뷰어로 자동 추가됩니다.
📍 위치
GitHub가 인식하려면 파일이 다음 위치 중 하나에 있어야 합니다:
.github/CODEOWNERS # 권장 위치
CODEOWNERS # 저장소 루트
docs/CODEOWNERS참고:
.github/CODEOWNERS위치가 선호되는 이유는 저장소 설정 파일들을 중앙에서 관리할 수 있기 때문입니다.
⚙️ 구문 및 동작 방식
기본 구조
각 행은 경로 패턴 뒤에 하나 이상의 소유자를 공백으로 구분하여 적습니다.
# CODEOWNERS 파일 예시
# 1. 저장소 전체 코드 (기본값)
* @octocat @github/support
# 2. 루트에 있는 .md 파일
*.md @docs-team
# 3. 'src/frontend/' 디렉터리와 그 하위 전체
src/frontend/ @frontend-lead
# 4. 특정 파일
config/database.yml @backend-admin
# 5. 하위 디렉터리 소유권 재정의
src/backend/users/ @user-management-team소유자 유형
- 개별 사용자: GitHub 핸들을 사용합니다. 예:
@octocat. - 팀: GitHub 팀 구문을 사용합니다. 예:
@organization/team-name. 팀을 사용하는 것이 권장되며, 팀 구성원이 바뀔 때 관리가 용이합니다.
우선순위 규칙
파일은 위에서 아래로 처리됩니다. 특정 경로에 대해 마지막에 매칭되는 패턴이 적용됩니다.
- 덜 구체적: 먼저 나타나거나 넓은 패턴을 사용하는 규칙.
- 더 구체적: 마지막에 나타나며 더 구체적인 경로를 사용하는 규칙으로, 이전 규칙을 덮어씁니다.
우선순위 예시:
# CODEOWNERS
# 10번째 라인 (덜 구체적):
src/models/* @data-team
# 50번째 라인 (더 구체적): 이 라인은 10번째 라인을 무시합니다
src/models/user.js @auth-squad이 경우 src/models/user.js를 수정하는 Pull Request는 @auth-squad의 리뷰만 요구하고, @data-team은 무시됩니다.
🛡️ 보호 브랜치와의 통합
CODEOWNERS의 진정한 힘은 GitHub 브랜치 보호 규칙과 연계될 때 발휘됩니다. 브랜치를 보호(main 또는 master 등)하면 “Require review from Code Owners” 옵션을 활성화할 수 있습니다.
CODEOWNERS 작업 흐름
- Pull Request 생성: 개발자가
src/billing/service.go와src/docs/README.md파일을 수정한 PR을 만들면, - 자동 할당: GitHub이 PR을 분석합니다:
src/billing/service.go는src/billing/* @billing-team과 매칭됩니다.src/docs/README.md는docs/*.md @documentation-team과 매칭됩니다.
- 필수 리뷰어: GitHub이
@billing-team과@documentation-team을 자동으로 필수 리뷰어에 추가합니다. - 병합: 각 소유 팀의 최소 한 명이 승인해야 PR을 병합할 수 있습니다.
💡 핵심 모범 사례
1. 개인이 아닌 팀 사용
소유자를 팀(@org/team-name)으로 지정하면 다음과 같은 장점이 있습니다.
- 개인이 휴가 중이거나 회사를 떠나도 리뷰가 중단되지 않음.
- 소유권과 지식이 기능 그룹 내에 고르게 분산됨.
2. 기본(Fallback) 규칙 정의
항상 넓은 범위의 규칙을 포함하세요. 예:
# 특정 할당이 없는 모든 파일에 대한 기본 소유자
* @organization/core-team이렇게 하면 어떤 변경도 리뷰 없이 넘어가지 않으며, 놓친 파일이나 경로에 대한 안전망을 제공합니다.
3. 파일 최신 상태 유지
CODEOWNERS 파일은 현재 팀 구조와 코드베이스를 반영해야 합니다. 프로젝트 구조 변경이나 팀 인원 변동 시 파일도 함께 업데이트해야 합니다. 이상적으로는 이 파일의 변경은 아키텍트나 기술 리더가 검토하도록 합니다.
4. 디렉터리 지정은 구체적으로
너무 넓은 매칭 규칙은 피하세요. 슬래시(/)를 사용해 디렉터리와 그 하위 전체를 지정합니다.
# 잘못된 예: 루트 디렉터리 파일에만 적용, 하위 디렉터리 제외
src/backend/*.js @js-team
# 올바른 예: 'src/backend/' 내부 모든 파일 및 하위 디렉터리 적용
src/backend/ @backend-team⚠️ CODEOWNERS의 주요 제한점: 경로 기반 경직성
GitHub 기본 CODEOWNERS 시스템은 “어떤 파일이 변경되었는가?” 라는 질문에만 답합니다. 이로 인해 다음과 같은 세 가지 중요한 문제점이 발생합니다.
-
병합 컨텍스트 부재
CODEOWNERS는 변경 대상 브랜치를 인식하지 못합니다. 예를 들어 PR이main에 향할 때만 아키텍트 리뷰를 요구하거나,hotfix가staging에만 향할 때 규칙을 완화할 수 없습니다. 즉, 대상 브랜치에 따라 리뷰어를 지정할 수 없습니다. -
교차 요구사항(AND/OR) 구현 불가
시스템은 조건을 결합할 수 없습니다. 하나의 규칙은 오직 경로가 일치할 때만 적용되므로 다음과 같은 논리를 구현할 수 없습니다:- AND: “파일이
src/auth/에 포함되고 라벨에security-review가 붙은 경우에만 보안 팀을 할당.” - OR: “보안 팀 또는 성능 팀 중 하나라도 해당 파일을 수정하면 할당한다.”
- AND: “파일이
-
(원본 텍스트가 여기서 잘려 있음)
Asignar al L… (texto truncado en la fuente original).