보호된 브랜치는 코드 안정성과 품질을 보장하기 위해 GitLab의 브랜치에 특정 권한을 적용합니다. 보호된 브랜치는 다음과 같이 동작합니다:

• 코드 변경 사항을 머지하고 푸시할 수 있는 사용자를 제어합니다.
• 중요한 브랜치가 실수로 삭제되는 것을 방지합니다.
• 코드 검토 및 승인 프로세스를 적용합니다.
• 코드 소유자 승인 요구 사항을 관리합니다.
• 커밋 히스토리를 유지하기 위해 강제 푸시 권한을 규제합니다.
• UI와 보호된 브랜치 API 양쪽에서 액세스를 제어합니다.

여러 규칙과 일치하거나 복잡한 권한 요구 사항이 있는 브랜치에서 보호 규칙이 어떻게 동작하는지에 대한 자세한 내용은 보호 규칙을 참고합니다.

브랜치 보호#

개별 프로젝트 또는 그룹의 모든 프로젝트에 보호된 브랜치를 구성합니다.

프로젝트에서#

사전 요구 사항:

• Maintainer 또는 Owner 권한이 있어야 합니다.
• 보호된 브랜치에서 그룹에 Allowed to merge 또는 Allowed to push and merge 권한을 부여할 때는 해당 프로젝트에 액세스할 수 있고 그룹과 공유되어 있어야 합니다. 자세한 내용은 공유된 프로젝트를 참고합니다.

브랜치를 보호하려면:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > Repository를 선택합니다.
3. Branch rules를 펼칩니다.
4. Add branch rule > Branch name or pattern을 선택합니다.
5. 드롭다운 목록에서 보호할 브랜치를 검색해 선택합니다.
6. Branch rule details 페이지를 보려면 Create branch rule을 선택합니다.
7. Protect branch 섹션에서 다음 옵션 중 하나를 선택합니다:
   • Allowed to merge에서 Edit를 선택합니다.
     1. 이 브랜치에 머지할 수 있는 권한을 선택합니다.
     2. Save changes를 선택합니다.
   • Allowed to push and merge에서 Edit를 선택합니다.
     1. 이 브랜치에 푸시할 수 있는 권한을 선택합니다.
     2. 선택 사항. Deploy keys를 검색해 선택합니다.
     3. Save changes를 선택합니다.

그룹에서#

그룹 소유자는 그룹에 대한 보호된 브랜치를 만들 수 있습니다. 이 설정은 그룹의 모든 프로젝트에 적용되며 프로젝트에서 수정할 수 없습니다.

사전 요구 사항:

• 그룹에 대한 Owner 권한이 있어야 합니다.
• 해당 그룹은 최상위 그룹이어야 합니다. 하위 그룹은 지원되지 않습니다.

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

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > Repository를 선택합니다.
3. Protected branches를 펼칩니다.
4. Add protected branch를 선택합니다.
5. Branch 텍스트 상자에 브랜치 이름 또는 와일드카드(*)를 입력합니다. 브랜치 이름과 와일드카드는 대소문자를 구분합니다.
6. Allowed to merge 목록에서 이 브랜치에 머지할 수 있는 권한을 선택합니다.
7. Allowed to push and merge 목록에서 이 브랜치에 푸시할 수 있는 권한을 선택합니다.
8. Allowed to force push 및 Require approval from code owners에 대해 원하는 설정을 선택합니다.
9. Protect를 선택합니다.

푸시 및 머지 권한#

Allowed to merge 및 Allowed to push and merge 설정은 브랜치 보호의 서로 다른 측면을 제어합니다:

Allowed to merge 또는 Allowed to push and merge에서 No one을 선택하면 UI가 다른 권한 선택을 지웁니다. 이 동작은 여러 액세스 수준을 동시에 설정할 수 있는 API와 다릅니다. API 동작에 대한 자세한 내용은 보호된 브랜치 API를 참고합니다.

