CODEOWNERS 파일은 소유권 규칙을 정의하는 문법을 사용합니다. 파일의 각 줄은 하나의 규칙을 나타내며, 파일 경로 패턴과 하나 이상의 소유자를 지정합니다. 주요 요소는 다음과 같습니다:

• 파일 경로: 특정 파일, 디렉토리, 또는 와일드카드.
• Code Owners: 사용자, 그룹, 또는 권한에 대한 멘션을 사용합니다.
• 코멘트: #으로 시작하는 줄은 무시됩니다. 인라인 코멘트는 지원되지 않습니다. 코멘트에 나열된 Code Owners는 파싱됩니다.
• 섹션: [Section name]을 사용하여 정의되는 선택적인 규칙 그룹.

몇 가지 예시:

# 와일드카드로 모든 파일에 기본 Code Owner 지정:
* @default-owner

# 특정 파일에 여러 Code Owner 지정:
README.md @doc-team @tech-lead

# 특정 확장자를 가진 모든 파일에 Code Owner 지정:
*.rb @ruby-owner

# 사용자 이름 또는 이메일 주소로 Code Owner 지정:
LICENSE @legal janedoe@gitlab.com

# 그룹 이름을 사용하여 그룹 및 중첩 그룹 매칭:
README @group @group/with-nested/subgroup

# 디렉토리와 모든 내용에 Code Owner 지정:
/docs/ @all-docs
/docs/* @root-docs
/docs/**/*.md @markdown-docs  # 모든 서브디렉토리의 특정 파일 유형 매칭
/db/**/index.md @index-docs   # 모든 서브디렉토리의 특정 파일 이름 매칭

# 섹션을 사용하여 관련 규칙 그룹화:
[Documentation]
ee/docs    @docs
docs       @docs

# 권한을 Code Owner로 할당:
/config/ @@maintainer

섹션#

CODEOWNERS 파일에서 섹션은 별도로 분석되고 항상 적용되는 명명된 영역입니다. 섹션을 정의하기 전까지 GitLab은 전체 CODEOWNERS 파일을 단일 섹션으로 처리합니다. 섹션을 더 추가하면 GitLab이 파일을 평가하는 방식이 변경됩니다:

• GitLab은 첫 번째 섹션 헤더 앞에 정의된 규칙을 포함하여 섹션 없는 항목을 또 다른 이름 없는 섹션처럼 처리합니다.
• 각 섹션은 규칙을 별도로 적용합니다.
• 파일 경로가 섹션의 여러 항목과 일치하는 경우, 해당 섹션의 마지막 일치 항목만 사용됩니다.
• 파일 경로가 여러 섹션의 항목과 일치하는 경우, 각 섹션의 마지막 일치 항목이 사용됩니다.

예를 들어, README 파일의 Code Owner를 정의하는 섹션이 있는 CODEOWNERS 파일에서:

* @admin

[README Owners]
README.md @user1 @user2
internal/README.md @user4

[README other owners]
README.md @user3

• 루트 디렉토리의 README.md에 대한 Code Owner는:
  • 이름 없는 섹션의 @admin.
  • [README Owners]의 @user1과 @user2.
  • [README other owners]의 @user3.
• internal/README.md에 대한 Code Owner는:
  • 이름 없는 섹션의 @admin.
  • [README Owners]의 @user4. 이 섹션에서 README.md와 internal/README.md 항목 모두 파일과 일치하지만 섹션의 마지막 일치 항목만 사용됩니다.
  • [README other owners]의 @user3.

CODEOWNERS 파일에 섹션을 추가하려면 대괄호 안에 섹션 이름을 입력하고, 그 다음에 파일 또는 디렉토리, 사용자, 그룹, 또는 서브그룹을 입력합니다:

[README Owners]
README.md @user1 @user2
internal/README.md @user2

머지 리퀘스트 위젯의 각 Code Owner는 레이블 아래에 나열됩니다. 다음 이미지는 Default, Frontend, Technical Writing 섹션을 보여줍니다:

섹션 구성 옵션에 대한 자세한 내용은 다음을 참조하세요:

• 기본 Code Owner 및 선택적 섹션
• 일반 항목과 섹션
• 중복 이름이 있는 섹션

섹션 제목 및 이름#

섹션 제목에는 이름이 있어야 합니다. 섹션 이름은 대소문자를 구분하지 않으며 중복 이름이 있는 섹션은 합쳐집니다. 보호된 브랜치에 한해:

• 승인을 요구할 수 있습니다(기본값).
• 선택적(^ 접두사)으로 설정할 수 있습니다.
• 특정 수의 승인을 요구할 수 있습니다. 자세한 내용은 그룹 상속 및 자격과 선택적으로 표시되는 승인을 참조하세요.
• 기본 소유자를 포함할 수 있습니다.

