GitHub·GitLab 저장소에 올린 비밀키, 스캐너로 찾아 막는 무료 설정법 (2026년)

GitHub·GitLab 저장소에 비밀키를 올렸을 때 무료 스캐너로 찾아 막는 방법은 생각보다 간단합니다. 공개 저장소라면 GitHub 설정을 확인하는 것으로 끝나는 경우가 많고, 비공개 저장소나 GitLab이라면 무료 도구인 Gitleaks를 붙이면 됩니다. 아래에서 어떤 기능이 어느 플랜까지 무료인지, 이미 올라간 키를 어떻게 처리하는지 순서대로 정리했습니다.

GitHub와 GitLab, 무료로 어디까지 막아줄까

비밀키 스캔은 시크릿 스캐닝(secret scanning)이라고 부르며, 저장소에 들어간 API 키·토큰·비밀번호 같은 자격 증명을 패턴으로 찾아내는 기능을 말합니다. 두 플랫폼 모두 기능은 있지만, 무료로 쓸 수 있는 범위가 서로 다릅니다.

GitHub는 공개(public) 저장소에서 시크릿 스캐닝과 푸시 보호(push protection)를 무료로 제공합니다. 별도 라이선스나 설정 없이 기본으로 켜지고, 2026년 3월 기준으로 39개 탐지기에 푸시 보호가 기본 적용됐습니다. Airtable, Databricks, Heroku, PostHog, Shopify 같은 서비스의 키가 여기에 포함됩니다. 같은 달 GitHub는 시크릿 탐지기 37개를 새로 추가했고, 스캔 범위를 AI 코딩 에이전트까지 넓혔습니다.

비공개·내부 저장소는 사정이 다릅니다. GitHub Team이나 Enterprise Cloud에서 Secret Protection을 켜야 하고, 활성 커미터 1인당 월 $19입니다. 2025년 4월에 커미터당 $49였던 기존 번들이 Secret Protection($19)과 Code Security($30)로 분리되면서 시크릿 기능만 따로 살 수 있게 됐습니다.

GitLab은 두 기능이 갈립니다. CI/CD 파이프라인에서 도는 secret_detection 작업은 Free·Premium·Ultimate 모든 등급에서 쓸 수 있습니다. 반면 푸시하는 순간 막아주는 시크릿 푸시 보호는 Ultimate 등급 전용입니다.

결론적으로 개인 프로젝트나 오픈소스라면 GitHub 기본 기능만으로 충분한 경우가 많습니다. 비공개 저장소를 무료로 지키고 싶다면 GitHub든 GitLab이든 로컬 훅과 CI에서 도는 오픈소스 스캐너가 사실상 유일한 선택지입니다.

GitHub와 GitLab, 무료로 어디까지 막아줄까 실시간 확인하기

저장소 설정으로 켜는 방법, 이미 푸시된 기록 검사까지

GitHub에서는 저장소의 Settings로 들어가 Code security 항목에서 Secret scanning과 Push protection을 켭니다. 공개 저장소는 이미 켜져 있을 가능성이 높으니 상태만 확인하면 됩니다. 켜면 새로 푸시하는 내용뿐 아니라 저장소의 기존 git 기록도 함께 스캔되고, 발견된 항목은 Security 탭의 알림 목록에 쌓입니다.

푸시 보호가 작동하면 탐지된 시크릿이 들어간 푸시가 서버에서 거부됩니다. 이때 사용자는 "테스트용이다", "오탐이다", "나중에 고치겠다" 같은 사유를 골라 우회할 수 있고, 그 기록이 남습니다. 우회는 편하지만 그만큼 실수도 통과하기 쉬우므로, 진짜 키라면 우회하지 말고 코드에서 빼는 편이 안전합니다.

GitLab은 .gitlab-ci.yml에 템플릿 한 줄을 추가하는 방식입니다.

include:
  - template: Security/Secret-Detection.gitlab-ci.yml

variables:
  SECRET_DETECTION_HISTORIC_SCAN: "true"

기본 상태에서는 커밋 변경분 위주로 검사합니다. 위처럼 SECRET_DETECTION_HISTORIC_SCAN을 "true"로 두면 전체 git 기록을 한 번 훑어 과거에 묻힌 키까지 찾아냅니다. 기록이 긴 저장소는 시간이 걸리므로 처음 한 번만 켜고, 결과를 확인한 뒤 끄는 방식이 무난합니다.

