보호된 브랜치

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

GitLab에서 권한은 기본적으로 리포지토리와 브랜치에 대한 읽기 또는 쓰기 권한을 갖는 아이디어를 중심으로 정의됩니다. 특정 브랜치에 대한 추가 제한을 부과하려면 해당 브랜치를 보호할 수 있습니다.

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

  • 어떤 사용자가 브랜치에 병합할 수 있는지.
  • 어떤 사용자가 브랜치에 푸시할 수 있는지.
  • 사용자가 브랜치에 강제 푸시할 수 있는지.
  • CODEOWNERS 파일에 나열된 파일에 대한 변경 사항을 브랜치에 직접 푸시할 수 있는지.
  • 어떤 사용자, 그룹 또는 접근 수준이 Protected branches API를 사용하여 브랜치 보호를 해제할 수 있는지.
  • 어떤 사용자가 Commits API를 사용하여 브랜치를 수정할 수 있는지.

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

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

  • 브랜치 푸시 권한은 변경되었습니다. GitLab 16.0에서 GitLab 관리자가 허용된 권한을 가져야 합니다.

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

작업 누가 할 수 있나요
브랜치 보호 최소한 유지 관리자 역할.
브랜치에 푸시 허용된 권한이 있는 모든 사람. (1)
브랜치에 강제 푸시 아무도 안 됨.
브랜치 삭제 아무도 안 됨. (2)
  1. 개발자 역할을 가진 사용자는 그룹에 프로젝트를 생성할 수 있지만, 기본 브랜치에 처음 푸시할 수 없을 수도 있습니다.
  2. 아무도 Git 명령을 사용하여 보호된 브랜치를 삭제할 수 없지만, 유지 관리자 역할을 가진 사용자는 UI 또는 API에서 보호된 브랜치를 삭제할 수 있습니다.

보호된 브랜치가 해제되거나 삭제되는 것을 방지하기 위해 병합 요청 승인 정책을 구현할 수 있습니다.

브랜치가 여러 규칙과 일치할 때

브랜치가 여러 규칙과 일치할 경우, 가장 허용적인 규칙이 브랜치의 보호 수준을 결정합니다. 예를 들어, 다음 규칙을 고려하세요. 여기에는 와일드카드가 포함됩니다.

브랜치 이름 패턴 병합 허용됨 푸시 및 병합 허용됨
v1.x 유지 관리자 유지 관리자
v1.* 유지 관리자 + 개발자 유지 관리자
v* 아무도 안 됨 아무도 안 됨

브랜치 이름이 v1.x인 브랜치는 세 가지 브랜치 이름 패턴인 v1.x, v1.* 및 v*와 대소문자를 구분하여 일치합니다.

가장 허용적인 옵션이 동작을 결정하므로, 브랜치 v1.x의 결과적인 권한은 다음과 같습니다:

  • 병합 허용: 세 가지 설정 중에서 유지 관리자 + 개발자가 가장 허용적이며, 결과적으로 브랜치 동작을 제어합니다. 비록 브랜치가 v1.x와 v*와도 일치하지만(각각 더 엄격한 권한이 설정되어 있음), 개발자 역할을 가진 사용자는 브랜치에 병합할 수 있습니다.
  • 푸시 및 병합 허용: 세 가지 설정 중에서 유지 관리자가 가장 허용적이며, 결과적으로 브랜치 동작을 제어합니다. 비록 v*와 일치하는 브랜치가 아무도 안 됨으로 설정되어 있지만, v1.x 또는 v1.*와 또한 일치하는 브랜치는 더 허용적인 유지 관리자 권한을 받습니다.

브랜치의 동작을 제어하려는 규칙이 확실해야 하며, 일치하는 모든 다른 패턴은 덜 허용적이거나 동등한 허용 규칙을 적용해야 합니다.

브랜치 v1.x에 푸시할 수 있는 아무도를 보장하려면, v1.x와 일치하는 모든 패턴이 푸시 및 병합 허용을 아무도 안 됨으로 설정해야 합니다. 아래와 같이:

브랜치 이름 패턴 병합 허용됨 푸시 및 병합 허용됨
v1.x 유지 관리자 아무도 안 됨
v1.* 유지 관리자 + 개발자 아무도 안 됨
v* 아무도 안 됨 아무도 안 됨

기본 브랜치 보호 수준 설정

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

기존 브랜치에 보호 추가

모든 프로젝트의 보호된 브랜치를 구성하거나 특정 프로젝트에 대해서만 구성할 수 있습니다.

한 프로젝트에 대한 경우

전제 조건:

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

브랜치를 보호하려면:

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

  7. 푸시 및 병합 허용 목록에서 이 브랜치로 푸시할 수 있는 역할을 선택합니다.

    참고:
    GitLab Premium 및 Ultimate에서는 그룹 또는 개별 사용자를 병합 허용 및 푸시 및 병합 허용에 추가할 수 있습니다.

  8. 보호를 선택합니다.

보호된 브랜치는 보호된 브랜치 목록에 표시됩니다.