예시:

# 필수 섹션
[Section name]

# 선택적 섹션
^[Section name]

# 5개의 승인이 필요한 섹션
[Section name][5]

# @username을 기본 소유자로 하는 섹션
[Section name] @username

# @group과 @subgroup을 기본 소유자로 하고 2개의 승인이 필요한 섹션
[Section name][2] @group @subgroup

섹션의 기본 Code Owner 설정#

섹션 내의 여러 파일 경로가 동일한 소유권을 공유하는 경우, 섹션의 기본 Code Owner를 정의합니다. 해당 섹션의 모든 경로는 특정 줄에서 섹션 기본값을 재정의하지 않는 한 이 기본값을 상속합니다.

기본 소유자는 파일 경로에 특정 소유자가 지정되지 않은 경우 적용됩니다. 파일 경로 옆에 정의된 특정 소유자는 기본 소유자를 재정의합니다.

예를 들어:

[Documentation] @docs-team
docs/
README.md

[Database] @database-team @agarcia
model/db/
config/db/database-setup.md @docs-team

이 예시에서:

• @docs-team은 Documentation 섹션의 모든 항목을 소유합니다.
• @database-team과 @agarcia는 @docs-team에 재정의 할당된 config/db/database-setup.md를 제외하고 Database 섹션의 모든 항목을 소유합니다.

섹션에서 항목이 섹션 없는 항목을 재정의하지 않는 일반 항목과 섹션을 함께 사용하는 것과 이 동작을 비교하세요.

선택적 섹션#

Code Owners 파일에서 선택적 섹션을 지정할 수 있습니다. 선택적 섹션을 사용하면 코드베이스의 다양한 부분에 담당자를 지정하되 승인을 요구하지 않을 수 있습니다. 이 접근 방식은 자주 업데이트되지만 엄격한 리뷰가 필요하지 않은 프로젝트 부분에 더 완화된 정책을 제공합니다.

전체 섹션을 선택적으로 처리하려면 섹션 이름 앞에 캐럿(^) 문자를 추가합니다.

이 예시에서 [Go] 섹션은 선택적입니다:

[Documentation]
*.md @root

[Ruby]
*.rb @root

^[Go]
*.go @root

선택적 Code Owners 섹션은 설명 아래 머지 리퀘스트에 표시됩니다:

섹션이 파일에서 중복되고 하나는 선택적으로 표시되고 다른 하나는 표시되지 않은 경우, 해당 섹션은 필수입니다.

CODEOWNERS 파일의 선택적 섹션은 머지 리퀘스트를 사용하여 변경이 제출된 경우에만 선택적으로 처리됩니다. 변경이 보호된 브랜치에 직접 제출된 경우 섹션이 선택적으로 표시되어 있더라도 Code Owners의 승인이 여전히 필요합니다.

적격 Code Owner#

적격성 규칙은 유효한 Code Owner가 될 수 있는 사람을 결정합니다. CODEOWNERS 파일의 참조 방법(사용자 이름, 그룹, 또는 권한)에 따라 특정 규칙이 적용됩니다.

사용자 적격성#

사용자 이름(@username)으로 참조된 사용자가 Code Owner로 적격이 되려면 프로젝트에 대한 권한이 있어야 합니다. 다음 규칙이 적용됩니다:

• 프로젝트 및 그룹 가시성 설정은 적격성에 영향을 미치지 않습니다.
• 그룹에서 차단된 사용자는 Code Owner가 될 수 없습니다.
• 적격 사용자는 다음을 포함합니다:
  • Developer, Maintainer, 또는 Owner 권한으로 프로젝트에 직접 멤버십이 있는 사용자.
  • 프로젝트의 그룹에 멤버십이 있는 사용자(직접 또는 상속).
  • 프로젝트 그룹의 상위 그룹에 멤버십이 있는 사용자.
  • 프로젝트에 초대된 그룹에 직접 또는 상속 멤버십이 있는 사용자.
  • 프로젝트 그룹에 초대된 그룹에 직접(상속 제외) 멤버십이 있는 사용자.
  • 프로젝트 그룹의 상위 그룹에 초대된 그룹에 직접(상속 제외) 멤버십이 있는 사용자.

그룹 적격성#

그룹 이름(@group_name) 또는 중첩 그룹 이름(@nested/group/names)으로 그룹을 참조할 때 다음 규칙이 적용됩니다:

