required check를 첫날부터 활성화하면 모든 PR이 중단될 수 있습니다

AI coding agent가 지속적으로 PR을 생성하는 repository에서는, CI나 GitHub App의 check를 required로 설정하여 merge 전 확인 누락을 줄이고 싶어집니다.

하지만 check를 추가한 당일에 바로 required로 전환하면, 다음과 같은 설정 실수로 인해 모든 PR이 중단될 수 있습니다.

• ruleset이 예상치 못한 branch에도 적용됨
• required로 설정한 check 이름과 실제로 보고된 check 이름이 다름
• 최신 commit에 check가 붙지 않고, Waiting for status to be reported 상태로 남음
• base branch 업데이트 시마다 재실행이 필요해짐
• GitHub App이나 workflow 장애 시 복구 방법을 모름

반면, advisory 상태로 방치하면 결과가 읽히지 않는 경우도 있습니다.

이 기사에서는 GitHub App이 내보내는 check를 예로 들어, advisory로 관찰한 후 GitHub Rulesets의 required status check로 승격하는 절차를 정리합니다. 특정 검사 로직이 아니라, GitHub 측의 설정, 검증, backout에 집중합니다.

check를 내보내는 주체와 merge를 막는 주체는 별개입니다

GitHub App이나 GitHub Actions는 check 상태를 보고합니다. 실제로 merge를 막는 것은 repository에 설정된 branch protection 또는 ruleset입니다.

GitHub App / GitHub Actions
└─ check를 최신 commit에 보고함
GitHub Rulesets / branch protection
...

이 분리를 먼저 이해해 두면, "App을 install했는데도 merge가 막히지 않는다", "App을 삭제해야만 merge할 수 있다"와 같은 오해를 피할 수 있습니다.

Rulesets는 기존의 branch protection과 병용할 수 있으며, 동일한 branch에 여러 ruleset이 적용될 수도 있습니다. 하나의 ruleset을 수정하더라도 다른 rule이 남아 있을 수 있으므로, 대상 branch에 적용 중인 rule 전체를 확인해야 합니다.

참고:

• GitHub Docs: About rulesets
• GitHub Docs: Available rules for rulesets

먼저 plan과 권한을 확인합니다

2026년 7월 시점의 GitHub Docs에 따르면, repository rulesets의 이용 범위는 다음과 같이 안내되어 있습니다.

ruleset을 생성 또는 편집하려면 repository의 admin 권한, 또는 edit repository rules 권한을 가진 custom role이 필요합니다. active한 ruleset은 해당 repository에 대한 read 권한이 있는 사람도 확인할 수 있습니다.

GitHub의 UI, plan, organization policy는 변경될 수 있습니다. 설정 전에 자신의 repository에서 Settings > Rules > Rulesets를 이용할 수 있는지, 공식 문서와 실제 화면을 확인하십시오.

Phase 1: 우선 1개의 repository에서 advisory 운영하기

첫 관찰 기간에는 branch protection이나 rulesets를 변경하지 않습니다. GitHub App을 선택된(selected) repository 1개에 install하고, 작은 PR을 열어 check가 안정적으로 전달되는지 확인합니다.

확인 항목은 5가지입니다.

• PR을 열었을 때 check가 생성되는가
• PR branch로 push할 때마다 최신 commit SHA로 check가 업데이트되는가
• check가 나오지 않는 상태를 성공으로 간주하지 않는가
• maintainer가 각 상태의 의미와 다음 조작을 설명할 수 있는가
• 장애 발생 시 ruleset을 되돌릴 수 있는 권한자와 연락 경로가 결정되어 있는가

관찰 기간은 repository의 PR 양에 맞춥니다. 예를 들어 1주일 동안 관찰했더라도 PR이 1개뿐이라면, 일수보다는 「일반적인 PR」, 「업데이트된 PR」, 「중단해야 할 상태」의 각 케이스를 확인했는지를 우선합니다.

이 단계에서 GitHub의 Checks 란에 표시되는 정확한 check 명칭과, check를 보고한 GitHub App을 기록합니다. required status check의 후보로 올리려면, 해당 check가 동일한 repository에서 최근 7일 이내에 성공한 상태여야 합니다.

Phase 2: required로 격상할 조건을 결정하기

「유용한 warning이 1회 발생했다」는 이유만으로 required로 격상하지 않고, 다음 조건을 충족한 뒤에 판단합니다.

Phase 3: repository ruleset에 추가하기

GitHub 화면은 업데이트될 수 있으므로, 아래 내용은 항목명이 아니라 설정 의도를 확인하기 위한 절차입니다.

• Repository의 Settings > Rules > Rulesets를 엽니다.
• default branch를 대상으로 하는 branch ruleset을 신규 생성하거나, 기존 ruleset을 편집합니다.
• 대상 branch의 pattern이 의도대로인지 확인합니다.
• Require status checks to pass before merging를 활성화합니다. advisory 기간에 확인한 정확한 check 명칭을 추가합니다.
• 선택 가능한 경우, expected source로서 실제로 check를 발생시킨 GitHub App을 지정합니다.
• Require branches to be up to date before merging를 사용할지 결정합니다.
• 저장 후, 새로운 commit을 push한 PR에서 merge box를 확인합니다.

