GitHub에 .env를 올렸다면? API 키 유출 대응부터 재발 방지까지

FastAPI로 웹사이트를 개발하거나 GitHub Actions로 배포를 자동화할 때, 데이터베이스 비밀번호와 API 키를 어디에 저장할지 고민하게 됩니다. 보통은 .env 파일에 넣지만, 파일을 만드는 것만으로 비밀이 보호되는 것은 아닙니다. Git에 함께 커밋하거나 배포 로그에 출력하면 인증 정보가 노출될 수 있습니다.

특히 처음 개발하는 사람은 “파일을 삭제하고 다시 올리면 해결되겠지”라고 생각하기 쉽습니다. 그러나 현재 코드에서 값을 지우는 일과 노출된 키를 사용할 수 없게 만드는 일은 서로 다릅니다. 이 글에서는 그 차이를 설명하고, 이미 추적 중인 파일을 확인하는 방법부터 안전한 설정 예제까지 살펴봅니다.

대상 독자: Git과 GitHub로 개인 웹사이트를 개발하는 초보 개발자. 명령어는 저장소 최상위 폴더에서 실행합니다. 예제에는 실제 인증 정보 대신 가상 값을 사용합니다.

1. .env와 .gitignore는 각각 무엇을 할까?

.env는 환경 변수 값을 기록하는 데 흔히 사용하는 파일입니다. Python 프로젝트에서는 별도 라이브러리나 실행 도구가 이를 읽어 애플리케이션 설정에 전달합니다. 파일 이름을 .env로 정했다고 자동으로 암호화되거나 모든 프로그램이 자동으로 읽는 것은 아닙니다.

예를 들어 번역 API를 사용하는 사이트에는 다음과 같은 설정이 있을 수 있습니다.

TRANSLATION_API_KEY=DEMO_VALUE_NOT_A_REAL_KEY
DATABASE_URL=postgresql://demo_user:demo_password@localhost/demo_db

위 값은 설명용입니다. 실제 서비스에서는 인증 정보 자체를 소스 코드에 쓰지 않고, 로컬 설정이나 서버의 비밀 관리 기능을 통해 전달하는 편이 좋습니다.

한편 .gitignore는 Git이 아직 추적하지 않는 파일을 추가할 때 무시할 경로를 지정합니다. 이미 추적 중인 파일에는 소급 적용되지 않습니다. .env를 먼저 커밋한 뒤 .gitignore에 추가했다면, 여전히 추적 중일 수 있습니다.[1]

2. 이미 업로드했다면 파일 삭제보다 키 대응이 우선이다

실제 인증 정보가 공개 저장소에 올라갔다면 누군가 복사했을 가능성을 고려해야 합니다. GitHub도 유출된 비밀 정보는 손상된 것으로 보고 적절히 대응하라고 안내합니다. 새 커밋에서 지우거나 저장소를 삭제하는 것만으로 키의 악용을 막을 수는 없습니다.[2]

우선 서비스 제공자의 관리 화면에서 어떤 키가 노출되었는지 확인합니다. 외부 API 토큰인지, 데이터베이스 비밀번호인지에 따라 변경 위치와 영향을 받는 서비스가 달라집니다. 한 키를 여러 서버가 공유한다면 교체 대상도 함께 목록으로 정리해야 합니다.

대응 과정에서는 다음 항목을 확인하세요.

1. 노출된 키의 종류, 권한, 연결된 서비스 확인
2. 제공자의 기능으로 기존 키 폐기 또는 비밀번호 변경
3. 새 인증 정보를 서버와 자동 배포 설정에 반영
4. 애플리케이션 재시작 또는 재배포 후 정상 연결 확인
5. 제공자의 사용 기록에서 예상 밖 호출이나 접근 확인

활성 상태인 운영 키가 공개됐다면 신속한 폐기가 우선입니다. 서비스 중단 때문에 교체 순서가 필요하다면 새 키를 발급하고 적용한 뒤 기존 키를 폐기할 수 있지만, 그동안 기존 키가 유효하다는 점을 고려해야 합니다. GitHub도 서비스 의존성과 중단 영향을 함께 평가하도록 안내합니다.[2]

또한 API 키를 바꿨다고 데이터베이스 비밀번호까지 바뀌지는 않습니다. .env에 인증 정보가 여러 개 있었다면 각각의 교체 여부를 확인해야 합니다.

3. 내 .env가 Git에 포함되어 있는지 확인하기

VS Code 터미널에서 저장소 최상위 폴더를 열고 다음 명령을 실행합니다.

git ls-files -- .env

