출처 대조 B · GitHub Docs 문서 대조

검증 환경: GitHub Docs (docs.github.com) 문서 대조

게시 2026-10-09최종 확인 2026-10-09읽기 7분

GitHub Ruleset으로 main 보호하고 본인 PR만 병합하기 (bypass)

GitHub Ruleset으로 main 브랜치 직접 push를 막고, 저장소 관리자는 PR을 통해서만 규칙을 우회해 병합하게 설정하는 방법. 메뉴 경로와 옵션을 공식 문서로 정리했다.

30초 요약

  • Settings → Rules → Rulesets에서 New branch ruleset으로 만든다. 대상은 기본 브랜치(main)로 잡는다.
  • Branch protections에서 Require a pull request before merging을 켜서 main에 직접 push하지 못하게 한다.
  • Bypass list에 저장소 관리자 역할을 추가하고 For pull requests only로 제한한다. 그러면 관리자도 PR을 열어야 하고, 그 PR은 규칙을 우회해 병합할 수 있다.
  • 생성할 때 Enforcement status가 기본값 Disabled이므로 Active로 바꿔야 적용된다.

증상/목표

혼자 또는 소수가 쓰는 저장소에서 main에 실수로 직접 push하거나 force push하는 일을 막고 싶다. 하지만 리뷰어가 없는 저장소에서 승인을 필수로 두면 병합할 사람이 없어질 수 있다. AI가 병합이 끝난 브랜치에 계속 push하던 실수를 장치로 막은 사례는 낚시어때 개발기 3편에 있다. 목표는 다음 둘이다.

  • main으로 가는 변경은 항상 PR을 거친다.
  • 본인이 연 PR은 관리자 권한으로 병합할 수 있다.

원인

공식 문서에 따르면 Ruleset은 브랜치·태그와 사람의 상호작용을 제어하는 이름 붙은 규칙 목록이다. 한 브랜치에 여러 Ruleset이 동시에 적용될 수 있고, 적용 상태(enforcement status)를 지우지 않고 바꿀 수 있다. 기존 branch protection rule은 브랜치에 하나만 적용된다. 둘이 함께 있으면 적용 가능한 규칙이 모두 강제되고, 충돌하면 더 엄격한 쪽이 적용된다.

Bypass list는 특정 역할·팀·GitHub App이 규칙을 건너뛰게 하는 목록이다. 문서는 bypass 대상을 PR로만 제한하는 옵션(For pull requests only)을 설명한다. 이 옵션을 적용하면 해당 대상은 브랜치를 바꾸려면 PR을 열어야 하고, 그 PR을 병합할 때만 보호 규칙을 우회할 수 있다. 직접 push까지 허용하는 Always allow와 다른 점이다.

Always allow는 직접 push와 PR 병합 모두 가능, For pull requests only는 PR을 열어야만 우회해 병합 가능Always allowFor pull requests only관리자가 main을 바꾸려 한다Bypass 옵션직접 push 가능PR을 열어야 한다그 PR은 규칙을 우회해 병합
Bypass 옵션에 따라 관리자의 main 변경 경로가 갈린다 (보라 = 사람 · 초록 = 외부 · 회색 = 조건)

해결 방법

문서의 「Creating a branch ruleset」 절차를 따른다. Ruleset은 저장소 Settings에서 만든다.

1. 새 branch ruleset 만들기

  1. 저장소 메인 화면에서 Settings를 누른다. 보이지 않으면 More 드롭다운을 쓴다.
  2. 왼쪽 사이드바 「Code, planning, and automation」 아래 Rulesets를 누르고, 한 번 더 Rulesets를 누른다.
  3. New ruleset → New branch ruleset을 누른다.
  4. 「Ruleset name」에 이름을 적는다. 예: protect-main.
  5. enforcement status 드롭다운에서 Active를 고른다. 기본값은 Disabled(적용 안 됨)다.

2. 대상 브랜치 지정

