보호된 브랜치

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-Managed, GitLab Dedicated

GitLab에서는 권한이 기본적으로 리포지터리 및 브랜치에 대한 읽기 또는 쓰기 권한을 중심으로 정의됩니다. 특정 브랜치에 더 많은 제한을 부여하려면 그 브랜치를 보호할 수 있습니다.

보호된 브랜치는 다음을 제어합니다.

  • 어떤 사용자가 브랜치를 Merge할 수 있는지.
  • 어떤 사용자가 브랜치로 푸시할 수 있는지.
  • 사용자가 브랜치로 강제 푸시할 수 있는지.
  • CODEOWNERS 파일에 나열된 파일의 변경 사항을 직접 브랜치로 푸시할 수 있는지.
  • 브랜치의 해제를 할 수 있는 사용자.
  • 커밋 API를 통해 브랜치를 수정할 수 있는 사용자.

리포지터리의 기본 브랜치는 기본적으로 보호됩니다.

보호된 브랜치를 수정할 수 있는 사용자

  • GitLab 16.0에서 브랜치 푸시 권한이 변경되어 GitLab 관리자도 allowed 권한이 있어야 합니다.

브랜치가 보호되면 기본 동작은 해당 브랜치에 대한 이러한 제한을 강제합니다.

동작 수행 가능한 사용자
브랜치 보호 적어도 관리자(Maintainer) 역할
브랜치로 푸시 허용됨(Allowed) 권한을 가진 누구든지. (1)
브랜치로 강제 푸시 아무도 불가. (3)
브랜치 삭제 아무도 불가. (2)
  1. 개발자 역할을 가진 사용자는 그룹 내에서 프로젝트를 만들 수 있지만, 초기에 기본 브랜치로 푸시할 수 없을 수 있습니다.
  2. Git 명령을 사용하여 보호된 브랜치를 삭제할 수 없지만, 적어도 관리자 역할을 가진 사용자는 UI 또는 API를 통해 보호된 브랜치를 삭제할 수 있습니다.
  3. group_protected_branches 피처 플래그가 활성화된 경우 및 동일한 브랜치가 그룹 및 프로젝트 레벨에서 모두 보호된 경우, 프로젝트 레벨에서 구성된 강제 푸시 설정은 무시됩니다. 다른 모든 보호 설정은 여전히 프로젝트 레벨 설정을 사용합니다.

Merge Request 승인 정책을 실행하여 보호된 브랜치의 해제나 삭제를 방지할 수 있습니다.

브랜치가 여러 규칙과 일치하는 경우

브랜치가 여러 규칙과 일치하는 경우 가장 관대한 규칙이 브랜치의 보호 수준을 결정합니다. 예를 들어 다음과 같은 규칙을 고려해 보세요. 이 규칙에는 와일드카드가 포함되어 있습니다.

브랜치 이름 패턴 Merge 허용 대상 푸시 및 Merge 허용 대상
v1.x 관리자(Maintainer) 관리자(Maintainer)
v1.* 관리자(Maintainer) + 개발자(Developer) 관리자(Maintainer)
v* 아무도 아무도

v1.x라는 브랜치는 v1.x, v1.*, v*의 세 브랜치 이름 패턴에 대소문자를 구분하여 일치합니다. 가장 관대한 옵션이 동작을 결정하므로, v1.x 브랜치의 권한은 다음과 같습니다.

  • Merge 허용: 세 가지 설정 중 Maintainer + Developer가 가장 관대하며 결과적으로 브랜치 동작을 제어합니다. 더 엄격한 권한을 가진 v1.x와 v*에도 불구하고, 개발자 역할을 가진 사용자는 브랜치로 Merge할 수 있습니다.
  • 푸시 및 Merge 허용: 세 가지 설정 중 Maintainer가 가장 관대하며 결과적으로 브랜치 동작을 제어합니다. v*와 일치하는 브랜치가 아무도로 설정되어 있더라도 v1.x 또는 v1.*와 일치하는 브랜치는 더 관대한 Maintainer 권한을 받습니다.