출력에 .env가 나오면 현재 Git 인덱스에 해당 경로가 들어 있습니다. 반대로 아무것도 나오지 않더라도 “과거에 한 번도 업로드되지 않았다”는 뜻은 아닙니다. 현재 추적 상태와 과거 기록은 따로 확인해야 합니다.

경로의 커밋 기록을 살펴보려면 다음 명령을 사용할 수 있습니다.

git log --all --oneline -- .env

이 명령은 로컬 저장소에 있는 참조를 기준으로 기록을 살펴봅니다. 다른 사람이 보관한 복사본이나 모든 원격 기록을 검사하는 보안 점검 도구는 아닙니다. 파일 이름이 변경되었거나 키가 다른 파일에도 들어갔다면 그 위치도 확인해야 합니다.

현재 변경 사항도 함께 확인하세요.

git status --short

민감한 값을 찾아낸 화면을 커뮤니티 질문이나 블로그에 첨부할 때는 실제 값을 제거해야 합니다. 문제를 설명하려고 올린 스크린샷이 또 다른 노출 경로가 될 수 있습니다.

4. 로컬 파일은 남기고 Git 추적만 중단하기

먼저 .gitignore에 아래 규칙을 넣습니다.

.env
.env.*
!.env.example

.env.*는 .env.local, .env.production 같은 이름을 무시합니다. 마지막 줄은 설정 항목을 공유하는 .env.example을 예외로 둡니다. 이 예외 파일에도 실제 키를 넣어서는 안 됩니다.[1]

이미 추적 중인 .env라면 다음을 실행합니다.

git rm --cached -- .env

--cached는 파일을 Git 인덱스에서만 제거하고 작업 폴더의 파일은 남기는 옵션입니다. 일반적인 git rm .env와 구분해서 사용해야 합니다. 파일이 수정되거나 스테이징된 상태에 따라 명령이 거절될 수 있으므로, 오류가 나면 변경 상태를 먼저 확인하세요.[3]

이후 .gitignore 변경을 스테이징하고 커밋합니다.

git add .gitignore
git diff --cached --stat
git commit -m "Stop tracking local environment file"

이미 다른 작업을 스테이징했다면 위 커밋에 함께 들어갈 수 있습니다. 커밋 전에 목록을 확인하세요. 상세 내용을 확인하는 git diff --cached는 삭제되는 실제 키까지 표시할 수 있으므로 화면 공유나 공개 로그에서 실행하지 않는 편이 좋습니다.[4]

마지막으로 추적 여부와 무시 규칙을 다시 확인합니다.

git ls-files -- .env
git check-ignore -v .env

첫 번째 명령은 출력이 없어야 하고, 두 번째 명령은 적용된 무시 규칙의 파일과 줄을 보여 줍니다. git check-ignore는 기본적으로 추적 중인 파일을 검사 결과에서 제외하므로 추적 중단 후 확인하는 것이 이해하기 쉽습니다.[5]

.env.production 등 다른 파일도 이미 추적 중이었다면 각각 처리해야 합니다. .env 하나를 제거했다고 모든 설정 파일이 제외되는 것은 아닙니다.

5. 가상 키로 확인한 실습 결과

위 핵심 동작은 Linux 환경의 Git 2.51.1에서 새 임시 저장소와 가상 키를 사용해 확인했습니다. 실제 서비스의 키 유출 사고나 운영 복구 사례는 아닙니다.

실습에서는 .env를 먼저 커밋하고, 이후 .gitignore를 추가했습니다. 그다음 추적 상태를 확인하고 git rm --cached를 실행했습니다.

*이미지: 위 실습에서 확인한 명령 결과를 읽기 쉽게 재구성한 도표. 실제 인증 정보는 포함하지 않았습니다.*

이 실습이 보여 주는 핵심은 .gitignore의 적용 시점입니다. 처음 프로젝트를 만들 때 규칙을 추가하는 것과, 이미 커밋한 파일에 나중에 규칙을 추가하는 것은 결과가 다릅니다.

6. 과거 커밋에서도 지워야 할까?

추적을 중단하고 새 커밋을 만들더라도 이전 커밋에는 파일이 남을 수 있습니다. 필요하면 git-filter-repo 같은 도구로 기록을 정리할 수 있습니다. 다만 기록 재작성은 커밋 식별자를 바꾸고 다른 사람의 브랜치나 복사본에도 영향을 줍니다.[6]

그래서 협업 저장소에 일반적인 강제 푸시 명령을 그대로 적용하는 것은 피해야 합니다. 먼저 노출된 인증 정보를 무효화하고, 어떤 브랜치·태그·복사본에 민감 정보가 남아 있는지 확인한 다음 정리 범위를 결정하세요.

