API 키가 들어간 PR, push protection을 통과해도 머지를 막을 수 있을까

변경을 전달하기 전에 비밀 값이 포함됐는지 살피는 AI 생성 개념 이미지입니다.

API 키가 들어간 변경을 push했는데 오류가 없었다면, 그 PR도 안전하게 머지할 수 있을까요? push 검사와 PR의 머지 조건은 검사하는 시점과 대상이 다를 수 있습니다. push가 성공했다는 사실 하나만으로 비밀 값 검토를 끝내면 중간에 빠진 조건을 놓칠 수 있습니다.

비밀 값이 들어간 PR을 막으려면 push 시점 검사와 머지 직전 검사의 대상·상태를 각각 확인하세요.

GitHub의 2026년 9월 9일 발표는 PR이 도입한 secret scanning 경고가 해결되지 않았을 때 머지를 막는 ruleset 규칙을 소개합니다. 발표 기준으로 GitHub Secret Protection 또는 GitHub Advanced Security 고객 대상 public preview입니다. 일반 ruleset을 사용할 수 있다는 사실과 이 개별 보안 규칙의 지원 조건은 구분해야 합니다.

push와 merge는 서로 다른 지점에서 멈춥니다

push protection 안내는 비밀이 저장소에 들어오는 push 시점의 보호를 설명합니다. 이번 규칙은 그 뒤 PR을 대상 브랜치에 합치기 전에 별도의 조건을 확인하는 방식입니다.

예를 들어 팀이 특정 일반 패턴을 push protection의 차단 대상으로 설정하지 않았지만 PR 단계에서는 확인하고 싶다고 해보겠습니다. 앞 단계가 그 유형을 막지 않더라도, 해당 유형을 포함하도록 설정한 머지 규칙이 뒤에서 검사할 수 있습니다. 두 장치를 같은 기능의 중복이라고 보기 어려운 이유입니다.

물론 뒤에 검사가 있다고 처음부터 비밀을 올려도 되는 것은 아닙니다. 저장소에 들어온 뒤 머지를 막는 것과 저장소에 들어오지 못하게 하는 것은 노출 범위가 다릅니다. 실제 키로 검사 동작을 시험하는 방법을 권하는 글도 아닙니다.

규칙은 최신 커밋과 열린 경고를 함께 봅니다

공지에서 설명한 머지 조건은 두 가지입니다. PR의 head 커밋에 대한 secret scan이 완료되어야 하고, PR의 커밋이 도입한 비밀 값에 열린 경고가 없어야 합니다.

이 때문에 “경고 목록이 지금 비어 있다”만으로는 충분하지 않을 수 있습니다. 아직 최신 커밋의 검사가 끝나지 않았다면 그 빈 목록을 검사 완료 결과처럼 읽으면 안 됩니다. 반대로 검사가 끝났더라도 차단 대상 경고가 열려 있다면 해결할 일이 남은 것입니다.

head는 이 PR의 현재 마지막 커밋을 가리킵니다. 어제 통과한 커밋과 오늘 수정한 커밋이 다르다면, 어제의 결과를 오늘의 상태로 사용해서는 안 됩니다. PR의 변경 대상과 검사 결과가 같은 커밋에 연결되어 있는지 보는 습관이 필요합니다.

기본 차단 대상과 추가할 수 있는 패턴 종류도 확인해야 합니다. 발표는 provider patterns를 기본으로 설명하고 custom·generic 같은 다른 범주를 추가 구성할 수 있다고 안내합니다. “secret scanning을 켰다”는 요약만 남기면 실제로 어떤 유형을 막기로 했는지 알기 어렵습니다.

설정 전에 범위와 관리 권한을 정합니다

Rulesets 설명은 규칙의 대상과 활성 상태, 우회 권한을 다룹니다. 먼저 보호할 저장소와 브랜치를 정해야 합니다. main만 보호하려는지 릴리스 브랜치도 포함하는지에 따라 대상 설정이 달라집니다.

공지에서 안내하는 경로는 저장소·조직·엔터프라이즈 설정의 Repository → Rulesets에서 규칙을 만들거나 수정하는 것입니다. 대상 브랜치를 정한 뒤 Require secret scanning alerts are resolved 규칙을 선택합니다. 실제 계정의 지원 조건과 관리 권한이 있어야 가능한 작업이며, 이 글에서 설정을 변경한 것은 아닙니다.

적용할 때는 다음 항목을 한 번에 적어 두는 편이 좋습니다.

• 보호할 저장소와 브랜치
• 활성화한 비밀 값 규칙과 포함한 패턴 종류
• 규칙을 우회할 수 있는 사용자·역할·앱
• 경고를 조사하고 해결할 담당자
• 문제가 생겼을 때 확인할 PR과 현재 커밋

일반 ruleset의 이용 가능 범위만 보고 모든 보안 옵션이 제공된다고 추정하지 않습니다. 설정 화면에 규칙이 없거나 적용할 수 없다면, 공개 미리보기와 제품 구독·정책 조건부터 대조해야 합니다. 정확한 지원 범위를 확인하지 않은 채 임의의 API 값을 넣는 것으로 해결하려고 할 필요는 없습니다.

하나의 PR을 네 상태로 따라가 봅니다

