<div align="center">
CommitGate
Git을 위한 AI 기반 보안 게이트입니다. 모든 git commit 또는 모든 git push 시 작동합니다.
CommitGate는 변경 사항을 스캔하여 비밀 정보나 위험한 코드가 히스토리에 도달하기 전에 차단합니다.
작동 방식 · 프로바이더 · 설정 · 사용 방법 · 구성 · 데이터 개인정보 보호
</div>
데모 (Demo)
<div align="center">
<img src="https://raw.githubusercontent.com/ductrl/CommitGate/HEAD/assets/demo.gif" alt="CommitGate Demo">
<p><em>CommitGate가 취약한 커밋이 Git 히스토리에 도달하기 전에 차단하는 모습입니다.</em></p>
</div>
작동 방식 (How it works)
CommitGate는 변경 사항에 대해 두 개의 스캐너를 실행하고 그 결과를 병합합니다:
| 스캐너 | 감지 항목 |
|---|
| Gitleaks | 알려진 비밀 패턴: API 키, 토큰, 비밀번호 |
| AI Reviewer | 정규식(regex)이 놓친 것: 코드 이해도, 사적 지식 |
-
사용자가 git commit을 실행하거나 (git push)를 실행합니다. 설치된 Git 훅(hook)이 변경 사항을 CommitGate에 전달합니다.
-
CommitGate는 허용(allow), 경고(warn), 또는 차단(block) 중 하나의 결과를 결정합니다.
-
터미널에서 보고서를 받게 됩니다. 차단된 경우 커밋이나 푸시가 중지되며, 그렇지 않은 경우 진행됩니다.
모듈별 설계를 보려면 docs/architecture.md를 참조하세요.
프로바이더 (Providers)
이들은 AI 리뷰어에 대해 지원하는 사용 가능한 프로바이더들입니다. OpenAI와 호환되는 API 키(더 빠르고 권장됨)를 사용하거나 자체 AI 에이전트를 사용할 수 있습니다.
설정
1. 필수 조건 설치
Gitleaks 설치하기
Gitleaks 준비 확인:
2. CommitGate 설치
pip install git+https://github.com/ductrl/CommitGate.git
3. 리포지토리 보호 설정
보호하려는 리포지토리 내부에서 다음을 실행합니다:
이 명령어는 commitgate.yaml 구성 파일을 생성하고 Git hook(훅)을 설치합니다. pre-commit 또는 pre-push 훅 중 어떤 것을 원하는지 묻습니다 (사용 방법은 How to use 참조).
4. AI 검토자 설정
commitgate.yaml 파일을 열고 provider를 아래 경로 중 하나와 일치하도록 설정합니다.
옵션 A: API 키 (OpenAI · Gemini · DeepSeek · Kimi · Groq)
프로젝트 루트에 .env 파일을 생성하고 키를 추가합니다.
.env 파일은 Git에서 제외하세요. 여기에 키가 들어있습니다.
옵션 B: AI 에이전트 (Claude Code, Codex 또는 Antigravity; API 키 불필요)
먼저 에이전트가 설치되어 로그인되었는지 확인합니다:
claude --version
codex --version
agy --version
그런 다음 provider를 설정합니다:
옵션 C: AI 미사용 (Gitleaks만 사용)
팀 전체가 동일한 게이트 정책을 공유할 수 있도록 commitgate.yaml 파일을 커밋하는 것이 좋습니다. 이 파일에는 비밀 정보(secrets)를 포함해서는 안 됩니다.
사용 방법 (How to use)
commitgate init을 실행한 후에는 평소처럼 git commit 또는 git push만 하면 되며, CommitGate가 변경 사항을 자동으로 스캔합니다.
pre-commit 대 pre-push
이 둘 중 하나를 선택하며, 이는 commitgate init 또는 commitgate install-hook을 실행할 때 이루어집니다:
| Hook | 실행 시점 (Runs on) | 스캔 대상 (Scans) |
|---|
| pre-commit | 모든 git commit 시마다 | 스테이징된 변경 사항 → 빠르고 커밋별 피드백 |
| pre-push | 모든 git push 시마다 | 푸시 범위 내의 모든 커밋 → 코드가 기기를 떠나기 전 최종 게이트 |
전환하거나 나중에 다른 것을 추가하려면 commitgate install-hook을 실행하고 선택하세요. 방어 깊이(defense in depth)를 위해 둘 다 설치하는 것이 좋습니다.
각 결과의 의미 (What each outcome means)
| 결과 (Outcome) | 시점 (When) |
|---|
allow | 발견된 문제 없음 (no findings) |
| ... | |
변경 기준은 commitgate.yaml의 policy.block_severity를 사용하여 변경할 수 있습니다 (low / medium / high / critical). 이와 다른 옵션들은 설정(Configuration)을 참조하세요. | |
수동 스캔 (Scan manually)
커밋하지 않고도 언제든지 스테이징된 변경 사항을 확인할 수 있습니다:
git add app.py
commitgate scan
만약 app.py가 비밀 정보를 하드코딩했다면 다음과 같이 표시됩니다:
CommitGate detected 1 security finding(s):
[CRITICAL] Finding #1
- Source: gitleaks
...
일회성 건너뛰기 (Skip once)
단일 커밋에 대해 게이트를 우회해야 하는 경우:
SKIP=commitgate git commit -m "your message"
설정 (Configuration)
commitgate init은 리포지토리 루트에 commitgate.yaml을 작성합니다. 모든 옵션에는 안전한 기본값이 설정되어 있으므로, 필요한 부분만 편집하세요. 언제든지 파일을 기본값으로 복원하려면 다음 명령어를 사용하세요:
주석 처리된 전체 파일 구조:
속도 최적화 (Tuning for speed)
CommitGate의 스캔 시간은 주로 생성해야 하는 출력량에 의해 결정됩니다. 일반적으로 출력할 정보가 적을수록 실행 속도가 빠릅니다.
reporting.min_severity: 이를 medium 또는 high로 높이면 발견되는 결과(findings)가 적어지고 스캔 시간이 단축됩니다.reporting.fields.description / suggestions: AI는 해당 필드 생성을 완전히 건너뛰고 스캔 속도를 크게 향상시킵니다.
두 설정 모두 policy.block_severity에 의해 제한되므로 (min_severity가 이를 초과하여 높아질 수 없음), 차단되는 발견(blocking finding)은 절대 숨겨지거나 건너뛰어지지 않습니다.
데이터 개인 정보 보호 (Data Privacy)
AI Reviewer를 활성화하면, CommitGate는 commitgate.yaml에서 구성한 선택된 변경 diff를 AI 제공업체로 전송합니다 (pre-commit을 위한 staged diff, pre-push를 위한 push-range diff). 이는 AI 에이전트에도 적용됩니다 (Claude Code → Anthropic, Codex → OpenAI, Antigravity → Google). 사용자의 diff가 여전히 해당 제공업체로 전송되므로, 이들은 에어 갭(air-gapped) 옵션이 아닙니다.
조직의 승인 없이 기밀하거나 독점적인 코드를 사용하는 경우 AI Reviewer를 사용하지 마십시오. Gitleaks만 실행하려면 ai.enabled: false로 설정하십시오.
완전한 로컬 LLM 지원은 개발 로드맵에 포함되어 있습니다.
라이선스 (License)
MIT © 2026 Mike Ly
CommitGate는 MIT 라이선스의 조건에 따라 사용, 수정 및 배포가 무료입니다.
<!-- provider badge + link definitions -->
