Code Owners

코드 소유자 기능을 사용하여 프로젝트 코드베이스의 특정 부분에 전문 지식을 갖고 있는 사람을 정의합니다. 리포지터리의 파일 및 디렉터리의 소유자를 정의하여 다음을 수행할 수 있습니다.

• 소유자의 승인을 필요로 함. 보호된 브랜치와 코드 소유자를 결합하여 보호된 브랜치로의 Merge Request 승인을 전문가의 승인이 필요합니다.

• 소유자 식별. 코드 소유자의 이름은 소유하는 파일과 디렉터리에 표시됩니다:

  

Merge Request의 유연한 승인 워크플로를 구축하려면 코드 소유자를 Merge Request 승인 규칙 승인 규칙 (선택 사항 또는 필수) 와 결합하세요:

• 코드 소유자를 사용하여 품질을 보장하세요. 리포지터리의 특정 경로에 도메인 전문 지식을 갖고 있는 사용자를 정의하세요.
• 승인 규칙를 사용하여 리포지터리의 특정 파일 경로와 일치하지 않는 전문 지식 영역을 정의하세요. 승인 규칙을 사용하여 프론트엔드 개발자나 보안 팀과 같은 올바른 리뷰어 집합으로 Merge Request 작성자를 안내합니다.

예를 들어:

파일 또는 디렉터리의 코드 소유자 보기

파일 또는 디렉터리의 코드 소유자를 보려면:

1. 왼쪽 사이드바에서 검색 또는 이동을 선택하여 프로젝트를 찾습니다.
2. 코드 > 리포지터리를 선택합니다.
3. 보고 싶은 파일 또는 디렉터리로 이동합니다.
4. 선택 사항. 브랜치 또는 태그를 선택합니다.

GitLab은 페이지 상단에 코드 소유자를 표시합니다.

코드 소유자 설정

전제 조건:

• 기본 브랜치로 푸시하거나 Merge Request을 만들 수 있어야 합니다.

1. 선호하는 위치에 CODEOWNERS 파일을 만듭니다.
2. 코드 소유자 구문 참조를 따르는 파일에 몇 가지 규칙을 정의합니다. 몇 가지 제안:
   • 모든 자격이 있는 승인자 구성 승인 규칙 구성.
   • 보호된 브랜치에서 코드 소유자 승인 필요 구성.
3. 변경 사항을 커밋하고 GitLab에 푸시합니다.

CODEOWNERS 파일

CODEOWNERS 파일(확장명 없음)은 리포지터리의 특정 파일 및 디렉터리를 책임지는 사용자나 공유 그룹을 지정합니다.

각 리포지터리는 단일 CODEOWNERS 파일을 사용합니다. GitLab은 리포지터리의 이러한 위치에서 이 순서대로 검사합니다. 발견된 첫 번째 CODEOWNERS 파일이 사용되고 나머지는 모두 무시됩니다.

1. 루트 디렉터리에: ./CODEOWNERS.
2. docs 디렉터리에: ./docs/CODEOWNERS.
3. .gitlab 디렉터리에: ./.gitlab/CODEOWNERS.

더 많은 정보는 코드 소유자 구문 및 오류 처리를 참조하세요.

사용자 또는 그룹 이름이 변경된 경우

사용자 또는 그룹 이름이 변경되면 CODEOWNERS는 새 이름으로 자동으로 업데이트되지 않습니다. 새 이름을 입력하려면 파일을 편집해야 합니다.

SAML SSO를 사용하는 조직은 사용자 이름을 설정하여 사용자가 자신의 사용자 이름을 변경할 수 없도록 할 수 있습니다.

그룹을 코드 소유자로 추가

그룹이나 서브그룹의 구성원을 코드 소유자로 설정하려면:

CODEOWNERS 파일에 다음 중 하나의 패턴을 따르는 텍스트를 입력합니다:

# 파일에 대한 모든 그룹 구성원을 코드 소유자로 설정
file.md @group-x

# 파일에 대한 모든 서브그룹 구성원을 코드 소유자로 설정
file.md @group-x/subgroup-y

# 파일에 대한 모든 그룹 및 서브그룹 구성원을 코드 소유자로 설정
file.md @group-x @group-x/subgroup-y

그룹 상속 및 자격

이 예에서:

• 부모 그룹 X(group-x)은 프로젝트 A를 소유합니다.
• 부모 그룹 X는 서브그룹인 서브그룹 Y도 포함합니다.(group-x/subgroup-y)
• 서브그룹 Y는 프로젝트 B를 소유합니다.