• 그룹 가시성 설정은 적격성에 영향을 미치지 않습니다.
• 참조된 그룹의 직접 멤버만 적격합니다. 상속된 멤버는 포함되지 않습니다.
• 적격 그룹은 다음을 포함합니다:
  • 프로젝트의 그룹.
  • 프로젝트 그룹의 상위 그룹.
  • Developer, Maintainer, 또는 Owner 권한으로 프로젝트에 직접 초대된 그룹.
  • 프로젝트의 그룹 또는 그 상위 그룹과 공유된 그룹. 공유된 그룹은 상위 그룹에서 Developer, Maintainer, 또는 Owner 권한을 가져야 합니다. 자세한 내용은 상위 그룹과 공유된 그룹을 참조하세요.

권한 적격성#

권한(@@role)을 참조할 때 다음 규칙이 적용됩니다:

• Developer, Maintainer, Owner 권한만 Code Owner로 사용할 수 있습니다.
• 지정된 권한을 가진 직접 프로젝트 멤버만 적격합니다.
• 권한은 상위 권한을 포함하지 않습니다. 예를 들어, @@developer를 지정해도 Maintainer 또는 Owner 권한을 가진 사용자는 포함되지 않습니다.

그룹 상속 및 적격성과 관련된 더 복잡한 시나리오에 대해서는 그룹 상속 및 적격성을 참조하세요.

권한을 Code Owner로 추가#

히스토리

• GitLab 17.7에서 codeowner_role_approvers라는 플래그와 함께 도입되었습니다.
• GitLab 17.8에서 GitLab.com에서 활성화되었습니다.
• GitLab 17.9에서 일반 제공됩니다. 기능 플래그 codeowner_role_approvers가 제거됩니다.

직접 프로젝트 멤버에 대한 권한을 Code Owner로 추가하거나 설정할 수 있습니다:

• @@ 접두사를 사용하여 권한을 설정합니다.
• Developer, Maintainer, Owner 권한만 사용 가능합니다.
• 권한은 상위 권한을 포함하지 않습니다. 예를 들어, @@developer를 지정해도 Maintainer 또는 Owner 권한을 가진 사용자는 포함되지 않습니다.
• 지정된 권한을 가진 직접 프로젝트 멤버만 적격 Code Owner입니다.
• 복수 권한을 지정할 수 있습니다. 예를 들어, @@developers는 허용됩니다.

다음 예시는 Developer 또는 Maintainer 권한을 가진 모든 직접 프로젝트 멤버를 file.md의 Code Owner로 설정합니다:

1. CODEOWNERS 파일을 엽니다.

2. 다음 패턴을 사용하여 줄을 추가합니다:

   file.md @@developer @@maintainer
   

3. 파일을 저장합니다.

4. 변경사항을 커밋하고 머지합니다.

그룹을 Code Owner로 추가#

그룹 또는 서브그룹의 직접 멤버를 Code Owner로 설정할 수 있습니다. 그룹 멤버십에 대한 자세한 내용은 멤버십 유형을 참조하세요.

필수 조건:

• 그룹이 프로젝트에 초대되어야 합니다.

그룹 또는 서브그룹의 직접 멤버를 Code Owner로 설정하려면:

1. CODEOWNERS 파일을 엽니다.

2. 다음 패턴 중 하나를 따르는 텍스트를 입력합니다:

   # 파일에 대한 Code Owner로서 모든 직접 그룹 멤버
   file.md @group-x
   
   # 파일에 대한 Code Owner로서 모든 직접 서브그룹 멤버
   file.md @group-x/subgroup-y
   
   # 파일에 대한 Code Owner로서 모든 직접 그룹 및 직접 서브그룹 멤버
   file.md @group-x @group-x/subgroup-y
   

3. 파일을 저장합니다.

4. 변경사항을 커밋하고 머지합니다.

구성 예시#

[Maintainers]
* @gitlab-org/maintainers/group-name

이 예시에서:

• group-name 그룹은 [Maintainers] 섹션 아래에 나열됩니다.

• group-name에는 다음 직접 멤버가 포함됩니다:

  

• 머지 리퀘스트 승인 위젯에서 동일한 직접 멤버들이 Maintainers로 나열됩니다:

  

문제가 발생하면 가능한 승인자로 표시되지 않는 사용자를 참조하세요.

경로 매칭#

경로는 절대, 상대, 디렉토리, 와일드카드, 또는 globstar일 수 있으며 리포지터리 루트에 대해 매칭됩니다.

절대 경로#

/로 시작하는 경로는 리포지터리 루트에서 매칭됩니다:

# 루트의 README.md만 매칭.
/README.md

# /docs 디렉토리 내의 README.md만 매칭.
/docs/README.md

상대 경로#

선행 /가 없는 경로는 globstar 경로로 처리됩니다:

# /README.md, /internal/README.md, /app/lib/README.md 매칭
README.md @username