브랜치 유형별 보호 전략#

브랜치 유형에 따라 목적과 보안 요구 사항이 다르므로 필요한 보호 수준도 다릅니다.

프로덕션 환경에 배포되는 브랜치의 경우:

• Allowed to merge를 Maintainers만으로 설정합니다.
• Allowed to push and merge를 No one(비어 있지 않음)으로 설정합니다.
• Require approval from code owners를 활성화합니다.
• 여러 명의 승인을 요구하는 방안을 고려합니다.

이렇게 구성하면 모든 변경 사항에 Maintainer 승인을 받은 머지 리퀘스트가 필요합니다.

활발히 개발 중인 브랜치의 경우:

• Allowed to merge를 Developers + Maintainers로 설정합니다.
• Allowed to push and merge를 No one(비어 있지 않음)으로 설정합니다.

이렇게 구성하면 모든 변경 사항이 코드 검토를 거치도록 하면서 개발자가 승인된 머지 리퀘스트를 머지할 수 있습니다.

Developer 권한의 권한 조합#

다음 예시는 보호 구성에 따라 Developer 권한이 있는 사용자가 할 수 있는 작업을 보여줍니다:

기본 브랜치 보호 설정#

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

와일드카드 규칙 사용#

와일드카드를 사용하면 단일 브랜치에 여러 규칙이 적용될 수 있습니다. 브랜치에 두 개 이상의 규칙이 적용되면 가장 허용적인 규칙이 브랜치의 동작을 결정합니다. 머지 제어가 제대로 작동하려면 Allowed to merge보다 더 넓은 사용자 집합에 Allowed to push and merge를 설정합니다.

사전 요구 사항:

• Maintainer 또는 Owner 권한이 있어야 합니다.

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

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.

2. 왼쪽 사이드바에서 Settings > Repository를 선택합니다.

3. Branch rules를 펼칩니다.

4. Add branch rule > Branch name or pattern을 선택합니다.