자격이 있는 코드 소유자는 다음과 같습니다:

• 프로젝트 A: 그룹 X의 구성원만 가능합니다. 왜냐하면 프로젝트 A는 서브그룹 Y에 속하지 않기 때문입니다.
• 프로젝트 B: 그룹 X와 서브그룹 Y의 구성원이 모두 가능합니다.

부모 그룹에서 프로젝트의 서브그룹 초대

당신은 서브그룹 Y를 프로젝트 A에 초대하여 그들의 구성원도 코드 소유자가 되도록 할 수 있습니다.

만약 당신이 서브그룹 Y를 프로젝트 A에 초대하지 않지만, 그들을 코드 소유자로 만들면, 그들이 Merge Request의 승인을 선택사항으로 만듭니다.

부모 그룹에 서브그룹 초대

프로젝트 A의 부모 그룹에 서브그룹 Y를 초대하는 것은 지원되지 않습니다. 서브그룹 Y를 코드 소유자로 설정하려면 이 그룹을 프로젝트에 직접 초대하십시오.

보다 구체적으로 정의된 파일 또는 디렉터리의 소유자 정의

CODEOWNERS 파일에서 파일 또는 디렉터리가 여러 항목과 일치하는 경우, 파일이나 디렉터리에 마지막으로 일치하는 항목의 사용자가 사용됩니다. 이렇게 함으로써 합리적인 방식으로 항목을 정의하여 보다 구체적으로 정의된 파일 또는 디렉터리의 소유자를 정의할 수 있습니다.

예를 들어, 다음과 같은 CODEOWNERS 파일에서:

# 이 줄은 파일 terms.md와 일치합니다.
*.md @doc-team

# 이 줄도 파일 terms.md와 일치합니다.
terms.md @legal-team

terms.md의 코드 소유자는 @legal-team입니다.

섹션을 사용하는 경우, 각 섹션의 파일이나 디렉터리에 대해 마지막으로 일치하는 항목이 사용됩니다. 예를 들어, 섹션을 사용하는 CODEOWNERS 파일의 경우:

[README 소유자]
README.md @user1 @user2
internal/README.md @user4

[README 기타 소유자]
README.md @user3

루트 디렉터리의 README.md의 코드 소유자는 @user1, @user2, 그리고 @user3입니다. internal/README.md의 코드 소유자는 @user4와 @user3입니다.

각 섹션당 하나의 CODEOWNERS 패턴이 파일 경로에 일치됩니다.

섹션으로 코드 소유자를 구성하기

섹션에 이름을 지정하여 코드 소유자를 구성할 수 있습니다.

공동 디렉터리에 대해 섹션을 사용하여 여러 팀이 리뷰어가 될 수 있도록 할 수 있습니다.

CODEOWNERS 파일에 섹션 이름을 대괄호로 묶은 다음, 파일이나 디렉터리와 사용자, 그룹 또는 서브그룹을 입력하면 됩니다.

[README 소유자]
README.md @user1 @user2
internal/README.md @user2

Merge Request 위젯의 각 코드 소유자는 라벨 아래에 나열됩니다. 다음 이미지는 그룹 및 문서 섹션을 보여줍니다:

섹션에 대한 기본 소유자 설정

• GitLab 15.11에서 도입됨 (기본적으로 비활성화된) codeowners_default_owners라는 플래그와 함께.
• GitLab 15.11에서 일반적으로 사용 가능함. 피처 플래그 codeowners_default_owners가 제거되었습니다.

섹션 내에서 여러 파일 경로가 같은 소유권을 공유하는 경우, 섹션에 대한 기본적인 코드 소유자를 정의합니다. 해당 섹션의 모든 경로는 이 기본값을 상속받으며, 해당 섹션의 기본값을 특정 라인에서 재정의하지 않는 한 기본 소유자가 적용됩니다.

기본 소유자는 파일 경로에 대해 특정 소유자가 지정되지 않은 경우에 적용됩니다. 파일 경로 옆에 특정한 소유자가 정의되면 기본 소유자는 무시됩니다.

예를 들어:

[문서] @docs-team
docs/
README.md

[데이터베이스] @database-team @agarcia
model/db/
config/db/database-setup.md @docs-team

이 예제에서:

• @docs-team은 문서 섹션의 모든 항목을 소유합니다.
• @database-team과 @agarcia는 데이터베이스 섹션의 모든 항목을 소유하며 config/db/database-setup.md는 @docs-team으로 재할당됩니다.

