비밀값이 새지 않게 막기
API 키 같은 비밀값이 에이전트 대화에 읽히거나 커밋에 섞여 새지 않게 세 겹으로 막아, 키를 다시 발급하고 기록을 지우는 사고를 미리 줄입니다.
에이전트가 비밀 파일을 읽지 못하게 권한 규칙으로 막고, 커밋 전에 비밀값 검사를 돌리고, GitHub의 푸시 보호를 켭니다. 이미 새었다면 키부터 폐기합니다. 명령과 설정 이름은 2026년 11월 21일에 Claude Code·GitHub 공식 문서로 확인했습니다.
준비
- Git 저장소
- pre-commit(커밋 전 검사를 쓸 때)
1. 에이전트가 읽지 못하게
Claude Code는 .claude/settings.json의 deny 규칙으로 막습니다. Read 차단은 cat·head 같은 셸 읽기에도 적용되지만, 파일을 직접 여는 스크립트는 막지 못합니다.
{
"permissions": {
"deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"]
}
}결과: 비밀 파일 차단 규칙
확인: Claude에게 .env를 읽어 달라고 해서 거절되는지 확인
2. 커밋 전에 검사
gitleaks를 pre-commit에 걸면 비밀값이 든 커밋이 막힙니다. rev는 최신 릴리스로 맞춥니다.
repos:
- repo: https://github.com/gitleaks/gitleaks
rev: v8.24.2
hooks:
- id: gitleaks결과: .pre-commit-config.yaml
확인: pre-commit autoupdate && pre-commit install 뒤 가짜 키로 커밋이 막히는지 확인
3. 푸시 보호 켜기
GitHub 저장소의 secret scanning 푸시 보호를 켜면 알려진 형식의 키가 든 푸시가 막힙니다. 공개 저장소로의 개인 푸시는 기본으로 켜져 있고, 저장소 단위 설정은 관리자가 켭니다.
결과: 켜진 푸시 보호
확인: 가짜 형식 키를 푸시해 막히는지 확인
4. 새었을 때
커밋이나 대화에 키가 들어갔으면 기록을 지우기 전에 그 키를 먼저 폐기하고 새로 발급합니다.
결과: 폐기된 키와 새 키
확인: 옛 키로 요청이 거절되는지 확인
주의
- .claudeignore는 효과 없음. Read deny 규칙으로
- 푸시 보호는 누구나 이유를 적고 우회할 수 있는 것이 기본. 우회 권한을 좁히기
- gitleaks 저장소는 기능이 완성됐다고 밝히고 후속 도구(Betterleaks)로 옮겨 가는 중. 새로 고를 때 확인
- 지운 커밋도 포크와 캐시에 남을 수 있음. 키 폐기가 먼저
참고 자료
- 1GitHub 문서: 푸시 보호docs.github.com
- 2gitleaks 저장소github.com
댓글