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

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

예시는 다음과 같습니다.

# Specify a default Code Owner for all files with a wildcard:
* @default-owner

# Specify multiple Code Owners to a specific file:
README.md @doc-team @tech-lead

# Specify a Code Owner to all files with a specific extension:
*.rb @ruby-owner

# Specify Code Owners with usernames or email addresses:
LICENSE @legal janedoe@gitlab.com

# Use group names to match groups and nested groups:
README @group @group/with-nested/subgroup

# Specify a Code Owner to a directory and all its contents:
/docs/ @all-docs
/docs/* @root-docs
/docs/**/*.md @markdown-docs  # Match specific file types in any subdirectory
/db/**/index.md @index-docs   # Match a specific file name in any subdirectory

# Use a section to group related rules:
[Documentation]
ee/docs    @docs
docs       @docs

# Assign a role as a 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와 선택적 섹션
• 일반 항목과 섹션
• 이름이 중복된 섹션

섹션 제목과 이름#

섹션 제목에는 이름이 있어야 합니다. 섹션 이름은 대소문자를 구분하지 않으며, 이름이 중복된 섹션은 하나로 합쳐집니다. 보호된 브랜치에 한해 섹션은 다음과 같이 설정할 수 있습니다.

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

예시는 다음과 같습니다.

# Required section
[Section name]

# Optional section
^[Section name]

# Section requiring 5 approvals
[Section name][5]

# Section with @username as default owner
[Section name] @username

# Section with @group and @subgroup as default owners and requiring 2 approvals
[Section name][2] @group @subgroup

섹션의 기본 Code Owner 설정#

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

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

예를 들면 다음과 같습니다.

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

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

이 예시에서는 다음과 같이 동작합니다.

• @docs-team은 Documentation 섹션의 모든 항목을 소유합니다.
• @database-team과 @agarcia는 Database 섹션의 모든 항목을 소유하지만, @docs-team에 할당하는 재정의가 있는 model/db/database-setup.md는 제외합니다.

섹션 안의 항목이 섹션 없는 항목을 재정의하지 않는 일반 항목과 섹션을 함께 사용하는 경우와 이 동작을 비교해 봅니다.

선택적 섹션#

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. 다음 패턴 중 하나를 따르는 텍스트를 입력합니다.

   # All direct group members as Code Owners for a file
   file.md @group-x
   
   # All direct subgroup members as Code Owners for a file
   file.md @group-x/subgroup-y
   
   # All direct group and direct subgroup members as Code Owners for a file
   file.md @group-x @group-x/subgroup-y
   

3. 파일을 저장합니다.

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

구성 예시#

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

이 예시에서는 다음과 같이 동작합니다.

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

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

  

• 머지 리퀘스트 승인 위젯에서도 같은 직접 멤버가 Maintainers로 나열됩니다.

  

문제가 발생하면 가능한 승인자로 표시되지 않는 사용자를 참고합니다.

경로 매칭#

경로는 절대 경로, 상대 경로, 디렉터리, 와일드카드 또는 globstar 형태로 지정할 수 있으며, 리포지터리 루트를 기준으로 일치 여부를 판단합니다.

절대 경로#

/로 시작하는 경로는 리포지터리 루트부터 일치시킵니다.

# Matches only README.md in the root.
/README.md

# Matches only README.md inside the /docs directory.
/docs/README.md

상대 경로#

앞에 /가 없는 경로는 globstar 경로로 처리됩니다.

# Matches /README.md, /internal/README.md, /app/lib/README.md
README.md @username

# Matches /internal/README.md, /docs/internal/README.md, /docs/api/internal/README.md
internal/README.md

디렉터리 경로#

디렉터리와 그 하위 디렉터리의 모든 파일을 일치시키려면 경로를 /로 끝냅니다.

# Matches all files in /docs/ and its subdirectories
/docs/

와일드카드 경로#

여러 문자를 일치시키려면 *를 사용합니다.

# Any markdown files in the docs directory
/docs/*.md @username

# /docs/index file of any filetype
# For example: /docs/index.md, /docs/index.html, /docs/index.xml
/docs/index.* @username

# Any file in the docs directory with 'spec' in the name.
# For example: /docs/qa_specs.rb, /docs/spec_helpers.rb, /docs/runtime.spec
/docs/*spec* @username

# README.md files one level deep within the docs directory
# For example: /docs/api/README.md
/docs/*/README.md @username

Globstar 경로#

여러 디렉터리 수준에 걸쳐 파일 또는 패턴을 일치시키려면 **를 사용합니다.

# For example: /docs/index.md, /docs/api/index.md, and /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 파일에만 영향을 줍니다.

# All files require approval from @username
* @username

# Except pom.xml which needs no approval
!pom.xml

[Ruby]
# All ruby files require approval from @ruby-team
*.rb @ruby-team

# Except Ruby files in the config directory
!/config/**/*.rb

제외 패턴이 동작하는 방식은 다음 지침으로 설명합니다.

• 제외는 해당 섹션 안에서 순서대로 평가됩니다. 예를 들면 다음과 같습니다.

  * @default-owner
  !*.rb                      # Excludes all Ruby files.
  /special/*.rb @ruby-owner  # This won't take effect as *.rb is already excluded.
  

• 한 번 제외된 패턴은 같은 섹션에서 다시 포함할 수 없습니다.

  [Ruby]
  *.rb @ruby-team           # All Ruby files need Ruby team approval.
  !/config/**/*.rb          # Ruby files in config don't need Ruby team approval.
  /config/routes.rb @ops    # This won't take effect as config Ruby files are excluded.
  

• 제외 패턴과 일치하는 파일은 해당 섹션에서 Code Owner 승인이 필요하지 않습니다. 소유자별로 다른 제외가 필요하면 여러 섹션을 사용합니다.

  [Ruby]
  *.rb @ruby-team
  !/config/**/*.rb        # Config Ruby files don't need Ruby team approval.
  
  [Config]
  /config/ @ops-team      # Config files still require ops-team approval.
  

• 자동으로 업데이트되는 파일에는 제외를 사용합니다.

  * @default-owner
  
  # Files updated by automation don't need approval.
  !package-lock.json
  !yarn.lock
  !**/generated/          # Any files in generated directories.
  !.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 문제 해결