특정 규칙이 브랜치의 동작을 제어하기를 원한다면, 일치하는 모든 다른 패턴은 더 적거나 같은 규칙을 적용해야 합니다.

아무도가 v1.x 브랜치로 푸시할 수 있도록 하려면, v1.x에 일치하는 모든 패턴은 다음과 같이 푸시 및 Merge 허용을 아무도로 설정해야 합니다.

브랜치 이름 패턴 Merge 허용 대상 푸시 및 Merge 허용 대상
v1.x 관리자(Maintainer) 아무도
v1.* 관리자(Maintainer) + 개발자(Developer) 아무도
v* 아무도 아무도

기본 브랜치 보호 수준 설정

관리자는 관리 영역에서 기본 브랜치 보호 수준을 설정할 수 있습니다.

기존 브랜치에 보호 추가

그룹 내의 모든 프로젝트 또는 특정 프로젝트에 대해 보호된 브랜치를 구성할 수 있습니다.

특정 프로젝트에 대해

전제 조건:

  • 적어도 관리자(Maintainer) 역할이 있어야 합니다.
  • 보호된 브랜치에 대해 그룹에 허용된 Merge 또는 푸시 및 Merge 허용 권한을 부여할 때, 해당 그룹은 프로젝트에 추가되어 있어야 합니다.

브랜치를 보호하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 리포지터리를 선택합니다.
  3. 보호된 브랜치를 확장합니다.
  4. 보호된 브랜치 추가를 선택합니다.
  5. 브랜치 드롭다운 디렉터리에서 보호할 브랜치를 선택합니다.
  6. Merge 허용 디렉터리에서 이 브랜치로 Merge할 수 있는 역할을 선택합니다.

  7. 푸시 및 Merge 허용 디렉터리에서 이 브랜치로 푸시할 수 있는 역할을 선택합니다.

    note
    GitLab Premium 및 Ultimate에서는 Allowed to merge 및 푸시 및 Merge 허용에 그룹 또는 개별 사용자를 추가할 수 있습니다.
  8. 보호하기(Protect)를 선택합니다.

보호된 브랜치가 보호된 브랜치 디렉터리에 표시됩니다.

그룹 내의 모든 프로젝트에 대해

Tier: Premium, Ultimate Offering: Self-Managed
  • GitLab 15.9에서 도입되었으며 group_protected_branches라는 플래그와 함께 제공됩니다. 기본적으로 비활성화되어 있습니다.
자체 호스팅하는 GitLab에서는 기본적으로 이 기능을 사용할 수 없습니다. 사용하려면 관리자가 feature flag인 group_protected_branches를 활성화해야 합니다. GitLab.com 및 GitLab Dedicated에서는 이 기능을 사용할 수 없습니다.

그룹 소유자는 그룹을 위해 보호된 브랜치를 생성할 수 있습니다. 이 설정은 그룹의 모든 프로젝트에서 상속되며 프로젝트 설정에서 재정의할 수 없습니다. 특정 브랜치가 그룹 및 프로젝트 수준에서 모두 강제 푸시 허용 설정으로 구성된 경우, 프로젝트 수준의 강제 푸시 허용 설정은 그룹 수준 설정을 우선하여 무시됩니다.

전제 조건:

  • 그룹에서 소유자 역할이 있어야 합니다.

그룹 내의 모든 프로젝트에 대해 브랜치를 보호하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
  2. 설정 > 리포지터리를 선택합니다.
  3. 보호된 브랜치를 확장합니다.
  4. 보호된 브랜치 추가를 선택합니다.
  5. 브랜치 텍스트 상자에 브랜치 이름이나 와일드카드를 입력합니다. 브랜치 이름과 와일드카드는 대소문자를 구분합니다.
  6. Merge 허용 디렉터리에서 이 브랜치로 Merge할 수 있는 역할을 선택합니다.
  7. 푸시 및 Merge 허용 디렉터리에서 이 브랜치로 푸시할 수 있는 역할을 선택합니다.
  8. 보호하기(Protect)를 선택합니다.