GitHub·GitLab 시크릿 스캔 설정 절차 확인하기

Gitleaks·TruffleHog로 커밋 전에 막는 무료 pre-commit 설정

플랫폼 기능이 닿지 않는 비공개 저장소에서는 오픈소스 스캐너가 대안입니다. 대표 도구는 Gitleaks와 TruffleHog이고, 두 저장소의 GitHub 스타 수를 합하면 5만 1천 개가 넘습니다. 성격은 이렇게 다릅니다.

2026년에 자주 권장되는 조합은 세 겹입니다. 커밋 직전 pre-commit에서 Gitleaks, PR마다 CI에서 Gitleaks, 전체 git 이력은 주 1회 예약 스캔으로 돌리는 구성입니다. CI 단계에 TruffleHog를 얹는 변형도 있습니다.

로컬 pre-commit 훅 만들기

Gitleaks를 설치한 뒤 저장소의 .git/hooks/pre-commit 파일에 아래 내용을 넣고 실행 권한을 주면 됩니다. 스테이징된 변경분만 검사하므로 커밋 속도에 부담이 크지 않습니다.

#!/bin/sh
gitleaks git --pre-commit --staged --redact -v

비밀키가 발견되면 종료 코드가 0이 아니므로 커밋이 중단됩니다. --redact는 터미널 출력에서 키 값을 가려 주는 옵션입니다. 명령어 이름은 버전에 따라 바뀐 적이 있으니(구버전은 protect --staged), 설치한 버전의 gitleaks --help로 한 번 확인하세요. 이미 쌓인 기록 전체를 검사할 때는 저장소 루트에서 gitleaks git -v를 실행합니다.

Gitleaks·TruffleHog로 커밋 전에 막는 무료 pre-… 바로가기

실수로 올린 키를 폐기하고 기록에서 지우는 순서

스캐너가 키를 찾았다면 가장 먼저 할 일은 기록 삭제가 아니라 키 폐기(rotate)입니다. 공개 저장소에 올라간 키는 자동 수집 봇이 금세 긁어 가기 때문에, 커밋을 지워도 이미 복사됐을 수 있다고 가정해야 합니다. 순서는 다음과 같습니다.

1. 해당 서비스 콘솔에서 유출된 키를 폐기하고 새 키를 발급한다.
2. 새 키는 코드가 아닌 환경 변수나 CI 시크릿 저장소에 넣는다.
3. 서비스의 사용 로그에서 유출 시점 이후 의심스러운 호출이 있었는지 확인한다.
4. 그다음에야 git 기록에서 해당 파일이나 문자열을 제거한다.
5. 정리 후 전체 이력 스캔을 다시 돌려 남은 것이 없는지 확인한다.

기록 제거에는 보통 git filter-repo나 BFG Repo-Cleaner를 씁니다. 기록을 다시 쓰면 커밋 해시가 전부 바뀌므로 강제 푸시(force push)가 필요하고, 협업자는 저장소를 새로 받아야 합니다. 이미 만들어진 포크나 캐시된 화면에는 옛 기록이 남을 수 있어서, 결국 폐기가 실질적인 해결책이고 기록 삭제는 뒷정리에 가깝습니다.

오탐을 처리하는 세 가지 방법

스캐너를 켜면 테스트용 더미 값이나 예제 문서가 걸리는 일이 흔합니다. 오탐이 쌓이면 경고를 무시하는 습관이 생기므로 초기에 정리해 두는 편이 낫습니다.

• 한 줄만 예외 처리: 해당 줄 끝에 # gitleaks:allow 주석을 붙인다.
• 특정 탐지만 무시: 리포트에 나온 fingerprint 값을 .gitleaksignore 파일에 한 줄씩 적는다.
• 경로·패턴 단위 제외: .gitleaks.toml의 allowlist에 테스트 폴더나 예제 파일 경로를 등록한다.

이미 알려진 과거 유출분이 많아 새 스캔이 온통 경고로 도배된다면, 현재 결과를 baseline 파일로 저장하고 --baseline-path 옵션으로 넘기는 방법도 있습니다. 그러면 이후에는 새로 생긴 유출만 보고되어 신규 실수에 집중할 수 있습니다. 다만 baseline에 들어간 키는 여전히 폐기 대상이라는 점을 잊으면 안 됩니다.

실수로 올린 키를 폐기하고 기록에서 지우는 순서 신청하기