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

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

여러 규칙과 일치하거나 복잡한 권한 요구 사항이 있는 브랜치의 보호 규칙 동작에 대한 자세한 내용은 보호 규칙을 참조하세요.

브랜치 보호#

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

그룹 규칙은 프로젝트에서 수정할 수 없지만 프로젝트 maintainer는 동일한 브랜치 이름에 대한 별도 규칙을 만들 수 있습니다. 동일한 브랜치에 두 규칙이 모두 적용되는 경우 GitLab은 일치하는 모든 규칙을 함께 평가하고 대부분의 설정에 대해 가장 허용적인 결과를 적용합니다. 자세한 내용은 그룹 및 프로젝트 간의 규칙을 참조하세요.

프로젝트에서#

전제 조건:

• 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. Branch rule details 페이지를 보려면 Create branch rule을 선택합니다.

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 파이프라인을 실행하고 작업에서 액션을 실행할 수 있는지 여부를 정의합니다.

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

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

보호된 브랜치 만들기#

전제 조건:

• 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와 동일하지 않습니다.