그룹의 모든 프로젝트에 대한 경우

세부정보:
Tier: Premium, Ultimate Offering: Self-managed


자기 관리형 GitLab에서는 기본적으로 이 기능이 사용 가능하지 않습니다.
이 기능을 사용 가능하게 하려면 관리자가 기능 플래그를 활성화해야 합니다. group_protected_branches라는 이름입니다. GitLab Dedicated에서는 이 기능이 사용할 수 없습니다.

그룹 소유자는 그룹에 대한 보호된 브랜치를 생성할 수 있습니다. 이러한 설정은 그룹의 모든 프로젝트에 상속되며 프로젝트 설정으로 무시할 수 없습니다.

전제 조건:

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

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

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

보호된 브랜치는 보호된 브랜치 목록에 추가됩니다.

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

와일드카드를 사용할 때 여러 규칙이 단일 브랜치에 적용될 수 있습니다.
하나의 브랜치에 둘 이상의 규칙이 적용되면 가장 허용적인 규칙이 브랜치의 동작을 제어합니다.
병합 제어가 제대로 작동하도록 하려면 푸시 및 병합 허용을 병합 허용보다 더 넓은 사용자의 집합으로 설정하십시오.

전제 조건:

  • 유지 관리자 역할이 있어야 합니다.

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

  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. 병합 허용 목록에서 이 브랜치로 병합할 수 있는 역할을 선택합니다.
  7. 푸시 및 병합 허용 목록에서 이 브랜치로 푸시할 수 있는 역할을 선택합니다. GitLab Premium 또는 Ultimate에서는 그룹 또는 개별 사용자를 추가할 수 있습니다.
  8. 보호를 선택합니다.

보호된 브랜치는 보호된 브랜치 목록에 표시됩니다.

보호된 브랜치에 대한 모든 사람의 병합 요청 제출 요구

모든 사람이 보호된 브랜치에 직접 체크인하는 대신 병합 요청을 제출하도록 강제할 수 있습니다:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 저장소를 선택합니다.
  3. 보호된 브랜치를 확장합니다.
  4. 보호된 브랜치 추가를 선택합니다.
  5. 브랜치 드롭다운 목록에서 보호할 브랜치를 선택합니다.
  6. 병합 허용 목록에서 개발자 + 유지 관리를 선택합니다.
  7. 푸시 및 병합 허용 목록에서 아무도를 선택합니다.
  8. 보호를 선택합니다.

또는 브랜치 규칙을 생성하거나 편집할 수 있습니다. 그런 다음:

  1. 병합 허용 섹션에서 편집을 선택합니다.
  2. 개발자 및 유지 관리를 선택합니다.
  3. 변경 사항 저장을 선택합니다.

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

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

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 저장소를 선택합니다.
  3. 보호된 브랜치를 확장합니다.
  4. 보호된 브랜치 추가를 선택합니다.
  5. 브랜치 드롭다운 목록에서 보호할 브랜치를 선택합니다.
  6. 푸시 및 병합 허용 목록에서 개발자 + 유지 관리를 선택합니다.
  7. 보호를 선택합니다.

또는 브랜치 규칙을 생성하거나 편집할 수 있습니다. 그런 다음:

  1. 푸시 및 병합 허용 섹션에서 편집을 선택합니다.
  2. 개발자 및 유지 관리를 선택합니다.
  3. 변경 사항 저장을 선택합니다.

배포 키를 보호된 브랜치에 푸시 허용

배포 키로 보호된 브랜치에 푸시할 수 있습니다.

필수 조건:

  • 배포 키는 프로젝트에 대해 활성화되어야 합니다. 프로젝트 배포 키는 생성될 때 기본적으로 활성화됩니다. 그러나 공개 배포 키는 승인되어야 합니다.
  • 배포 키는 프로젝트 저장소에 대해 쓰기 권한을 가져야 합니다.
  • 배포 키의 소유자는 프로젝트에 대해 최소한 읽기 권한을 가져야 합니다.
  • 배포 키의 소유자는 또한 프로젝트의 구성원이어야 합니다.

배포 키를 사용하여 보호된 브랜치에 푸시할 수 있도록 하려면:

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

배포 키는 병합 허용 드롭다운 목록에서 사용할 수 없습니다.

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

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

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

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 저장소를 선택합니다.
  3. 보호된 브랜치를 확장합니다.
  4. 보호된 브랜치 추가를 선택합니다.
  5. 브랜치 드롭다운 목록에서 보호할 브랜치를 선택합니다.
  6. 푸시 및 병합 허용 및 병합 허용 목록에서 원하는 설정을 선택합니다.
  7. 모든 푸시 권한이 있는 사용자가 강제 푸시를 허용하려면 강제 푸시 허용 토글을 켭니다.
  8. 보호를 선택합니다.

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

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 저장소를 선택합니다.
  3. 보호된 브랜치를 확장합니다.
  4. 보호된 브랜치 목록에서 브랜치 옆에 있는 강제 푸시 허용 토글을 켭니다.

