환경변수와 비밀키 관리: .env부터 시크릿 매니저까지 단계별 운영 가이드

혼자 만드는 서비스라도 API 키, 데이터베이스 접속 정보, 결제 시크릿은 언젠가 여러 환경을 오갑니다. 로컬에서는 잘 되던 설정이 CI에서 빠지거나, 실수로 저장소에 키가 올라가면 복구에 시간을 쓰게 됩니다. 핵심은 키를 숨기는 데서 끝나지 않고, 어디서 주입되고 언제 교체되는지 정해두는 것입니다.

조코헌트에 출시된 프로덕트 234개와 출시한 메이커 183명을 보면, 1인 개발도 출시 순간부터 여러 실행 환경을 관리하게 됩니다. 처음부터 거대한 보안 시스템을 만들 필요는 없지만, 다음 단계로 넘어갈 기준은 미리 정해두는 편이 안전합니다.

1. 비밀키 관리의 기준부터 정하기

환경변수에 넣을 것

외부에 공개되면 안 되는 값은 코드와 분리합니다. API 키, 데이터베이스 URL, 세션 서명 키, OAuth 시크릿, 웹훅 검증 키가 대표적입니다. 반대로 공개되어도 되는 서비스 주소나 기능 플래그까지 모두 비밀로 취급하면 설정이 복잡해지므로, “유출되면 권한을 얻을 수 있는가?”를 기준으로 나누세요.

세 가지 질문

각 키마다 다음을 문서로 남기면 운영이 단순해집니다.

어느 환경에서 필요한가: 로컬, 테스트, 프로덕션
누가 발급·교체하는가: 개인 계정인지, 프로젝트 계정인지
유출되면 무엇을 해야 하는가: 폐기, 재발급, 영향 범위 확인

이런 규칙은 AI 코딩 도구에 컨텍스트 잘 주는 법: 규칙 파일을 운영 문서로 쓰기처럼 프로젝트 규칙 파일에도 짧게 기록해두면 좋습니다.

2. `.env`는 로컬 전용으로 운영하기

`.env.example`을 계약서로 만들기

저장소에는 실제 값이 없는 .env.example만 커밋합니다. 변수 이름과 용도를 적고, 필요한 값이 빠졌을 때 앱이 알아보기 쉬운 오류를 내도록 구성하세요.

# 외부 AI API 호출용
AI_API_KEY=
# 프로덕션 데이터베이스
DATABASE_URL=
# 세션 서명용 랜덤 문자열
SESSION_SECRET=

새 환경변수를 추가할 때는 코드와 .env.example을 함께 수정합니다. 값이 비어 있어도 되는 선택 항목인지, 반드시 필요한 필수 항목인지 주석으로 구분하면 온보딩과 배포 점검이 빨라집니다.

커밋 사고를 예방하기

.gitignore에는 실제 환경 파일을 등록하고, 커밋 직전에 파일 목록을 확인하는 습관을 만드세요. 비밀키 검색 도구나 pre-commit 훅을 연결할 수도 있습니다. 자동화 흐름은 Claude Code 훅(hooks) 활용: 커밋 메시지 규칙·자동 포맷·알림을 강제하는 자동화 패턴에서 다룬 방식처럼 프로젝트 규모에 맞게 작게 시작하면 됩니다.

이미 키를 커밋했다면 파일에서 지우는 것만으로 충분하지 않을 수 있습니다. 저장소 기록, CI 로그, 빌드 로그에 남았을 가능성을 고려해 먼저 키를 폐기하고 새 키를 발급한 뒤 노출 경로를 확인하세요.

3. CI와 프로덕션은 주입 경로를 분리하기

CI에서는 저장소 설정의 시크릿 사용

테스트와 배포 자동화에는 CI 제공자의 secrets 저장 기능을 사용합니다. 워크플로 파일에 값을 직접 적거나, 명령어 인자로 출력되게 만들지 마세요. 환경별로 필요한 키만 연결하고, 로그에 환경변수가 표시되지 않는지도 확인해야 합니다. 서비스별 설정 방식과 권한 범위는 해당 도구의 공식 문서에서 확인하세요.

프로덕션에서는 플랫폼 설정 활용

프로덕션 서버에는 로컬 .env 파일을 복사하기보다 배포 플랫폼이나 서버의 환경변수 설정으로 주입하는 방식이 관리하기 쉽습니다. 개발·스테이징·프로덕션 값을 분리하고, 데이터베이스와 외부 API 키도 가능하면 서로 다른 자격증명을 사용하세요.

처음 선택하는 인프라 조합이 아직 고민이라면 1인 개발자 풀스택 기술 스택 고르기: Next.js·Supabase·Vercel 조합이 합리적인 이유와 한계를 참고하되, 특정 플랫폼의 시크릿 보관 방식은 배포 전에 공식 문서로 다시 확인하세요.

4. 키 교체와 유출 대응을 절차로 만들기

평소에 할 일

키 이름에 발급 시점이나 개인 이름을 넣기보다 용도 중심으로 정합니다. 사용하지 않는 키는 정리하고, 담당 계정이 퇴사나 권한 변경으로 사라지지 않도록 프로젝트 단위 소유권을 검토하세요. 교체 주기는 서비스 위험도와 제공자의 기능에 따라 다르게 잡으면 됩니다.

유출을 발견했을 때

해당 키를 즉시 비활성화하거나 폐기합니다.
새 키를 발급하고 로컬·CI·프로덕션 값을 모두 교체합니다.
저장소, 이슈, 로그, 배포 기록에서 노출 범위를 확인합니다.
비정상 호출이나 데이터 접근 흔적을 점검합니다.
원인과 재발 방지 조치를 한 문서에 남깁니다.

5. 배포 전 10분 체크리스트

실제 .env 파일이 저장소 추적 대상이 아닌가?
.env.example에 코드가 요구하는 변수 이름이 모두 있는가?
CI 시크릿이 로그에 출력되지 않는가?
스테이징과 프로덕션 키가 분리되어 있는가?
사용하지 않는 키와 과도한 권한을 정리했는가?
유출 시 폐기·재발급 순서를 알고 있는가?

비밀키 관리는 처음부터 비싼 도구를 도입하는 문제가 아닙니다. 로컬 파일, CI secrets, 프로덕션 환경변수라는 단순한 세 층을 분리하고, 키 교체 절차를 문서화하는 것부터 시작하세요. 서비스와 팀이 커져 접근 권한과 감사 기록이 필요해지는 시점에 시크릿 매니저로 옮겨가도 늦지 않습니다.

이 글의 목차