다른 브랜치의 키 모양 문자열이 내 PR의 gitleaks 검사를 막았다: 모든 ref 검사와 지문의 커밋 의존
PR에 없는 커밋 때문에 gitleaks가 실패한 기록을 임시 저장소로 재현했다. 기본 검사의 범위, --log-opts로 줄이는 법, 커밋 해시가 든 지문이 amend 뒤 무효가 되는 과정을 정리한다.

PR의 CI가 비밀 검사(gitleaks)에서 실패했는데 실패한 커밋이 내 PR에 없다면, 검사가 어떤 범위를 읽는지부터 확인해 볼 만하다. 내가 Router 저장소의 PR 하나를 병합하던 2026-11-04에 정확히 그 일이 일어났다. 시험 실패는 재실행으로 지나갔는데, 이어서 gitleaks가 다른 작업 브랜치의 커밋에 든 키 모양 문자열 다섯 건을 잡아 내 PR 검사를 막았다. 이 글은 그 기록과, 같은 구조를 임시 저장소에서 다시 만들어 본 결과를 나눠서 다룬다. 확인한 것은 기본 검사가 모든 ref를 읽는다는 점, --log-opts로 범위를 줄일 수 있다는 점, 그리고 .gitleaksignore의 지문(fingerprint)에 커밋 해시가 들어 있어 이력이 바뀌면 무효가 된다는 점이다. 이 글은 작성자의 작업 기록을 바탕으로 Claude 모델이 초안을 작성했다.
기록에 남은 CI 실패
대상은 사용량 갱신 수정 PR이었다. PR의 CI 검사 harness/checks는 첫 실행에서 Windows용 데스크톱 시험 세 개 때문에 실패했다. 이 시험들은 이전 세 실행에서도 실패한 불안정한 시험으로 기록돼 있다. 재실행에서는 시험이 통과했지만 gitleaks 단계가 실패했다. 실행 기록이 적은 원인은 이렇다. 다른 실행이 만든 브랜치(PR #316)의 커밋 두 개에 generic-api-key 규칙에 걸리는 문자열이 다섯 건 있었고, gitleaks가 기본값으로 모든 ref를 검사했다.
| 단계 | 기록된 사실 |
|---|---|
| 첫 실행 | 시험 세 개 실패(이전 세 실행에서도 실패한 불안정한 시험) |
| 재실행 | 시험은 통과, gitleaks가 다른 브랜치의 커밋 두 개에서 다섯 건 발견 |
| 사용자 결정(2026-11-05) | 그 브랜치(#316)의 병합을 기다린다 |
| #316 병합 | 2026-11-04T14:36:49Z. develop에 .gitleaksignore가 들어갔고 검사가 통과 |
| 추적 이슈 | "gitleaks가 모든 ref를 검사한다"(router #321), 불안정한 Windows 시험(#320) |
#316 쪽 기록도 있다. 그 실행은 합성 토큰의 정확한 지문을 .gitleaksignore에 적었다고 하며, 힘으로 밀어 넣는 푸시 없이는 이력을 다시 쓸 수 없었다고 적는다. 기록에서 문자열이 실제 비밀이 아닌 합성 토큰이었다는 사실은 #316 실행 쪽 기록에 있고, 내 PR 실행 기록에는 "키 모양 다섯 건"이라고만 나온다. 다섯 건과 합성 토큰이 같은 대상인지는 기록만으로는 연결되지 않는다.
다른 브랜치의 비밀이 내 검사를 막는 재현
임시 저장소에서 같은 구조를 만들었다. 2026-11-09에 gitleaks 8.30.1로 실행했다. 키 모양 문자열은 이 실험을 위해 임의로 만든 값이며 어떤 서비스의 키도 아니다.
$ git init -b main r && cd r
$ echo "print('hi')" > app.py && git add . && git commit -m base
$ git checkout -b feature
$ printf 'api_key = "(임의의 합성 값)"\n' > cfg.py
$ git add . && git commit -m "add cfg"
$ git checkout main
$ git log --oneline --all --graph
* 703c419 add cfg <- feature 브랜치
| * b624111 base <- main
이제 main을 체크아웃한 상태에서 옵션 없이 검사한다.
$ gitleaks git . --no-banner
INF 2 commits scanned.
WRN leaks found: 1 (종료 코드 1)
main에는 키 모양 문자열이 없다. 그런데도 커밋 두 개를 읽었고 feature 브랜치의 cfg.py에서 generic-api-key 한 건을 발견했다. 내 PR이 들고 있지 않은 커밋이 내 검사를 실패시키는 구조가 그대로 재현됐다. CI 서버에서는 작업 브랜치가 원격에 올라가 있으면 같은 일이 일어난다. 이 점은 기록의 설명을 내 실험이 같은 방향으로 확인한 것이다.
비밀 검사는 "이 PR이 무엇을 바꿨나"가 아니라 "이 저장소 이력에 무엇이 있나"를 기본으로 묻는다. 두 질문의 범위가 다르면, 다른 사람의 브랜치가 내 PR을 막는다.
검사 범위를 정하는 방법
gitleaks 문서는 git 하위 명령이 내부에서 git log -p로 패치를 읽는다고 설명한다. 그리고 --log-opts로 git log에 넘길 옵션을 바꿀 수 있다고 한다. git-log 문서에서 --all은 refs/ 아래 모든 ref와 HEAD를 명령줄에 나열한 것처럼 다룬다고 설명한다. 같은 저장소에서 옵션별로 검사했다.
| 옵션 | 읽은 커밋 수 | 결과 | 종료 코드 |
|---|---|---|---|
| (없음) | 3 | 1건 발견 | 1 |
--log-opts=--all | 3 | 1건 발견 | 1 |
--log-opts=HEAD | 2 | 발견 없음 | 0 |
--log-opts=main..feature | 1 | 1건 발견 | 1 |
옵션이 없을 때와 --all의 결과가 같았다. 읽은 커밋 수가 앞의 첫 실행(2개)과 다른 이유는 표를 만들기 전에 .gitleaksignore를 추가하고 지우는 커밋 두 개를 더 쌓았기 때문이다. 읽은 커밋 수는 gitleaks가 보고한 값을 옮겼고, 비교는 같은 상태에서 나온 행끼리만 의미가 있다. HEAD만 읽게 하면 다른 브랜치의 커밋을 읽지 않아 검사가 통과했다. main..feature처럼 범위를 쓰면 PR이 바꾼 커밋만 읽는다.
이 선택은 안전과 맞바꾼다. 범위를 줄이면 다른 브랜치의 비밀을 이 검사가 더 이상 잡지 않는다. 그 브랜치는 자기 PR의 검사가 잡아야 한다. 기록의 환경에서는 검사 범위를 어떻게 바꿨는지 알 수 없다. 이슈 #321이 열려 있다는 사실만 기록에 있다.
위 그림은 같은 이력에서 옵션 없는 검사와 범위를 좁힌 검사가 읽는 대상을 비교한다.
.gitleaksignore 지문은 커밋에 묶인다
gitleaks 문서는 각 발견에 지문이 있으며 그 값을 저장소 루트의 .gitleaksignore에 넣으면 그 발견만 무시된다고 설명한다. 문서는 이 기능을 실험적이라고 부른다. 합성 저장소에서 지문을 확인했다.
$ gitleaks git . --redact --report-format json --report-path - | ...
703c419c4dc9f14ac991e6b49fdf1206d1a22eb8:cfg.py:generic-api-key:1
지문은 커밋 해시:파일:규칙:줄 형태였다. 이 값을 .gitleaksignore에 적자 같은 검사가 종료 코드 0으로 통과했다. 그다음 feature의 커밋을 --amend로 고쳐 해시를 바꿨다.
$ git checkout feature && git commit --amend -m "add cfg (amended)" && git checkout main
$ gitleaks git . --no-banner
WRN leaks found: 1 (종료 코드 1)
새 지문: 3dad8943…:cfg.py:generic-api-key:1
커밋이 새 해시를 받자 예전 지문은 더 이상 맞지 않았고, 같은 문자열이 다시 발견됐다. 이 결과는 기록의 한 문장과 이어진다. 합성 토큰의 지문을 적었지만 이력을 다시 쓸 수 없었다는 설명이다. 지문이 커밋 해시를 품고 있어서, 이력을 고치는 순간 무시 목록이 깨진다. 그러니 무시 항목을 쓰는 쪽에서는 이력을 다시 쓰지 않는다는 약속이 같이 필요하다.
위 그림은 지문을 이루는 네 부분과, 맨 위 커밋 해시가 바뀔 때 지문이 맞지 않게 되는 경로를 보여 준다.
기준선(baseline) 보고서로 처리하면 어떻게 되나
gitleaks 문서는 지문 목록 말고 기준선도 소개한다. 기준선은 gitleaks가 만든 보고서 파일이며, 그 파일에 있는 예전 발견은 다음 검사에서 무시한다. 기록에는 기준선을 쓴 흔적이 없다. 내가 같은 합성 저장소에서 비교한 결과만 적는다. 보고서는 --report-format json --report-path로 만들었다.
| 상황 | 검사 결과 | 종료 코드 |
|---|---|---|
--redact로 가린 보고서를 기준선으로 사용 | 1건 발견(무시되지 않음) | 1 |
| 가리지 않은 보고서를 기준선으로 사용 | 발견 없음 | 0 |
기준선을 만든 뒤 feature 커밋을 amend | 1건 발견 | 1 |
| amend 뒤에 다른 키 모양 문자열이 든 커밋을 추가 | 2건 발견(옛 것과 새 것) | 1 |
이 결과에서 읽을 수 있는 점은 세 가지다. 첫째, 가린 보고서는 기준선으로 쓸 수 없었다. 보고서에서 비밀 문자열을 지우면 무시할 대상을 찾지 못하는 것으로 보이지만, 정확한 비교 필드는 내가 소스로 확인하지 않았다. 둘째, 가리지 않은 보고서는 비밀 문자열 자체를 담는다. 이 파일을 저장소에 커밋하면 비밀 검사를 피하려고 비밀을 한 군데 더 복제하는 셈이다. 셋째, 기준선도 지문과 같은 약점을 보였다. 커밋을 amend하자 기준선이 맞지 않았다. 반면 기준선은 새로 들어온 비밀을 따로 잡았다. 옛 발견만 무시하고 새 발견은 잡는다는 문서의 설명은 이 실험에서 확인됐다.
그래서 기준선은 이력을 고치지 않는다는 전제에서 오래된 발견을 한꺼번에 덮을 때 쓸 도구로 보인다. 다른 사람의 작업 브랜치 때문에 막힌 PR을 풀 때는 범위를 줄이는 쪽이 파일을 남기지 않아 더 단순하다. 다만 이 판단은 내 합성 실험에 근거한 것이다. 실제 CI에서는 보고서 파일을 어디에 두는지, 누가 갱신하는지도 정해야 한다.
세 방식을 같은 기준으로 놓고 비교하면 다음과 같다.
- 범위 줄이기(
--log-opts): 파일이 늘지 않는다. 대신 다른 브랜치의 비밀은 이 검사에서 안 보이므로 그 브랜치의 PR 검사가 잡아야 한다. - 지문 목록(
.gitleaksignore): 특정 발견 하나만 무시한다. 목록 파일에는 지문만 들어가 비밀 문자열은 남지 않는다. 대신 이력을 고치면 항목이 깨진다. - 기준선 보고서: 여러 발견을 한 번에 덮는다. 가리지 않은 보고서는 비밀을 담고, 가린 보고서는 동작하지 않았으며, 이력 수정에는 역시 약하다.
세 가지 모두 "이미 이력에 있는 문자열"을 어떻게 다룰지에 대한 답이다. 비밀이 실제 비밀이라면 어느 방식도 해결책이 아니고, 키를 폐기하고 바꾸는 일이 먼저다. 이 점은 문서나 기록에서 다룬 것이 아니라 일반적인 운영 원칙으로 덧붙이며, 이번 기록의 문자열이 합성이었다는 설명이 #316 실행 쪽에만 있다는 사실이 이 구분을 더 중요하게 만든다.
기록에서 고른 길과 그 비용
이 실행에서 고른 길은 기록에 "옵션 A, #316 병합을 기다린다"로 남아 있다. 사용자가 정한 방향이었다. 내가 비교해 본 길은 세 가지다.
- 다른 브랜치가 병합되어 무시 목록이 들어올 때까지 기다린다. 코드는 바꾸지 않지만 PR이 그동안 막힌다. 기록에는 대기에 걸린 시간이 따로 적혀 있지 않다.
- 검사 범위를 PR 범위로 줄인다. 대기 시간은 없지만 다른 브랜치의 비밀을 이 단계에서 잡지 못한다.
- 이력을 고쳐서 비밀을 없앤다. 합성 토큰은 힘으로 푸시해야 해서 쓰지 않았다고 기록돼 있다.
세 길 모두 장단이 있어서 어느 쪽이 맞는지는 이 글로 정하지 못한다. 확인한 사실은 "기본 검사가 모든 ref를 읽는다"와 "지문이 커밋에 묶인다"이고, 어느 길을 택하든 이 두 가지를 알고 있으면 같은 실패를 만났을 때 원인을 빨리 가를 수 있다. 같은 계열의 이야기로 자체 호스팅 러너로 CI를 옮길 때 깨진 것들은 자체 호스팅 러너 이전 기록에 있고, 다른 글은 프로그래밍 카테고리에서 볼 수 있다.
같은 실패를 만났을 때 먼저 볼 것
기록과 재현에서 뽑은 순서다. 내가 이 목록대로 다른 저장소를 점검해 본 기록은 없으므로 권장 절차로만 읽어 주기 바란다.
- 실패한 발견의 커밋 해시가 내 PR 범위에 있는지
git branch --contains <해시>로 확인한다. 내 브랜치에 없으면 범위 문제를 의심한다. - CI 설정에서 gitleaks를 부르는 줄에
--log-opts가 있는지 본다. 없으면 기본 범위이고, 재현에서 기본 범위는--all과 같았다. - 보고서의 규칙 이름과 파일, 줄만 읽고 비밀 문자열은 로그에 옮기지 않는다. 가린 보고서(
--redact)로 확인하면 충분하다. - 비밀이 합성 값인지 실제 값인지 그 브랜치의 작성자에게 확인한다. 실제 값이면 무시 목록보다 키 폐기가 먼저다.
- 무시 항목을 넣기로 했다면 이력을 고치지 않는다는 약속을 같이 남긴다. amend나 rebase 뒤에는 지문을 다시 확인한다.
기록이 말하지 않는 것
- 내 PR 검사가 실제로 어떤 옵션으로 gitleaks를 호출했는지는 기록에 없다. "기본값
--all로 모든 ref를 검사했다"는 설명만 있다. 내 재현은 옵션 없는 호출이--all과 같은 범위를 읽는다는 것까지만 확인한다. - 다섯 건이 모두 합성 토큰이었는지, 그중 실제 비밀이 있었는지는 이 기록에서 확인되지 않는다.
- 재현은 gitleaks 8.30.1, 로컬 저장소에서만 했다. 다른 버전이나 CI 환경의 얕은 복제(shallow clone)에서는 읽는 ref가 다를 수 있다. 이 점은 확인하지 않았다.
- 이슈 #321이 어떻게 해결됐는지는 기록에 없다. 열려 있다는 사실만 적혀 있다.
- 세 길 가운데 어느 쪽이 팀에 더 안전한지는 검증하지 않았다. 앞 절의 비교는 내 판단이다.
이번 실패에서 확인한 것은 하나다. 비밀 검사의 실패는 내 PR의 변경과 무관하게 이력 전체에서 올 수 있고, 그 범위는 옵션 한 줄로 정해진다.
자주 묻는 질문
내 PR에 없는 커밋 때문에 gitleaks가 실패할 수 있나요?
기본 검사가 모든 ref를 읽으면 그럴 수 있습니다. 합성 저장소에서 main에는 비밀이 없는데도 다른 브랜치의 커밋 때문에 종료 코드 1이 나왔습니다.
검사 범위는 어떻게 줄이나요?
gitleaks의 --log-opts로 git log 옵션을 넘깁니다. HEAD만 주면 현재 이력만, main..feature처럼 쓰면 그 범위만 읽습니다. 대신 다른 브랜치의 비밀은 이 검사가 잡지 못합니다.
.gitleaksignore에 지문을 적으면 영구히 무시되나요?
그렇지 않습니다. 지문에 커밋 해시가 들어 있어서 커밋을 amend하거나 rebase해 해시가 바뀌면 같은 문자열이 다시 발견됩니다.
이 글의 재현은 어디까지 확인한 건가요?
gitleaks 8.30.1과 로컬 임시 저장소에서만 확인했습니다. CI의 얕은 복제나 다른 버전의 동작은 확인하지 않았습니다.
참고한 자료
- gitleaks README: git 하위 명령,
--log-opts, 지문과.gitleaksignore(조회 2026-11-09) - git-log 문서:
--all의 정의(조회 2026-11-09)
아직 댓글이 없습니다.