또는 브랜치 규칙을 생성하거나 편집할 수 있습니다. 그런 다음:

  1. 보호된 브랜치 목록에서 브랜치 옆에 있는 강제 푸시 허용 토글을 켭니다.

이 브랜치에 푸시할 수 있는 구성원은 이제 강제 푸시도 할 수 있습니다.

규칙이 여러 개 일치하는 경우

브랜치가 여러 규칙과 일치할 경우, 가장 관대한 규칙이 브랜치의 보호 수준을 결정합니다.

예를 들어, 다음 규칙을 고려해 보세요. 이 규칙에는 와일드카드가 포함됩니다:

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

v1.x라는 이름의 브랜치는 세 가지 브랜치 이름 패턴: v1.x, v1.*, v*와 모두 일치합니다.

가장 관대한 옵션이 동작을 결정하므로, 브랜치 v1.x에 대한 결과적인 권한은 다음과 같습니다:

  • 강제 푸시 허용: 세 가지 설정 중에서 예가 가장 관대하며,

    그 결과 브랜치 동작을 제어합니다. 비록 이 브랜치가 v1.x와 v*에도 일치하지만

    (각각 더 엄격한 권한을 가진), 이 브랜치에 푸시할 수 있는 사용자라면 누구나 강제 푸시를 할 수 있습니다.

보호된 브랜치에서 코드 소유자의 승인을 요구합니다

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

보호된 브랜치에서는 코드 소유자의 승인을 최소한 1건 요구할 수 있습니다.

브랜치가 여러 규칙에 의해 보호되는 경우, 해당 규칙 중 어떤 규칙에서든 코드 소유자의 승인이 필요가 활성화된 경우 코드 소유자의 승인이 요구됩니다.

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

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

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

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

또는 브랜치 규칙을 생성하거나 편집할 수 있습니다.

그런 다음, 보호된 브랜치 목록에서 브랜치 옆의 코드 소유자 승인 토글을 켭니다.

활성화되면, 이러한 브랜치에 대한 모든 병합 요청은 병합될 수 있기 전에 일치하는 규칙에 따라 코드 소유자의 승인을 요구합니다.

또한, 규칙이 일치하는 경우 보호된 브랜치에 대한 직접 푸시는 거부됩니다.

CODEOWNERS 파일에 명시되지 않은 사용자는 지정된 파일 또는 경로에 변경 사항을 푸시할 수 없으며, 특정적으로 허용되지 않는 한 그렇습니다.

개발자가 보호된 브랜치에 직접 푸시하는 것을 제한할 필요는 없습니다.

대신, 코드 소유자의 검토가 필요한 특정 파일로 푸시를 제한할 수 있습니다.

GitLab Premium 13.5 및 이후 버전에서는 보호된 브랜치에 푸시할 수 있는 사용자와 그룹이 기능 브랜치를 병합하기 위해 병합 요청이 필요하지 않습니다.

따라서, 이들은 병합 요청 승인 규칙을 건너뛸 수 있으며, 코드 소유자도 포함됩니다.

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

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

병합 요청 파이프라인은 소스 브랜치에서 실행되므로, 병합 요청을 열고 있는 사용자가 소스 브랜치에 병합하거나 푸시할 권한이 없으면 파이프라인이 생성되지 않습니다.

파이프라인 보안 모델에 대한 자세한 내용은 보호된 브랜치의 보안을 참조하세요.

보호된 브랜치를 사용하여 새 브랜치 만들기

사전 요구 사항:

보호된 브랜치를 사용하여 새 브랜치를 만들려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.

  2. 코드 > 브랜치를 선택합니다.

  3. 새 브랜치를 선택합니다.

  4. 브랜치 이름을 입력하고 새 브랜치의 기반이 될 기존 브랜치, 태그 또는 커밋을 선택합니다. 모든 사람이 보호된 브랜치에 대해 병합 요청을 제출해야 한다면, 기존의 보호된 브랜치와 이미 보호된 브랜치에 있는 커밋만 수용됩니다.

브랜치 API를 사용하여 보호된 브랜치를 가진 브랜치를 생성할 수도 있습니다.

브랜치 보호가 모든 사람이 보호된 브랜치로 직접 푸시할 수 있도록 허용되도록 구성되어 있으면, 커맨드 라인이나 Git 클라이언트 애플리케이션에서 보호된 브랜치를 가진 브랜치도 생성할 수 있습니다.

보호된 브랜치 삭제

최소한 유지관리자 역할이 있는 사용자는 GitLab 웹 인터페이스를 사용하여 보호된 브랜치를 수동으로 삭제할 수 있습니다:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.

  2. 코드 > 브랜치를 선택합니다.

  3. 삭제할 브랜치 옆에 있는 삭제( )를 선택합니다.

  4. 확인 대화상자에서 브랜치 이름을 입력하고 예, 보호된 브랜치 삭제를 선택합니다. 브랜치 이름은 대소문자를 구분합니다.

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

관련 주제

문제 해결

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

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