이러한 동작은 일반 항목과 섹션을 함께 사용할 때와 비교할 수 있으며, 섹션이 없는 항목은 섹션이 없는 항목과는 달리 섹션의 항목을 재정의하지 않습니다.

기본 소유자와 선택적 섹션을 함께 사용하기

기본 소유자 구문을 선택적 섹션과 필수 승인과 함께 사용하려면 기본 소유자를 끝에 두세요:

[문서][2] @docs-team
docs/
README.md

^[데이터베이스] @database-team
model/db/
config/db/database-setup.md @docs-team

일반 항목과 섹션을 함께 사용하기

섹션 바깥에 있는 경로에 대한 기본 코드 소유자를 설정하면 항상 승인이 필요합니다. 이러한 항목은 섹션이 없으면 항상 필요한 것으로 간주됩니다. 섹션이 없는 항목은 또 다른 섹션인것처럼 취급됩니다:

# 모든 파일에 대해 필요함
* @general-approvers

[문서] @docs-team
docs/
README.md
*.txt

[데이터베이스] @database-team
model/db/
config/db/database-setup.md @docs-team

이 예제에서:

• @general-approvers는 어디서나 모든 항목을 소유하며 재정의되지 않습니다.
• @docs-team은 문서 섹션의 모든 항목을 소유합니다.
• @database-team은 데이터베이스 섹션의 모든 항목을 소유하며 config/db/database-setup.md는 @docs-team으로 재할당됩니다.
• model/db/CHANGELOG.txt를 수정하는 Merge Request은 @general-approvers, @docs-team, @database-team 그룹 각각으로부터 세 가지 승인이 필요합니다.

이러한 동작은 섹션의 기본 소유자만 사용할 때와 비교할 수 있으며, 섹션의 특정 항목이 섹션 기본값을 재정의합니다.

이름이 중복된 섹션들

동일한 이름을 가진 여러 섹션을 결합합니다. 또한 섹션 제목은 대소문자를 구분하지 않습니다. 예를 들어:

[문서]
ee/docs/    @docs
docs/       @docs

[데이터베이스]
README.md  @database
model/db/   @database

[DOCUMENTATION]
README.md  @docs

이 코드는 문서 섹션 헤더 아래에 세 항목을, 데이터베이스 아래에 두 항목을 결과로 가집니다. 문서 및 DOCUMENTATION 섹션 아래에 정의된 항목은 첫 번째 섹션의 대소문자를 따릅니다.

코드 소유자 섹션을 선택적으로 만들기

코드 소유자 파일에서 선택적 섹션을 지정할 수 있습니다. 선택적 섹션을 사용하면 코드베이스의 여러 부분에 대한 책임을 지정할 수 있지만, 해당 부분에 대한 강력한 검토가 필요하지는 않습니다. 이 접근 방식은 빈번하게 업데이트되지만 엄격한 검토가 필요하지 않은 프로젝트 부분에 대해 더 유연한 정책을 제공합니다.

전체 섹션을 선택적으로 취급하려면 섹션 이름 앞에 캐럿 ^ 문자를 붙이세요.

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

[문서]
*.md @root

[Ruby]
*.rb @root

^[Go]
*.go @root

선택적인 코드 소유자 섹션은 설명 아래의 Merge Request 위젯에 표시됩니다:

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

CODEOWNERS 파일에서 선택적 섹션은 통합 요청을 사용하여 제출되는 경우에만 선택적입니다. 특정 브랜치로 직접 제출되는 경우에는 코드 소유자의 승인이 필요하며 선택적인 섹션이 있는지 여부에 상관없이 코드 소유자로부터의 승인이 필요합니다.

코드 소유자로부터 다중 승인 필요

• GitLab 15.9에서 도입되었습니다.

Merge Request의 승인 영역에서 코드 소유자 섹션에 대해 다중 승인을 요청할 수 있습니다. 섹션 이름 뒤에 [n]과 같은 숫자를 붙여야 하며, 예를 들어 [2] 또는 [3]과 같이 하면 됩니다. 이렇게 하면 해당 섹션의 코드 소유자로부터 n개의 승인이 필요합니다. n에 대한 유효한 값은 ≥ 1인 정수입니다. [1]은 선택 사항입니다. 유효하지 않은 값은 1로 처리됩니다.

코드 소유자로부터 다중 승인을 요청하려면 다음을 수행합니다:

1. 왼쪽 사이드바에서 찾거나 이동을 선택하여 프로젝트를 찾습니다.
2. 설정 > 리포지터리를 선택합니다.
3. 보호된 브랜치를 확장합니다.
4. 기본 브랜치 옆의 토글을 켭니다.
5. CODEOWNERS 파일을 편집하여 다중 승인을 위한 규칙을 추가합니다.

