보호된 브랜치


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

GitLab에서는 권한이 저장소 및 브랜치에 대한 읽기 또는 쓰기 권한을 가질 수 있는 아이디어를 중심으로 정의됩니다. 특정 브랜치에 더 많은 제한을 부여하기 위해 그들은 보호될 수 있습니다.

보호된 브랜치를 통제합니다:

  • 어떤 사용자가 브랜치로 병합할 수 있는지.
  • 어떤 사용자가 브랜치로 푸시할 수 있는지.
  • 사용자가 강제로 브랜치로 푸시할 수 있는지.
  • CODEOWNERS 파일에 나열된 파일의 변경 사항이 직접 브랜치로 푸시될 수 있는지.
  • 보호된 브랜치 API를 사용하여 브랜치의 보호를 해제할 수 있는 사용자, 그룹 또는 액세스 레벨.
  • Commits API를 사용하여 브랜치를 수정할 수 있는 사용자.

저장소의 기본 브랜치는 기본적으로 보호됩니다.

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

  • GitLab 16.0에서 브랜치 푸시 권한이 GitLab 관리자가 GitLab 16.0버전에서 allowed 권한을 가져야 하는 것으로 변경되었습니다.

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

액션 누가 할 수 있는지
브랜치 보호 적어도 Maintainer 역할.
브랜치로 푸시 Allowed 권한을 가진 사람. (1)
브랜치로 강제로 푸시 아무도 불가.
브랜치 삭제 아무도 불가. (2)
  1. 개발자 역할을 하는 사용자는 그룹 내에서 프로젝트를 만들 수 있지만, 초기에 기본 브랜치로 푸시할 수 없을 수도 있습니다.
  2. 아무도 Git 명령을 사용하여 보호된 브랜치를 삭제할 수 없지만, 적어도 Maintainer 역할을 하는 사용자는 UI나 API에서 보호된 브랜치를 삭제할 수 있습니다.

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

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

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

브랜치 이름 패턴 병합할 수 있는지 푸시 및 병합할 수 있는지
v1.x Maintainer Maintainer
v1.* Maintainer + Developer Maintainer
v* 아무도 아무도

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

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

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

If you want to ensure that No one is allowed to push to branch v1.x, every pattern that matches v1.x must set Allowed to push and merge to No one, like this:

브랜치 이름 패턴 병합할 수 있는지 푸시 및 병합할 수 있는지
v1.x Maintainer No one
v1.* Maintainer + Developer No one
v* 아무도 아무도

기본 브랜치 보호 수준 설정

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

기존 브랜치에 보호 추가

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

하나의 프로젝트에 대한 경우

전제 조건:

  • 적어도 Maintainer 역할을 가져야 합니다.
  • 보호된 브랜치에서 그룹에 Allowed to merge 또는 Allowed to push and merge 권한을 부여할 때, 그룹이 프로젝트에 추가되어야 합니다.

브랜치를 보호하려면:

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

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

    참고: GitLab Premium 및 Ultimate에서는 Allowed to merge 및 Allowed to push and merge에 그룹 또는 개별 사용자를 추가할 수 있습니다.

  8. 보호를 선택합니다.

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

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


Tier: Premium, Ultimate
Offering: Self-managed
  • GitLab 15.9에서 group_protected_branches라는 플래그로 도입되었으며, 기본값은 비활성화된 상태입니다. feature_flag라는 기능 플래그로 소유됩니다.

자체 관리형 GitLab에서는 기본적으로 이 기능을 사용할 수 없습니다.
사용하려면, 관리자가 기능 플래그인 group_protected_branches를 활성화할 수 있습니다.
GitLab Dedicated의 경우, 이 기능을 사용할 수 없습니다.

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

전제 조건: - 그룹에 대해 소유자 역할을 가져야 합니다.

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

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

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

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

와일드카드를 사용하면 여러 규칙을 단일 브랜치에 적용할 수 있습니다. 한 브랜치에 두 개 이상의 규칙이 적용되면, 가장 허용이 많은 규칙이 브랜치의 동작을 제어합니다. 병합 제어가 올바르게 작동하려면, 푸시 및 병합 허용을 병합 허용보다 넓은 범위의 사용자로 설정하세요.

필수 조건:

  • 적어도 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. 병합 허용 목록에서 이 브랜치로 병합할 수 있는 역할을 선택합니다.
  7. 푸시 및 병합 허용 목록에서 이 브랜치로 푸시할 수 있는 역할을 선택합니다. GitLab 프리미엄 또는 얼티밋에서는 그룹 또는 개별 사용자를 추가할 수도 있습니다.
  8. 보호를 선택합니다.

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

보호된 브랜치에 대한 모두에게 병합 요청 제출 필요

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

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

또는 브랜치 규칙 생성 또는 편집을 선택한 후:

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

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

쓰기 액세스 권한을 가진 모든 사람이 보호된 브랜치로 푸시할 수 있도록 할 수 있습니다.

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

또는 브랜치 규칙 생성 또는 편집을 선택한 후:

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

Deploy 키가 보호된 브랜치로 푸시하도록 허용

배포 키를 사용하여 보호된 브랜치에 푸시할 수 있습니다.

사전 요구 사항:

  • 프로젝트에 배포 키가 활성화되어 있어야 합니다. 프로젝트 배포 키는 생성될 때 기본적으로 활성화됩니다. 그러나 공개 배포 키는 프로젝트에 권한 부여되어야 합니다.
  • 배포 키가 프로젝트 저장소에 쓰기 액세스를 가져야 합니다.
  • 배포 키의 소유자는 프로젝트의 적어도 읽기 액세스를 가져야 합니다.
  • 배포 키의 소유자는 프로젝트의 멤버여야 합니다.

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

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

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

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

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

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

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

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

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

또는 브랜치 규칙 생성 또는 편집을 선택한 후:

  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. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  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 클라이언트 응용 프로그램에서도 만들 수 있습니다.

보호된 브랜치 삭제

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

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

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

관련 주제

문제 해결

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

git에서 브랜치 이름은 대소문자를 구분합니다. 보호된 브랜치를 구성하거나 대상 브랜치 작업흐름을 구성할 때, dev는 DEV나 Dev와 동일하지 않습니다.