보호된 브랜치가 보호된 브랜치 디렉터리에 추가됩니다.

와일드카드 규칙으로 여러 브랜치 보호

와일드카드를 사용하면 단일 브랜치에 여러 규칙을 적용할 수 있습니다. 브랜치에 두 개 이상의 규칙이 적용되면 가장 관용적인 규칙이 브랜치 동작을 제어합니다. Merge 제어가 올바르게 작동하려면 푸시 및 Merge 허용을 허용된 Merge보다 넓은 사용자 집합으로 설정해야 합니다.

필수 조건:

  • 적어도 Maintainer 역할이 있어야 합니다.

동시에 여러 브랜치를 보호하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 리포지터리를 선택합니다.
  3. 보호된 브랜치를 확장합니다.
  4. 보호된 브랜치 추가를 선택합니다.

  5. 브랜치 드롭다운 디렉터리에서 브랜치 이름과 와일드카드를 입력합니다. 브랜치 이름과 와일드카드는 대소문자를 구분합니다. 예시:

    와일드카드 보호된 브랜치 일치하는 브랜치
    *-stable production-stable, staging-stable
    production/* production/app-server, production/load-balancer
    *gitlab* gitlab, gitlab/staging, master/gitlab/production
  6. 허용된 Merge 디렉터리에서 이 브랜치에 Merge할 수 있는 역할을 선택합니다.
  7. 푸시 및 Merge 허용 디렉터리에서 이 브랜치로 푸시할 수 있는 역할을 선택합니다. GitLab Premium 또는 Ultimate에서는 그룹이나 개별 사용자도 추가할 수 있습니다.
  8. 보호를 선택합니다.

보호된 브랜치가 보호된 브랜치 디렉터리에 표시됩니다.

보호된 새 브랜치 생성

적어도 Developer 역할이 있는 사용자는 새로운 보호된 브랜치를 만들 수 있습니다.

필수 조건:

  • 푸시 및 Merge 허용이 아무도로 설정되어 있어야 합니다.
  • 허용된 Merge이 Developers로 설정되어 있어야 합니다.

사용자 인터페이스 또는 API를 사용하여 새 브랜치를 만들 수 있습니다. 이를 통해 실수로 명령줄이나 Git 클라이언트 응용 프로그램에서 브랜치를 만들지 않게 할 수 있습니다.

사용자 인터페이스를 통해 새 브랜치를 만들려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 코드 > 브랜치를 선택합니다.
  3. 새 브랜치를 선택합니다.
  4. 브랜치 이름을 입력하고 새 브랜치의 기준이 될 기존 브랜치, 태그 또는 커밋을 선택합니다. 보호된 브랜치와 보호된 브랜치에 이미 있는 커밋만이 허용됩니다.

보호된 브랜치에 대한 모든 Merge Request 제출 필요

모든 사람에게 보호된 브랜치로 직접 확인하도록 허용하는 대신 모든 사람에게 Merge Request을 제출하도록 강제할 수 있습니다.

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 리포지터리를 선택합니다.
  3. 보호된 브랜치를 확장합니다.
  4. 보호된 브랜치 추가를 선택합니다.
  5. 브랜치 드롭다운 디렉터리에서 보호하려는 브랜치를 선택합니다.
  6. 허용된 Merge 디렉터리에서 Developers + Maintainers를 선택합니다.
  7. 푸시 및 Merge 허용 디렉터리에서 아무도를 선택합니다.
  8. 보호를 선택합니다.

모든 사람에게 보호된 브랜치로 직접 푸시 허용

쓰기 액세스 권한이 있는 모든 사람에게 보호된 브랜치로 푸시할 수 있도록 허용할 수 있습니다.

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 리포지터리를 선택합니다.
  3. 보호된 브랜치를 확장합니다.
  4. 보호된 브랜치 추가를 선택합니다.
  5. 브랜치 드롭다운 디렉터리에서 보호하려는 브랜치를 선택합니다.
  6. 푸시 및 Merge 허용 디렉터리에서 Developers + Maintainers를 선택합니다.
  7. 보호를 선택합니다.

배포 키를 보호된 브랜치로 푸시할 수 있도록 허용

배포 키의 소유자가 보호된 브랜치로 푸시할 수 있도록 허용할 수 있습니다. 사용자가 관련 프로젝트의 구성원이 아니어도 배포 키가 작동합니다. 그러나 배포 키의 소유자는 프로젝트에 적어도 읽기 액세스 권한이 있어야 합니다.

필수 조건:

  • 프로젝트를 위해 배포 키가 활성화되어 있어야 합니다. 프로젝트 배포 키는 생성될 때 기본적으로 활성화됩니다. 그러나 공개 배포 키는 프로젝트에 권한을 부여받아야 합니다.
  • 배포 키가 프로젝트 리포지터리에 쓰기 액세스권한을 가지고 있어야 합니다.

보호된 브랜치로 배포 키를 허용하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 리포지터리를 선택합니다.
  3. 보호된 브랜치를 확장합니다.
  4. 보호된 브랜치 추가를 선택합니다.
  5. 브랜치 드롭다운 디렉터리에서 보호하려는 브랜치를 선택합니다.
  6. 푸시 및 Merge 허용 디렉터리에서 배포 키를 선택합니다.
  7. 보호를 선택합니다.

배포 키는 허용된 Merge 드롭다운 디렉터리에 표시되지 않습니다.

보호된 브랜치에서 강제 푸시 허용

보호된 브랜치에 강제 푸시를 허용할 수 있습니다.

새로운 브랜치를 보호하고 강제 푸시를 활성화하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 리포지터리를 선택합니다.
  3. 보호된 브랜치를 확장합니다.
  4. 보호된 브랜치 추가를 선택합니다.
  5. 브랜치 드롭다운 디렉터리에서 보호하려는 브랜치를 선택합니다.
  6. 푸시 및 Merge 허용 및 허용된 Merge 디렉터리에서 원하는 설정을 선택합니다.
  7. 모든 사용자에게 푸시 액세스 권한이 있는 경우 강제 푸시 허용 토글을 켭니다.
  8. 보호를 선택합니다.

이미 보호된 브랜치에서 강제 푸시를 활성화하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 리포지터리를 선택합니다.
  3. 보호된 브랜치를 확장합니다.
  4. 보호된 브랜치 추가를 선택합니다.
  5. 보호된 브랜치의 디렉터리에서 해당 브랜치 옆에 있는 강제 푸시 허용 토글을 켭니다.

이제 해당 브랜치에 푸시 액세스 권한이 있는 멤버는 강제 푸시를 수행할 수 있습니다.

브랜치가 여러 규칙과 일치하는 경우

브랜치가 여러 규칙과 일치하는 경우, 가장 관용적인 규칙이 브랜치의 보호 수준을 결정합니다. 예를 들어 미리 정의된 와일드카드를 포함한 다음 예제를 살펴보세요:

브랜치 이름 패턴 강제 푸시 허용
v1.x 예
v1.* 아니요
v* 아니요

v1.x 라는 이름의 브랜치는 v1.x, v1.*, v*의 세 가지 브랜치 이름 패턴과 일치합니다. 가장 관용적인 옵션이 행동을 제어하기 때문에 v1.x 브랜치에 대한 권한은 다음과 같습니다:

  • 강제 푸시 허용: 세 가지 설정 중에서 가장 관용적인 예로 제어됩니다. v1.x와 v* (각각 더 엄격한 액세스 권한이 있는)에도 일치하지만, 이 브랜치로 푸시할 수 있는 모든 사용자는 강제 푸시도 할 수 있습니다.
note
프로젝트 수준의 브랜치에 대한 강제 푸시 설정은 group_protected_branches 피처 플래그가 활성화되고 그룹 소유자가 동일한 브랜치에 대한 그룹 수준 보호를 설정한 경우 그룹 수준 설정에 의해 재정의됩니다.

보호된 브랜치의 코드 소유자 승인 필요

Tier: Premium, Ultimate Offering: GitLab.com, Self-Managed, GitLab Dedicated

보호된 브랜치의 경우 코드 소유자의 최소 승인 하나가 필요할 수 있습니다. 브랜치가 여러 규칙에 의해 보호되는 경우 해당 규칙 중 코드 소유자 승인 필요가 활성화된 경우 적용 가능한 규칙 중 어떤 규칙인지에 상관없이 코드 소유자 승인이 필요합니다.

새 브랜치를 보호하고 코드 소유자 승인을 활성화하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 리포지터리를 선택합니다.
  3. 보호된 브랜치를 확장합니다.
  4. 보호된 브랜치 추가를 선택합니다.
  5. 브랜치 드롭다운 디렉터리에서 보호하려는 브랜치를 선택합니다.
  6. 푸시 및 Merge 허용 및 허용된 Merge 디렉터리에서 원하는 설정을 선택합니다.
  7. 코드 소유자 승인 필요 토글을 켭니다.
  8. 보호를 선택합니다.

이미 보호된 브랜치에서 코드 소유자 승인을 활성화하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 리포지터리를 선택합니다.
  3. 보호된 브랜치를 확장합니다.
  4. 보호된 브랜치 추가를 선택합니다.
  5. 보호된 브랜치의 디렉터리에서 해당 브랜치 옆에 있는 코드 소유자 승인 토글을 켭니다.

활성화되면 이러한 브랜치에 대한 모든 Merge Request에는 코드 소유자의 승인이 필요하며, 해당 규칙을 충족하는 경우 직접 푸시는 거부됩니다.

CODEOWNERS 파일에 지정되지 않은 사용자는 특정 파일에 푸시할 수 없습니다. 개발자를 보호된 브랜치로 직접 푸시하는 것을 제한할 필요가 없습니다. 대신 리뷰가 필요한 특정 파일에 푸시를 제한할 수 있습니다.

GitLab Premium 13.5 이후, 보호된 브랜치로 푸시할 수 있는 사용자 및 그룹은 기능 브랜치에 대한 Merge Request 승인 규칙, 코드 소유자를 포함하여 필요하지 않습니다. 따라서, 이들은 Merge Request 승인 규칙을 건너뛸 수 있습니다.

보호된 브랜치에서 파이프라인 실행하기

보호된 브랜치에 머지 또는 푸시할 수 있는 권한은 사용자가 CI/CD 파이프라인을 실행하고 작업을 실행할 수 있는지 여부를 정의합니다.

왜냐하면 Merge Request 파이프라인은 소스 브랜치에서 실행되기 때문에, Merge Request을 열고 있는 사용자가 소스 브랜치로 머지하거나 푸시할 수 있는 권한이 없으면 파이프라인이 생성되지 않습니다.

자세한 내용은 보호된 브랜치의 보안을 참조하세요.

보호된 브랜치 삭제하기

최소한 Maintainer 역할을 가진 사용자는 GitLab 웹 인터페이스를 사용하여 매뉴얼으로 보호된 브랜치를 삭제할 수 있습니다:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 코드 > 브랜치를 선택합니다.
  3. 삭제하려는 브랜치 옆에서 삭제를 선택합니다 ().
  4. 확인 대화상자에서 브랜치 이름을 입력하고 예, 보호된 브랜치 삭제를 선택합니다. 브랜치 이름은 대소문자를 구분합니다.

보호된 브랜치는 GitLab의 UI 또는 API를 사용해서만 삭제할 수 있습니다. 로컬 Git 명령이나 타사 Git 클라이언트를 통해 실수로 브랜치를 삭제하는 것을 방지합니다.

관련 주제

문제 해결

브랜치 이름은 대소문자를 구분합니다

git에서 브랜치 이름은 대소문자를 구분합니다. 보호된 브랜치를 구성하거나 대상 브랜치 워크플로우를 구성할 때, dev는 DEV나 Dev와 같지 않습니다.