예를 들어, [Documentation] 섹션에 두 개의 승인이 필요한 경우:

[Documentation][2]
*.md @tech-writer-team

[Ruby]
*.rb @dev-team

코드 소유자 섹션의 Documentation에서 두 개의 승인이 필요하다는 것이 표시됩니다:

푸시 허용

푸시 허용 권한을 가진 사용자는 자신의 변경 사항에 대한 Merge Request을 만들거나 변경 사항을 직접 브랜치에 푸시할 수 있습니다. 사용자가 Merge Request 프로세스를 거치지 않으면, 보호된 브랜치의 기능 및 Merge Request에 포함된 코드 소유자 승인도 적용되지 않습니다.

이 권한은 주로 자동화(내부 사용자) 및 릴리스 도구에 연결된 계정에 부여됩니다.

푸시 허용 권한이 없는 사용자의 모든 변경 사항은 반드시 Merge Request을 통해 라우팅되어야 합니다.

관련 주제

• 구문 참조
• 개발 가이드라인

문제 해결

코드 소유자와 작업 시 다음과 같은 문제가 발생할 수 있습니다.

코드 소유자 기능이 오류를 처리하는 방법에 대한 자세한 내용은 코드 소유자 참조를 참조하십시오.

승인이 선택 사항으로 표시됨

코드 소유자 승인 규칙이 선택 사항인 경우 다음 중 하나에 해당하는 경우입니다:

• 사용자 또는 그룹이 프로젝트의 구성원이 아닙니다. 코드 소유자는 상위 그룹에서 구성원을 상속받을 수 없습니다.
• 보호된 브랜치에서 코드 소유자 승인이 설정되지 않았습니다.
• 섹션이 선택 사항으로 표시되었습니다.
• 충돌로 인해 검토 가능한 코드 소유자가 다른 Merge Request 승인 설정과 충돌하여 Merge Request을 승인할 수 없는 경우입니다.

승인이 표시되지 않음

코드 소유자 승인 규칙은 Merge Request이 생성될 때만 업데이트됩니다. CODEOWNERS 파일을 업데이트하면 Merge Request을 닫고 새로 만들어야 합니다.

사용자가 승인자로 표시되지 않음

다음 중 하나에 해당하는 경우 사용자가 코드 소유자 Merge Request 승인 규칙의 승인자로 표시되지 않을 수 있습니다:

• 규칙으로 특정 사용자가 Merge Request을 승인하는 것을 방지합니다. 프로젝트의 Merge Request 승인 설정을 확인하십시오.
• 코드 소유자 그룹이 비공개로 표시되었으며, 현재 사용자가 해당 코드 소유자 그룹의 구성원이 아닙니다.
• 현재 사용자가 내부 코드 소유자 그룹의 권한이 없는 외부 사용자인 경우입니다.

승인 규칙이 유효하지 않음

다음과 같은 오류가 발생할 수 있습니다:

승인 규칙이 유효하지 않음.
GitLab은 이 규칙을 자동으로 승인하여 Merge Request을 차단 해제했습니다.

이 문제는 규칙이 프로젝트의 직접 구성원이 아닌 코드 소유자를 사용하는 경우에 발생합니다.

해결책은 해당 그룹 또는 사용자가 프로젝트에 초대되었는지 확인하는 것입니다.

사용자 또는 그룹이 디렉터리의 코드 소유자로 표시되지 않음

디렉터리를 보거나 수정하는 동안 구성된 규칙에 따라 사용자 또는 그룹이 예상대로 표시되지 않을 수 있습니다. 그러나 디렉터리 아래에 있는 파일들의 코드 소유자는 올바르게 표시됩니다.

예를 들어:

* @dev-team
docs/ @tech-writer-team

docs/ 디렉터리 아래에 있는 모든 파일들은 @tech-writer-team을 코드 소유자로 보여줍니다. 그러나 디렉터리 자체는 @dev-team을 표시합니다.

디렉터리를 보는 동안 이러한 동작이 발생하는 이유는 구문 규칙이 디렉터리 자체보다는 디렉터리 아래의 모든 파일들에 대해 적용되기 때문입니다. 이 문제를 해결하려면 CODEOWNERS 파일을 업데이트하여 디렉터리 자체와 디렉터리 아래에 있는 모든 파일을 명시적으로 포함하도록 합니다. 예를 들어:

* @dev-team
docs @tech-writer-team
docs/ @tech-writer-team