expected source를 지정하면, 동일한 이름의 check를 다른 사용자나 integration이 보고하더라도 required 조건을 충족하지 않습니다. 이름뿐만 아니라 누가 보고한 check인지까지 고정하고 싶을 때 사용합니다.

strict와 loose를 의식하기

Require branches to be up to date before merging를 활성화하는 strict 설정에서는, topic branch를 base branch의 최신 상태로 추종시킨 후 merge합니다. 다른 PR이 먼저 merge되면 업데이트와 check 재실행이 증가합니다.

비활성화하는 loose 설정에서는 재실행은 줄어들지만, 최신 base branch와 조합된 상태를 확인하지 않고 merge할 수 있는 여지가 있습니다.

어느 쪽을 선택할지는 PR 양, check 실행 시간, merge queue의 유무, base branch 업데이트 빈도에 따라 달라집니다. AI agent가 다수의 PR을 업데이트하는 repository에서는, strict를 활성화했을 때의 재실행 횟수도 관찰 대상으로 삼습니다.

Phase 4: 「통과」와 「중단」을 모두 테스트하기

설정 후에는 성공 케이스뿐만 아니라, 중단되는 케이스까지 확인합니다.

통과하는 케이스

• 일반적인 PR에 새로운 commit을 push합니다.
• 최신 SHA에 check가 붙는 것을 확인합니다.
• check가 성공한 후, merge box의 required 조건이 충족되는 것을 확인합니다.

중단되는 케이스

• 확인이 필요한 테스트용 PR을 준비합니다.
• check가 required 조건을 충족하지 못해 merge box가 중단되는 것을 확인합니다.
• 원인을 해소하고, 동일한 PR의 최신 SHA에서 check가 업데이트되는 것을 확인합니다.
• 업데이트 후 merge 가능 상태로 돌아가는 것을 확인합니다.

Veripsa Core를 사용하기 위해 해시 입력이나 채팅을 통한 ACK 운영을 추가할 필요는 없습니다. Core가 제공하는 것은 merge 전의 확인 자료이며, required화나 예외 판단은 GitHub Rulesets 측의 설정입니다. missing check나 pending 상태의 해소에는 ruleset 수정 또는 backout을 사용합니다.

Waiting for status to be reported에서 확인하는 위치

required check가 pending 상태로 남아 있다면, 순차적으로 원인을 파악합니다.

• 최신 SHA인가 — 이전 커밋(commit)에 붙은 성공적인 check는 최신 커밋의 required 조건을 충족하지 못합니다.
• check 이름이 일치하는가 — workflow job, reusable workflow, GitHub App에 따라 표시 이름의 형식이 다를 수 있습니다.
• expected source가 일치하는가 — 다른 App이나 user가 생성한 동일한 이름의 check로는 충족되지 않는 설정이 있습니다.
• ruleset의 대상 branch인가 — default branch 이외의 곳에 잘못 적용했거나, 반대로 대상에서 누락되지 않았는지 확인합니다.
• event가 전달되는가 — PR 업데이트, fork로부터의 PR, merge queue 등 실제로 사용하는 경로마다 check가 보고되는지 확인합니다.
• 다른 rule도 적용 중인가 — branch protection이나 다른 ruleset이 동시에 merge를 막고 있지는 않은지 확인합니다.

GitHub Actions의 workflow를 required로 설정할 경우, workflow 전체가 path filter나 branch filter에 의해 skip되면 pending 상태로 남을 수 있습니다. 이는 job 단위의 skip과는 동작 방식이 다르므로, GitHub App의 check와 동일한 방식으로 취급하지 않는 것이 안전합니다.

자세한 조건은 GitHub Docs의 Troubleshooting required status checks에서 확인할 수 있습니다.

backout은 uninstall이 아니라 enforcement를 되돌리는 것

required 설정 직후에 PR이 계속 막힌다면, 우선 enforcement를 advisory로 되돌립니다.

• 대상 ruleset을 일시적으로 disable 하거나, 문제가 되는 required check만 제거합니다.
• 동일한 branch에 적용되는 branch protection 및 다른 ruleset도 확인합니다.
• GitHub App의 check/comment는 유지하며, advisory 상태로 관찰을 계속합니다.
• check 이름, 대상 branch, latest SHA, expected source 중 어디에서 실패했는지 기록합니다.
• 수정 후, 통과하는 케이스와 막히는 케이스를 재검증한 뒤에 required로 되돌립니다.

비상시를 대비해 모든 인원에게 영구적인 bypass 권한을 부여하면, 평상시에도 rule을 우회할 수 있게 됩니다. backout 담당자와 조건을 정하고, 필요한 rule만 되돌리는 것이 원인 파악에 용이합니다.

Veripsa Core로 테스트할 경우

Veripsa Core는 open PR 간의 중첩이나 도착 순서를 GitHub check 및 PR comment로 출력합니다. App 단독으로는 merge를 막지 않으며, 이를 required로 만들지는 repository owner가 GitHub 측에서 결정합니다.

일반적인 이용 시 수동 ACK나 스냅샷 해시(snapshot hash) 입력을 요구하지 않습니다. 처음에는 선택된 단일 repository(selected repository) 하나에 대해 advisory 방식으로 운영하며, check가 안정적으로 전달되는지, 결과를 maintainer가 읽을 수 있는지, 그리고 backout이 가능한지를 확인한 후 required 단계로 진행합니다.

Discussion