다른 사용자의 로컬 복사본을 내 쪽에서 지울 수는 없습니다. 포크에 남은 기록도 별도로 처리해야 합니다. 기록 정리는 노출된 정보의 잔존을 줄이는 작업이며, 키 폐기를 대신하지 않습니다.[6]

7. .env.example과 배포용 Secrets를 분리하기

다른 개발자나 미래의 자신에게 필요한 설정 항목을 알려주려면 .env.example을 사용합니다.

TRANSLATION_API_KEY=
DATABASE_URL=
APP_ENV=development

이 파일은 “무엇을 설정해야 하는가”를 설명합니다. 실제 값은 각자의 로컬 .env나 서버 설정에 입력합니다. 프로젝트 문서에는 각 항목의 역할과 발급 위치를 적으면 처음 실행하는 사람이 이해하기 쉽습니다.

GitHub Actions에서 비밀 값이 필요하다면 워크플로 파일에 직접 적기보다 Secrets로 등록하고 필요한 단계에 전달합니다. 다음 코드는 전달 방식만 보여 주는 부분 예제이며 완성된 배포 워크플로는 아닙니다.[7]

steps:
  - name: Check required configuration
    env:
      TRANSLATION_API_KEY: ${{ secrets.TRANSLATION_API_KEY }}
    run: python -c "import os; assert os.environ.get('TRANSLATION_API_KEY'), 'Required secret is missing'"

이 예제는 값 자체를 출력하지 않고 존재 여부만 확인합니다. GitHub Actions 단계에 전달한 환경 변수는 운영 서버에 자동으로 영구 저장되는 설정이 아닙니다. 서버가 실행 시 값을 읽을 수 있도록 배포 환경에도 별도 설정해야 합니다.

로그 마스킹만 믿고 키를 출력하지 마세요. GitHub는 구조화된 값이나 변형된 값 등에서 비밀 정보의 마스킹이 실패할 수 있다고 설명합니다. 노출된 실행 로그도 삭제하고 키를 교체해야 합니다.[8]

8. 커밋 전에 확인할 최소 습관

매번 긴 보안 점검을 하는 대신, 파일을 올리는 순간에 확인할 항목을 정해 두면 실수를 줄이기 쉽습니다.

• 실제 설정 파일과 예제 설정 파일의 이름을 구분했는가?
• 커밋 대상에 .env, 개인 키, 비밀번호가 들어 있는가?
• 디버깅 코드가 설정값 전체를 출력하지 않는가?
• 문서나 스크린샷에 인증 정보가 남아 있지 않은가?
• 운영 서버와 테스트 서버가 불필요하게 같은 키를 공유하지 않는가?

VS Code의 소스 제어 화면에서 커밋 대상 파일을 하나씩 살펴보는 것도 좋습니다. “설정 파일이 포함되어 있는지”와 “설정값이 코드에 직접 들어 있는지”는 따로 확인하세요. 파일 이름만 안전해 보여도 내용에 실제 키가 있을 수 있습니다.

자주 묻는 질문

Q. .gitignore를 추가했는데 .env가 계속 보입니다.

이미 추적 중일 가능성이 있습니다. git ls-files -- .env로 확인하고, 해당하면 git rm --cached -- .env로 추적을 중단합니다. 실제 키가 노출되었다면 키 폐기·교체도 진행해야 합니다.

Q. private 저장소라면 실제 키를 넣어도 괜찮을까요?

private 저장소는 접근 범위를 제한하지만 비밀 관리 기능을 대신하지 않습니다. 협업자의 복사본이나 자동화 과정에도 값이 전달될 수 있습니다. 실제 키를 소스에 넣지 않는 구조로 관리하세요.

Q. 새 커밋에서 키를 지웠으니 기존 키를 계속 써도 될까요?

이미 노출되었다면 계속 사용하지 않는 편이 안전합니다. 현재 파일에서 값을 지워도 누군가 확보한 값까지 무효화되지는 않습니다. 제공자의 관리 기능으로 기존 값을 폐기하거나 변경해야 합니다.

Q. .env.example은 GitHub에 올려도 되나요?

빈 값이나 인증에 사용할 수 없는 예시 값만 들어 있다면 설정 안내용으로 공유할 수 있습니다. 실제 토큰이나 운영 비밀번호를 그대로 복사하지 않았는지 확인하세요.

Q. git rm --cached 명령에서 파일이 없다고 나옵니다.

추적 중인 경로가 아니거나 실행 위치·파일 경로가 다른 경우일 수 있습니다. 저장소 최상위 폴더에서 git ls-files -- .env를 확인하세요. 추적되지 않는 파일에 해당 명령을 반복할 필요는 없습니다.