「Target branches」에서 Add a target을 눌러 기본 브랜치를 포함하도록 지정한다. 브랜치 이름 패턴은 fnmatch로 일치시킨다. *는 /를 포함하지 않으므로 qa/*는 qa/foo에는 일치하지만 qa/foo/bar에는 일치하지 않는다.

3. PR 필수 규칙 켜기

「Branch protections」에서 Require a pull request before merging을 켠다. 이 규칙에는 다음 옵션이 있다(공식 문서 기준).

  • Required approvals: 병합 전 필요한 승인 수.
  • Dismiss stale approvals: PR diff가 바뀌면 기존 승인을 취소한다.
  • Require review from Code Owners: 코드 소유자가 있는 파일을 바꾸면 그 소유자의 승인이 필요하다.
  • Require approval of the most recent reviewable push: 마지막으로 push한 사람이 아닌 다른 사람의 승인이 필요하다.
  • 병합 방식 지정: merge·squash·rebase 중 허용할 방식을 정한다.

함께 쓸 만한 규칙으로 Restrict deletions와 Block force pushes가 있다. 문서는 둘 다 기본으로 켜져 있다고 설명한다. Block force pushes가 켜져 있으면 bypass 권한이 없는 한 조직 소유자와 저장소 관리자도 기본 브랜치를 바꾸거나 이름을 바꿀 수 없다.

CI 통과를 병합 조건으로 걸려면 Require status checks to pass before merging을 쓴다. 상태 검사 이름을 입력해 추가하고, Require branches to be up to date before merging은 상태 검사를 정의했을 때만 효력이 있다.

4. 관리자를 bypass에 추가하되 PR로 제한

  1. 「Bypass list」에서 Add bypass를 누른다.
  2. 「Add bypass」 대화상자에서 대상을 검색해 「Suggestions」에서 고르고 Add Selected를 누른다. 대상은 저장소 역할(관리자 등), 팀, GitHub App이다.
  3. 추가된 대상 오른쪽 「Always allow」 옆의 케밥 아이콘을 누르고 For pull requests only를 고른다.
  4. 맨 아래 Create를 누른다.

5. 병합하기

main에 직접 push하는 대신 작업 브랜치를 push하고 PR을 연다. 규칙을 아직 통과하지 못한 PR을 관리자가 병합하는 것이 bypass에 해당한다.

확인

Settings → Rules → Rulesets 목록에서 만든 Ruleset이 Active인지 본다. 그다음 테스트 브랜치에서 main으로 직접 push해 거부되는지, 같은 변경을 PR로 열어 관리자 권한으로 병합되는지 본다.

검증 범위: 메뉴 경로, 옵션 이름, bypass 동작, 기본 켜짐 규칙은 GitHub 공식 문서로 대조했다. 위 push·병합 동작은 GitHub 계정과 저장소가 필요해 러너에서 실행하지 않았다. 러너에서는 Ruleset 설정을 JSON으로 정리한 파일의 구조만 확인했다.

CI 실행 결과 · 5/5 단계 성공
검증 환경 4항목
OSUbuntu 24.04.5
jq1.7
실행 날짜2026-10-09
작성자 기재 환경GitHub Docs (docs.github.com) 문서 대조
[PASS] Ruleset 설정 JSON이 만들어졌다
[PASS] enforcement가 active다
[PASS] 대상이 branch다
[PASS] pull_request 규칙이 있다
[PASS] bypass가 pull_request 전용이다
이 결과는 글의 명령어를 GitHub Actions의 깨끗한 환경에서 그대로 실행해 자동으로 붙인 것입니다.

주의

  • Enforcement status 기본값은 Disabled다. Active로 바꾸지 않으면 규칙이 적용되지 않는다.
  • Bypass를 Always allow로 두면 해당 대상은 PR 없이 main에 직접 push할 수 있다. PR만 거치게 하려면 For pull requests only를 고른다.
  • Ruleset과 기존 branch protection rule이 함께 있으면 모두 적용되고 충돌 시 더 엄격한 쪽이 적용된다. 기존 규칙이 남아 있는지 함께 본다.
  • 문서에 따르면 Ruleset은 저장소당 최대 75개다. 공개 저장소는 GitHub Free에서도 쓸 수 있고, 비공개 저장소는 Pro·Team·Enterprise Cloud 플랜에서 쓸 수 있다.
  • 봇이 만든 PR에서 필수 검사가 돌지 않는 문제는 GitHub Actions PR이 다른 워크플로를 트리거하지 않을 때 (GITHUB_TOKEN과 GitHub App 토큰)에 있다.

자주 묻는 질문

Ruleset과 branch protection rule 중 무엇을 써야 하나?

문서가 설명하는 차이는 다음과 같다. Ruleset은 한 브랜치에 여러 개를 동시에 적용할 수 있고, 삭제하지 않고 적용 상태를 바꿀 수 있으며, 읽기 권한이 있는 사람이 active ruleset을 볼 수 있다. 커밋 메시지·작성자 이메일 같은 메타데이터도 제한할 수 있다. 이런 기능이 필요하면 Ruleset이 맞다.

bypass에서 「For pull requests only」와 「Always allow」는 무엇이 다른가?

「Always allow」는 직접 push와 PR 병합 모두 허용한다. 「For pull requests only」는 PR을 열어야 하고, 그 PR을 병합할 때만 규칙을 우회한다. 추가한 대상 옆 케밥 아이콘에서 바꾼다.

규칙을 켜기 전에 영향을 시험해 볼 수 있나?

문서가 설명하는 enforcement status는 Active와 Disabled 둘이다. Evaluate는 메타데이터 제한의 영향을 미리 보는 용도로 한 번 언급될 뿐이라 이 글에서는 다루지 않는다.

참고 자료