가이드

설정값과 비밀 정보의 보관 위치

일반 설정값과 자격 증명을 분리하고, 로컬 개발·CI·운영 환경별 접근 범위에 맞는 보관 방법을 선택합니다.

어떤 형식을 선택해야 할까요?

작업 흐름에서 파일이 맡는 역할에 따라 선택하세요.

공유 가능한 기본값 → 비밀값이 없는 예시만 저장소에 커밋
개발자별 로컬 설정 → 도구가 지원하면 로컬 .env를 사용하고 Git 추적에서 제외
CI 자격 증명 → CI 제공자의 비밀 정보 저장 기능을 사용하고 접근 제한
운영 환경·컨테이너 → 실행 플랫폼의 비밀 정보 기능을 사용하고 필요한 서비스에만 권한 부여
노출이 의심됨 → 파일 삭제만 하지 말고 자격 증명을 폐기하거나 교체

일반 설정값과 비밀 정보를 구분하세요

서비스 URL이나 기능 플래그처럼 민감하지 않은 설정값과 비밀번호, API 키, 개인 키 같은 자격 증명은 다르게 취급해야 합니다. 실제 자격 증명을 코드에 직접 넣거나, 실제 값이 포함된 파일을 공유 저장소에 커밋하지 마세요. 먼저 애플리케이션이 어떤 설정 방식을 지원하는지 확인하세요.

로컬 .env 파일을 Git에서 제외하세요

도구가 지원한다면 개발자별 로컬 값은 .env 파일에 두고, 변수 이름과 예시 값만 담은 .env.example을 공유하세요. 실제 .env는 .gitignore에 추가하고 Git이 이미 추적 중이지 않은지도 확인해야 합니다. Git 제외 규칙은 안전한 보관소가 아니며 이미 기록된 값도 저장소 이력에서 지우지 않습니다.

CI 비밀 정보 저장소와 최소 권한을 사용하세요

GitHub Actions 같은 CI에서는 워크플로 파일에 자격 증명을 쓰지 말고 제공자의 비밀 정보 기능에 등록하세요. 필요한 저장소·환경·작업에만 접근을 허용하고 토큰 권한은 꼭 필요한 수준으로 제한하며, 로그에 값을 출력하지 마세요. 자동 마스킹만으로 변환된 값이나 모든 명령 출력을 숨길 수 있는 것은 아닙니다.

운영 실행 환경에서 비밀 정보를 제공하세요

운영 환경에서는 호스팅 또는 클라우드 플랫폼의 비밀 정보 저장 기능을 우선 사용하고, 각 값을 읽을 수 있는 배포 대상과 서비스를 제한하세요. Docker Compose는 명시적으로 허가한 서비스에 비밀 정보를 파일로 마운트할 수 있습니다. 기능과 제약은 플랫폼마다 다르므로 실제 실행 환경의 문서를 확인하세요. 지원된다면 장기 유효 키 대신 OIDC 같은 단기 자격 증명도 고려하세요.

노출됐다면 자격 증명을 먼저 폐기하거나 교체하세요

비밀 정보가 커밋, CI 로그, 채팅 등에 노출됐을 수 있다면 보이는 사본을 지우는 것만으로는 부족합니다. 먼저 해당 키나 토큰을 폐기하거나 교체하고, 접근 로그와 사용 가능성을 살펴보세요. 그다음 저장소 이력과 로그를 적절히 처리하고 재발하지 않도록 접근 권한을 강화하세요.

고려할 형식

.env

적합한 용도: .env 파일을 지원하는 도구에서 로컬 설정값을 불러오기

적합하지 않은 용도: 비밀 정보를 보호 없이 공유하거나 보관하기

.gitignore

적합한 용도: 아직 추적되지 않는 로컬 .env가 실수로 추가되지 않도록 하기

적합하지 않은 용도: 자격 증명을 폐기하거나 Git이 추적한 값을 이력에서 삭제하기

내보내기 전 확인

.env와 .gitignore만으로 비밀 정보의 안전이 보장되지는 않습니다. Git 추적 상태, CI 로그, 백업, 실행 환경의 비밀 정보 저장소도 확인하세요.
마스킹으로 변환된 값이나 모든 명령 출력을 숨기지 못할 수 있습니다.
자격 증명 유출이 의심되면 파일만 삭제하지 말고 해당 자격 증명을 폐기하거나 교체하세요.

가이드

설정 파일 형식 선택하기대상 도구가 허용하는 형식을 먼저 확인하세요. 여러 형식을 지원한다면 팀이 안전하게 검증하고 관리할 수 있는 형식을 고르세요.인증서 및 키 파일 형식 선택하기먼저 배포 대상이 요구하는 형식을 확인하고 발급된 인증서, 인증서 요청서, 개인 키를 구분하세요.