API 키 관리에서 필요한 것은 파일 이름 하나가 아니라 작업 순서입니다. 프로젝트를 만들 때 설정 파일을 추적 대상에서 제외하고, 배포 환경에는 필요한 비밀 값만 전달하며, 노출이 발생하면 기존 인증 정보의 사용부터 차단하세요.

참고 자료

기술 설명은 다음 공식 문서를 참고했습니다. 문서 확인일: 2026년 10월 1일. 명령 검증 범위는 위에 명시한 임시 저장소의 Git 동작이며, 각 외부 서비스의 키 교체나 운영 서버 배포는 검증 범위에 포함하지 않습니다.

1. Git — gitignore
2. GitHub — Remediating a leaked secret in your repository
3. Git — git rm
4. Git — git diff
5. Git — git check-ignore
6. GitHub — Removing sensitive data from a repository
7. GitHub — Using secrets in GitHub Actions
8. GitHub — Secure use reference

IT 게시판

구분 제목 작성자 날짜 조회 추천

공지

Notice

공지 inspeep 커뮤니티 이용 및 게시물 관리 규정 안내

👤 관리자 📅 2026.04.15 👀 조회 57 👍 추천 0

BEST

BEST 1. 아무것도 모르고 코딩 독학으로 시작하는 웹사이트 제작: 도메인과 호스팅의 늪

👤 관리자 📅 2026.03.05 👀 조회 140 👍 추천 0

BEST

BEST 2. 코딩 문외한의 워드프레스 정복기: VS Code와 FTP의 습격

👤 관리자 📅 2026.03.05 👀 조회 135 👍 추천 0

BEST

BEST 3. 접속 불가 사태 발생! 초보 개발자의 눈물겨운 서버 복구 성공기

👤 관리자 📅 2026.03.05 👀 조회 128 👍 추천 0

BEST

BEST 10. 방구석 서버의 한계를 넘다: Render 백업부터 웹진형 게시판 개발까지

👤 관리자 📅 2026.03.05 👀 조회 120 👍 추천 0

Random Pick

Random Pick 로제 아이폰18 들자 삼성 등판 “우리한테 물어보지”..

👤 라두 📅 2026.09.12 👀 조회 10 👍 추천 0

Random Pick

Random Pick AI 개발 위험성을 폭로한 제이콥 콕슨은 누구인가?

👤 K_Shit 📅 2026.09.12 👀 조회 11 👍 추천 0

Random Pick

Random Pick 싱글벙글 아이폰듀오 팔릴때마다 함박웃음 짓는다는 기업

👤 야리타 📅 2026.09.13 👀 조회 13 👍 추천 0

개발

소름 쫙 돋는 개발포지션으로 지원오는데 제대로된 지원자가 없어요

👤 Cyan 📅 2026.05.24 👀 조회 13 👍 추천 0

뉴스

기가 막힌 싱글벙글 방금 핵쟁이들 컴퓨터 벽돌만들어버린 게임사

👤 Cyan 📅 2026.05.22 👀 조회 13 👍 추천 0

개발

말도 안 되는 국산 1인개발 유사 발라트로

👤 Cyan 📅 2026.05.22 👀 조회 20 👍 추천 0

개발

No Image

글로벌 SEO를 위한 첫걸음: DeepL API로 커뮤니티 자동 영문 번역기 도입기

👤 인스피 📅 2026.05.16 👀 조회 23 👍 추천 0

일반

신박한 ai별 엉덩이 때리면 반응

👤 Cyan 📅 2026.05.14 👀 조회 6 👍 추천 0

뉴스

상상초월 EU 배터리 교체 스마트폰 의무화래

👤 룸디르 📅 2026.05.09 👀 조회 17 👍 추천 0

뉴스

주목받는 ‘육아 도구’ 된 스마트폰…화면만 보는 어린 자녀들

👤 리토타 📅 2026.05.07 👀 조회 14 👍 추천 0

뉴스

눈물 쏙 빼는 중서운 이야기) 정체불명의 윈도우 창

👤 리토타 📅 2026.05.06 👀 조회 21 👍 추천 0

개발

웃음 참기 힘든 한국인이 만든 개발새발 하찮은 그림체 프롬프트 대유행중 ㅋㅋ

👤 포티리즈 📅 2026.05.05 👀 조회 26 👍 추천 0

뉴스

예사롭지 않은 오버 클럭하다가 컴퓨터 터진 썰 푼다...txt

👤 티지노아 📅 2026.05.04 👀 조회 28 👍 추천 0

잡담