# /internal/README.md, /docs/internal/README.md, /docs/api/internal/README.md 매칭
internal/README.md

디렉토리 경로#

경로 끝에 /를 추가하면 디렉토리와 그 서브디렉토리의 모든 파일과 매칭됩니다:

# /docs/와 그 서브디렉토리의 모든 파일 매칭
/docs/

와일드카드 경로#

*를 사용하여 여러 문자와 매칭합니다:

# docs 디렉토리의 모든 마크다운 파일
/docs/*.md @username

# /docs/index 파일의 모든 파일 유형
# 예: /docs/index.md, /docs/index.html, /docs/index.xml
/docs/index.* @username

# docs 디렉토리에서 이름에 'spec'이 포함된 모든 파일.
# 예: /docs/qa_specs.rb, /docs/spec_helpers.rb, /docs/runtime.spec
/docs/*spec* @username

# docs 디렉토리 한 수준 깊이의 README.md 파일
# 예: /docs/api/README.md
/docs/*/README.md @username

Globstar 경로#

**를 사용하여 여러 디렉토리 수준에 걸쳐 파일이나 패턴과 매칭합니다:

# 예: /docs/index.md, /docs/api/index.md, /docs/api/graphql/index.md.
/docs/**/index.md

디렉토리의 모든 파일과 매칭하려면 디렉토리 경로에 후행 슬래시(/)를 사용합니다.

제외 패턴#

히스토리

• GitLab 17.10에서 codeowners_file_exclusions라는 플래그와 함께 도입되었습니다.
• GitLab 17.10에서 GitLab.com에서 활성화되었습니다.
• GitLab 17.11에서 일반 제공됩니다. 기능 플래그 codeowners_file_exclusions가 제거됩니다.

파일 또는 경로 앞에 !를 추가하여 Code Owner 승인 요건에서 면제하거나 제외합니다. 제외는 해당 섹션에 적용됩니다. 다음 예시에서:

• pom.xml 제외는 기본 섹션에 적용됩니다.
• /config/**/*.rb 제외는 Ruby 섹션의 Ruby 파일에만 영향을 미칩니다.

# 모든 파일은 @username의 승인이 필요
* @username

# pom.xml은 승인이 필요 없음
!pom.xml

[Ruby]
# 모든 ruby 파일은 @ruby-team의 승인이 필요
*.rb @ruby-team

# config 디렉토리의 Ruby 파일은 제외
!/config/**/*.rb

다음 가이드라인은 제외 패턴이 작동하는 방식을 설명합니다:

• 제외는 섹션 내에서 순서대로 평가됩니다. 예를 들어:

  * @default-owner
  !*.rb                      # 모든 Ruby 파일 제외.
  /special/*.rb @ruby-owner  # *.rb가 이미 제외되었으므로 효과가 없음.
  

• 패턴이 제외된 후 동일한 섹션에서 다시 포함할 수 없습니다:

  [Ruby]
  *.rb @ruby-team           # 모든 Ruby 파일에 Ruby 팀 승인 필요.
  !/config/**/*.rb          # config의 Ruby 파일은 Ruby 팀 승인 불필요.
  /config/routes.rb @ops    # config Ruby 파일이 제외되었으므로 효과가 없음.
  

• 제외 패턴과 일치하는 파일은 해당 섹션에 대해 Code Owner 승인이 필요하지 않습니다. 다른 소유자에 대해 다른 제외가 필요한 경우 여러 섹션을 사용하세요:

  [Ruby]
  *.rb @ruby-team
  !/config/**/*.rb        # Config Ruby 파일은 Ruby 팀 승인 불필요.
  
  [Config]
  /config/ @ops-team      # Config 파일은 ops-team 승인 여전히 필요.
  

• 자동으로 업데이트되는 파일에 제외를 사용하세요:

  * @default-owner
  
  # 자동화로 업데이트된 파일은 승인 불필요.
  !package-lock.json
  !yarn.lock
  !**/generated/          # generated 디렉토리의 모든 파일.
  !.gitlab-ci.yml
  

항목 소유자#

항목은 하나 이상의 소유자를 가져야 합니다. 그룹, 서브그룹, 사용자가 될 수 있습니다.

/path/to/entry.rb @group
/path/to/entry.rb @group/subgroup
/path/to/entry.rb @user
/path/to/entry.rb @group @group/subgroup @user

그룹을 Code Owner로 추가하는 방법에 대한 자세한 내용은 그룹을 Code Owner로 추가를 참조하세요.

관련 항목#

• Code Owners
• 고급 CODEOWNERS 구성
• 머지 리퀘스트 승인
• 보호된 브랜치
• Code Owners 트러블슈팅