5. 드롭다운 목록에 브랜치 이름과 와일드카드(*)를 입력합니다. 브랜치 이름과 와일드카드는 대소문자를 구분합니다. 예:

   와일드카드로 보호된 브랜치	일치하는 브랜치
   *-stable	production-stable, staging-stable
   production/*	production/app-server, production/load-balancer
   *gitlab*	gitlab, gitlab/staging, master/gitlab/production

6. Create wildcard를 선택합니다.

7. Create branch rule을 선택합니다. Branch rule details 페이지로 이동합니다.

8. Protect branch 섹션에서 다음 옵션 중 하나를 선택합니다:

   • Allowed to merge에서 Edit를 선택합니다.
     1. 이 브랜치에 머지할 수 있는 권한을 선택합니다.
     2. Save changes를 선택합니다.
   • Allowed to push and merge에서 Edit를 선택합니다.
     1. 이 브랜치에 머지할 수 있는 권한을 선택합니다.
     2. 원하는 경우 Deploy keys를 검색해 추가합니다.
     3. Save changes를 선택합니다.

보호 옵션 구성#

브랜치를 보호하기 위해 다양한 보호 옵션을 설정할 수 있습니다.

머지 리퀘스트 요구#

보호된 브랜치에 직접 체크인하도록 허용하는 대신 모든 사용자가 머지 리퀘스트를 제출하도록 강제할 수 있습니다:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > Repository를 선택합니다.
3. Branch rules를 펼칩니다.
4. 브랜치 옆에서 View details를 선택합니다.
5. Allowed to merge 섹션에서 Edit를 선택합니다
6. Developers + Maintainers를 선택합니다.
7. Save changes를 선택합니다.
8. Allowed to push and merge 섹션에서 No one을 선택합니다.
9. Save changes를 선택합니다.

직접 푸시 허용#

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

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > Repository를 선택합니다.
3. Branch rules를 펼칩니다.
4. 브랜치 옆에서 View details를 선택합니다.
5. Allowed to push and merge 섹션에서 Developers + Maintainers를 선택합니다.
6. Save changes를 선택합니다.

그룹 권한 사용#

그룹 또는 하위 그룹의 멤버를 보호된 브랜치의 Allowed to merge 또는 Allowed to push and merge로 설정하려면:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.

2. 왼쪽 사이드바에서 Settings > Repository를 선택합니다.

3. Branch rules를 펼칩니다.

4. 브랜치 옆에서 View details를 선택합니다.

5. Allowed to merge 또는 Allowed to push and merge 섹션에서 Edit를 선택합니다.

6. Groups 아래에서 검색해 그룹을 추가합니다. 예:

   # Allow group members to merge into this branch
   Allowed to merge: @group-x
   
   # Allow group members to push and merge into this branch
   Allowed to push and merge: @group-x/subgroup-y
   

7. Save changes를 선택합니다.

그룹 상속 요구 사항#

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TD
    accTitle: Diagram of group inheritance for protected branches
    accDescr: If a project is shared with a group, the group members inherit permissions for protected branches.
    A[Parent group X] -->|owns| B[Project A]
    A -->|contains| C[Subgroup Y]
    B -->|shared with| C
    C -->|members inherit permissions| B

이 예시에서:

• 상위 그룹 X(group-x)가 프로젝트 A를 소유합니다.
• 상위 그룹 X에는 하위 그룹인 하위 그룹 Y도 포함되어 있습니다. (group-x/subgroup-y)
• 프로젝트 A는 하위 그룹 Y와 공유됩니다.

보호된 브랜치 권한을 받을 수 있는 그룹은 다음과 같습니다:

• 프로젝트 A: 프로젝트 A가 하위 그룹 Y와 공유되어 있으므로 그룹 X와 하위 그룹 Y 모두입니다.

그룹과 프로젝트 공유#

그룹 또는 하위 그룹과 프로젝트를 공유하면 해당 멤버가 보호된 브랜치 권한을 받을 수 있습니다.

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph LR
    accTitle: Diagram of project sharing for protected branch permissions
    accDescr: Sharing a project with a group affects whether their members can have protected branch permissions.
    A[Parent group X] -->|owns| B[Project A]
    A -->|also contains| C[Subgroup Y]
    C -.->D{Share Project A<br/>with Subgroup Y?} -.->|yes| E[Members of Subgroup Y<br/>can have protected<br/>branch permissions]
    D{Share Project A<br/>with Subgroup Y?} -.->|no| F[Members of Subgroup Y<br />cannot have protected<br/>branch permissions]
    E -.->|Add Subgroup Y<br/> to protected branch settings| I[Subgroup Y members<br/>can merge/push] -.-> B
    F -.-> |Add Subgroup Y<br/> to protected branch settings| J[Settings will not<br/>take effect] -.-> B

프로젝트 A에 대해 하위 그룹 Y의 멤버에게 액세스 권한을 부여하려면 해당 하위 그룹과 프로젝트를 공유해야 합니다. 하위 그룹을 보호된 브랜치 설정에 직접 추가하는 것은 효과가 없고 하위 그룹 멤버에게는 적용되지 않습니다.

배포 키 액세스 활성화#

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

사전 요구 사항:

• 프로젝트에 배포 키가 활성화되어 있어야 합니다. 프로젝트 배포 키는 생성될 때 기본적으로 활성화됩니다. 다만 공개 배포 키는 프로젝트에 대한 액세스 권한을 부여받아야 합니다.
• 배포 키에 프로젝트 리포지터리에 대한 쓰기 액세스 권한이 있어야 합니다.
• 배포 키의 소유자에게 프로젝트에 대한 최소 읽기 액세스 권한이 있어야 합니다.
• 배포 키의 소유자는 프로젝트의 멤버이기도 해야 합니다.

배포 키가 보호된 브랜치에 푸시하도록 허용하려면:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > Repository를 선택합니다.
3. Branch rules를 펼칩니다.
4. 브랜치 옆에서 View details를 선택합니다.
5. Allowed to push and merge 섹션에서 Edit를 선택합니다.
6. Deploy keys에서 검색해 배포 키를 추가합니다.
7. Save changes를 선택합니다.

배포 키는 Allowed to merge 드롭다운 목록에서 사용할 수 없습니다.

강제 푸시 허용#

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

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

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > Repository를 선택합니다.
3. Branch rules를 펼칩니다.
4. Add branch rule > Branch name or pattern을 선택합니다.
5. 드롭다운 목록에서 보호하고 강제 푸시를 활성화할 브랜치를 검색해 선택합니다.
6. Create branch rule을 선택합니다. Branch rule details 페이지로 이동합니다.
7. Allowed to push and merge 및 Allowed to merge 섹션에서 원하는 설정을 선택합니다.
8. Save changes를 선택합니다.
9. 푸시 액세스 권한이 있는 모든 사용자에게 강제 푸시를 허용하려면 Allowed to force push 토글을 켭니다.

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

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > Repository를 선택합니다.
3. Branch rules를 펼칩니다.
4. 브랜치 옆에서 View details를 선택합니다.
5. Allowed to force push 토글을 켭니다.

코드 소유자 승인 요구#

보호된 브랜치에는 코드 소유자의 승인을 최소 한 건 요구할 수 있습니다. 브랜치가 여러 규칙으로 보호되는 경우 Required approval from code owners가 활성화되어 있으면 코드 소유자 승인이 필요합니다.

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

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > Repository를 선택합니다.
3. Branch rules를 펼칩니다.
4. Add branch rule > Branch name or pattern을 선택합니다.
5. 드롭다운 목록에서 보호하고 강제 푸시를 활성화할 브랜치를 검색해 선택합니다.
6. Create branch rule을 선택합니다. Branch rule details 페이지로 이동합니다.
7. Allowed to push and merge 및 Allowed to merge 섹션에서 원하는 설정을 선택합니다.
8. Save changes를 선택합니다.
9. Require approval from code owners 토글을 켭니다.

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

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > Repository를 선택합니다.
3. Branch rules를 펼칩니다.
4. 브랜치 옆에서 View details를 선택합니다.
5. Code owner approval 토글을 켭니다.

활성화하면 이 브랜치에 대한 모든 머지 리퀘스트는 머지되기 전에 일치하는 규칙별로 코드 소유자의 승인을 받아야 합니다. 또한 규칙이 일치하면 보호된 브랜치로의 직접 푸시가 거부됩니다.

CODEOWNERS 파일에 지정되지 않은 사용자는 별도로 허용받지 않는 한 지정된 파일이나 경로에 대한 변경 사항을 푸시할 수 없습니다. 개발자가 보호된 브랜치에 직접 푸시하는 것을 제한할 필요는 없습니다. 대신 코드 소유자의 검토가 필요한 특정 파일에 대해서만 푸시를 제한할 수 있습니다.

보호된 브랜치에 푸시할 수 있는 사용자와 그룹은 기능 브랜치를 머지하기 위해 머지 리퀘스트가 필요하지 않습니다. 따라서 코드 소유자를 포함한 머지 리퀘스트 승인 규칙을 건너뛸 수 있습니다.

브랜치 보호를 해제할 수 있는 사람 제어#

브랜치를 보호할 때 나중에 그 보호를 해제할 수 있는 사람도 제어할 수 있습니다. 기본적으로 Maintainer 또는 Owner 권한이 있는 사용자가 보호된 브랜치의 보호를 해제할 수 있습니다.

규제 또는 준수 요구 사항이 있는 조직이라면 이 권한을 특정 사용자, 그룹 또는 액세스 수준으로 제한할 수 있습니다.

이 권한은 API를 통해서만 구성할 수 있습니다. 다음 용도에 이 기능을 사용합니다:

• 규제 준수: 권한이 있는 담당자만 브랜치 보호를 수정할 수 있도록 합니다.
• 대규모 조직: 여러 리포지터리에서 보호가 실수로 제거되는 것을 방지합니다.
• 자동화된 거버넌스: 개발 팀이 재정의할 수 없는 관리자 전용 보호를 만드는 스크립트를 사용할 수 있습니다.

보호 해제 권한에 유효한 액세스 수준과 제약 조건에 대한 자세한 내용은 유효한 액세스 수준을 참고합니다.

보호 해제 권한#

다음 표는 구성에 따라 브랜치의 보호를 해제할 수 있는 사람을 보여줍니다:

보호된 브랜치의 CI/CD#

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

머지 리퀘스트 파이프라인은 소스 브랜치 또는 소스 브랜치를 기반으로 하는 머지 리퀘스트 참조에서 실행됩니다. 사용자에게 소스 브랜치에 머지하거나 푸시할 권한이 없으면 파이프라인이 생성되지 않습니다.

머지 리퀘스트가 보호된 브랜치 사이에 있는 경우, 사용자에게 소스 브랜치와 대상 브랜치를 모두 업데이트할 권한이 있으면 파이프라인에서 보호된 변수와 러너를 사용할 수 있습니다. 자세한 내용은 보호된 변수 및 러너에 대한 액세스 제어를 참고합니다.

보호된 브랜치 생성#

사전 요구 사항:

• Developer, Maintainer 또는 Owner 권한이 있어야 합니다.
• 보호된 브랜치를 만들려면 브랜치 보호가 보호된 브랜치에 대해 모든 사용자가 머지 리퀘스트를 제출하도록 요구하게 구성되어 있어야 합니다.

보호가 적용된 새 브랜치를 만들려면:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Code > Branches를 선택합니다.
3. New branch를 선택합니다.
4. 브랜치 이름을 입력하고 새 브랜치의 기반이 될 기존 브랜치, 태그 또는 커밋을 선택합니다. 보호된 브랜치에 대해 모든 사용자가 머지 리퀘스트를 제출하도록 요구하는 경우, 기존 보호된 브랜치와 이미 보호된 브랜치에 있는 커밋만 허용됩니다.

브랜치 API를 사용해 보호가 적용된 브랜치를 만들 수도 있습니다.

브랜치 보호가 모든 사용자가 보호된 브랜치에 직접 푸시하도록 허용하게 구성되어 있으면, 명령줄이나 Git 클라이언트 애플리케이션에서도 보호가 적용된 브랜치를 만들 수 있습니다.

보호된 브랜치 삭제#

Maintainer 또는 Owner 권한이 있는 사용자는 GitLab 웹 인터페이스를 사용해 보호된 브랜치를 수동으로 삭제할 수 있습니다:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Code > Branches를 선택합니다.
3. 삭제할 브랜치 옆에서 More actions(⋮)를 선택합니다.
4. Delete protected branch를 선택합니다.
5. 확인 대화 상자에서 브랜치 이름을 입력하고 Yes, delete protected branch를 선택합니다. 브랜치 이름은 대소문자를 구분합니다.

보호된 브랜치는 GitLab UI 또는 API로만 삭제할 수 있습니다. 로컬 Git 명령이나 타사 Git 클라이언트로는 보호된 브랜치를 삭제할 수 없습니다.

정책 적용#

보안과 준수를 위해 인스턴스, 그룹 또는 프로젝트에서 별도로 정의된 설정에 영향을 주는 머지 리퀘스트 승인 정책을 구현할 수 있습니다. 정책은 사용자가 브랜치의 보호를 해제하거나 브랜치를 삭제하고, 푸시하거나 강제 푸시할 수 있는 능력에 영향을 줄 수 있습니다.

관련 주제#

• 보호 규칙 및 권한
• 보호된 브랜치 API
• 브랜치
• 브랜치 API
• 커밋 API
• 코드 소유자

문제 해결#

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

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