환장하는 S26 울트라 디스플레이 정보 및 약간의 후기

👤 포티리즈 📅 2026.05.03 👀 조회 22 👍 추천 0

일반

[무료 배포] 단순 반복 업무를 끝내줄 생산성 도구, 'My Quick Phrases'를 소개합니다.

👤 인스피 📅 2026.05.01 👀 조회 29 👍 추천 0

팁/정보

No Image

바이브 코딩 시대, 코딩을 몰라도 결국 '이것'은 배워야 하는 진짜 이유

👤 리토타 📅 2026.04.30 👀 조회 23 👍 추천 1

리뷰

매일 쏟아지는 AI 신모델 뉴스, 결국 우리가 선택해야 할 '진짜' 기준은?

👤 포티리즈 📅 2026.04.25 👀 조회 43 👍 추천 0

팁

[AI 코딩 꿀팁] 돈 안 드는 '바이브 코딩' 완벽 가이드: 수동 하네스 엔지니어링으로 환각(Hallucination) 잡기

👤 관리자 📅 2026.04.23 👀 조회 46 👍 추천 1

정보

[1인 개발 칼럼] AI 정보의 홍수 속, '바이브 코딩' 유목민이 살아남는 법 (가짜 전문가를 조심하세요)

👤 관리자 📅 2026.04.22 👀 조회 38 👍 추천 0

자유

[1인 개발 웹사이트 운영기] 첫 게시글 조회수 100회 돌파! 솔직한 중간 정산

👤 관리자 📅 2026.04.16 👀 조회 58 👍 추천 1

개발기

No Image

[AI 활용기] 제미나이 프로 200% 활용법: 토큰 한계를 극복하는 '수동 하네스 엔지니어링' 실전 팁

👤 관리자 📅 2026.04.13 👀 조회 52 👍 추천 0

개발기

No Image

19. 내가 잠든 사이 서버가 뻗는다면? 파이썬(FastAPI) 에러 추적 및 디스코드 자동 알림 시스템 기획기

👤 관리자 📅 2026.04.12 👀 조회 44 👍 추천 0

개발기

No Image

[웹 기획] 커뮤니티의 생명은 공유! 타 사이트 및 유튜브 링크 자동 변환 UX 개선 기획기

👤 관리자 📅 2026.04.08 👀 조회 51 👍 추천 0

개발기

No Image

18. 커뮤니티의 꽃, 회원 관리: 나만의 비밀 관리자 대시보드

👤 관리자 📅 2026.04.01 👀 조회 72 👍 추천 0

개발기

No Image

[긴급] 내 웹사이트가 해킹당한다면? 초보 웹마스터의 서버 보안 구축 기획기

👤 관리자 📅 2026.03.28 👀 조회 68 👍 추천 0

개발기

No Image

17. 진정한 프로그램을 만들어보자. 웹툰/코믹스 이미지 속 외국어, 클릭 한 번에 자동 번역기 만들기 (기획 편)

👤 관리자 📅 2026.03.23 👀 조회 85 👍 추천 0

개발기

No Image

16. 완벽주의의 함정과 AI 기획

👤 관리자 📅 2026.03.20 👀 조회 76 👍 추천 0

자유

No Image

[운영파트] (2). 내 사이트는 왜 '유령 도시'일까? SEO(검색엔진 최적화)에 눈을 뜨다

👤 관리자 📅 2026.03.18 👀 조회 80 👍 추천 0

개발기

No Image

[운영파트] (1) 방문자 수 0명의 늪: 열심히 만든 내 웹사이트, 왜 구글 검색에 안 나올까? (초보 웹마스터의 생존기)

👤 관리자 📅 2026.03.16 👀 조회 97 👍 추천 0

개발기

No Image

[외전] 3. 수정 지옥에 빠지다: 완벽주의의 함정과 FastAPI 핵심 풀코드 결산

👤 관리자 📅 2026.03.09 👀 조회 96 👍 추천 0

개발기

[외전] 2. 방구석 500GB 서버의 위기: 파이썬 Pillow와 WebP로 이미지 용량 다이어트 성공기

👤 관리자 📅 2026.03.07 👀 조회 98 👍 추천 0

개발기

[외전] 1. 코딩 초보의 현실 자각 타임: 까만 화면을 넘어 GUI 관리자 대시보드가 절실해진 이유

👤 관리자 📅 2026.03.06 👀 조회 117 👍 추천 0

개발기

No Image

15. 세상에 내 웹사이트를 알리다: SEO 최적화와 구글 서치 콘솔, 그리고 최종 회고록

👤 관리자 📅 2026.03.05 👀 조회 114 👍 추천 1