가상의 문서 수정 PR에 실수로 인증 정보처럼 보이는 값이 추가됐다고 해보겠습니다. 아래는 동작을 설명하기 위한 상태 예시이며, 실제 비밀이나 PR을 생성한 기록은 아닙니다.

첫 상태는 최신 커밋의 스캔이 아직 진행 중인 경우입니다. 열린 경고가 보이지 않아도 이 규칙의 검토가 끝난 상태로 취급하지 않습니다. 무엇을 기다리는지 PR의 검사 상태와 연결해 봅니다.

두 번째는 스캔이 끝났고 차단 대상 경고가 열린 경우입니다. 개발자는 단순히 CI를 다시 실행하기보다 해당 경고의 위치와 유형을 읽어야 합니다. 실제 비밀인지, 예제 문자열인지, 누가 조치할 수 있는지를 구분해야 다음 행동을 정할 수 있습니다.

세 번째는 노출된 비밀을 처리하고 관련 경고도 해결한 경우입니다. 여기서는 비밀 규칙의 차단 사유가 해소됐는지 확인합니다. 그러나 코드 리뷰나 다른 필수 검사까지 자동으로 통과했다는 뜻은 아닙니다. PR에 적용되는 전체 조건은 별도로 남습니다.

네 번째는 그 뒤 새 커밋이 올라온 경우입니다. 이전 경고가 해결됐다는 사실을 유지하더라도 새로운 head에 필요한 스캔 완료 여부를 다시 봅니다. 수정 과정에서 다른 비밀이 들어갔는지도 새 변경의 범위에서 확인해야 합니다. 이처럼 상태를 나누면 “경고를 닫았는데 왜 아직 머지가 안 되지?”라는 질문도 좁힐 수 있습니다.

경고를 닫는 일과 키를 교체하는 일은 다릅니다

GitHub의 경고 해결 안내는 문제를 조치한 뒤 경고를 닫는 흐름을 설명합니다. 저장소에 노출된 비밀은 더는 안전하다고 가정하지 말고, 해당 제공자의 절차에 맞춰 무효화나 교체를 진행해야 합니다.

예를 들어 파일에서 키 문자열을 지운 새 커밋을 추가했다고 해보겠습니다. 현재 파일에서 보이지 않게 된 것과 그 키가 더 이상 사용할 수 없게 된 것은 다릅니다. 이전 기록이나 이미 복사된 값까지 새 커밋 하나가 없애 주는 것은 아닙니다.

반대로 키를 폐기했어도 GitHub의 경고가 자동으로 닫혔다고 가정하지 않습니다. 공식 안내는 파일에서 토큰을 제거하는 것만으로 경고가 자동 종료되지 않는다고 설명합니다. 경고의 해결 사유와 조치 내용을 기록해 상태를 정리해야 합니다.

실제 서비스가 그 인증 정보에 의존한다면 교체 과정의 영향도 고려해야 합니다. 어떤 서비스가 옛 값을 쓰는지 파악하고 담당자와 안전한 교체 순서를 맞춰야 합니다. 이 글은 특정 계정의 비밀을 폐기하는 명령이나 사고 대응의 완료 판정을 대신하지 않습니다.

우회 권한이 있다면 검토할 결과가 달라집니다

ruleset이 존재해도 특정 사용자의 머지는 허용될 수 있습니다. 규칙이 꺼져 있거나 대상 브랜치가 다를 수도 있고, 그 사용자에게 우회 권한이 있을 수도 있습니다. 한 번의 머지 성공만 보고 규칙이 고장 났다고 단정하지 않습니다.

팀의 목적이 일반 개발자의 위험한 변경을 막는 것이라면 우회 경로를 누가 어떤 사유로 사용할지 정해야 합니다. 모든 관리자를 편의상 예외로 두고도 “아무도 비밀이 있는 PR을 머지할 수 없다”고 보고하면 실제 정책보다 강한 주장입니다.

Rulesets는 여러 규칙이 같은 대상에 적용될 수도 있습니다. 비밀 규칙만 해제됐는데 다른 리뷰나 상태 검사 때문에 머지가 계속 막힐 수 있습니다. 문제를 해결할 때는 한 규칙의 상태와 전체 머지 가능 상태를 나눠 읽어야 합니다.

적용됐다는 보고에는 조건을 함께 남깁니다

설정 완료를 확인할 때는 활성 규칙의 이름뿐 아니라 대상 브랜치, 포함한 패턴, 우회 대상, 현재 PR 커밋과 검사 상태를 함께 봅니다. 경고가 있었던 경우에는 비밀 자체의 조치와 경고 상태 정리가 각각 끝났는지도 확인합니다.

이 글에서는 실제 저장소의 차단 동작이나 탐지율을 측정하지 않았습니다. 공개 발표의 지원 범위와 문서가 설명한 조건을 정리한 것입니다. 팀에 적용한다면 승인된 안전한 검증 방법으로 의도한 경로가 차단되는지와 정상 변경이 통과하는지를 따로 확인해야 합니다.

push 성공을 최종 안전 판정으로 사용하지 말고, PR의 현재 head 검사와 열린 경고, 예외 권한까지 연결해 보세요. 그러면 비밀 검사가 어느 시점에 무엇을 막았는지, 아직 어떤 조치가 남았는지를 정확하게 설명할 수 있습니다.