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 땜빵과 아다리로 가득한 동키콩 개발사

👤 리토타 📅 2026.07.28 👀 조회 13 👍 추천 0

Random Pick

Random Pick 마개조 스마트폰 쿨링케이스 V2

👤 디록 📅 2026.07.25 👀 조회 21 👍 추천 0

Random Pick

Random Pick 스마트폰 없는 완벽한 하루는 가능할까?… 62% "거리 두고 싶다"

👤 K_Shit 📅 2026.07.25 👀 조회 12 👍 추천 0

뉴스

국내 기업 위장 취업한 北 IT 인력, 해외서 원격 근무했다

👤 로루디다 📅 2026.10.25 👀 조회 0 👍 추천 0

뉴스

싱글벙글 아이폰 듀오... 결함 발생 속출...JPG

👤 K_Shit 📅 2026.10.24 👀 조회 0 👍 추천 0

뉴스

'아이폰 듀오' 펼치니 일부 앱 화면 절반이 '검은 여백'

👤 PPAOE 📅 2026.10.23 👀 조회 0 👍 추천 0

개발

바이오웨어 망한거보고 MAGA 개발자가 한소리함 ㅋㅋ

👤 바루데여 📅 2026.10.23 👀 조회 0 👍 추천 0

개발

싱글벙글 앞으로 예정된 서울 대규모 개발 리스트

👤 Maodun 📅 2026.10.23 👀 조회 0 👍 추천 0

팁/정보

No Image

비행기 모드인데 인터넷이 된다? 이름 때문에 생기는 스마트폰의 오해

👤 인스피 📅 2026.10.23 👀 조회 3 👍 추천 0

뉴스

북한 IT 인력, 한국기업 취업 첫 확인‥"수사 중"

👤 PPAOE 📅 2026.10.22 👀 조회 1 👍 추천 0

개발

싱글벙글 개발자가 말하는 AI소설이 성공할 수 없는 이유

👤 로루디다 📅 2026.10.22 👀 조회 1 👍 추천 0

자유

No Image

도메인이 연결되지 않을 때: DNS·HTTPS·웹서버를 나누어 확인하는 순서

👤 인스피 📅 2026.10.21 👀 조회 1 👍 추천 0

개발

소수의 트롤링으로 아직도 화자되는 충격적인 개발 과정.JPG

👤 PPAOE 📅 2026.10.20 👀 조회 1 👍 추천 0

뉴스

아이폰18 일반 최종 유출

👤 Maodun 📅 2026.10.20 👀 조회 2 👍 추천 0

팁/정보

No Image

댓글 전송 버튼이 멈출 때: fetch 오류 처리와 중복 제출 방지하기

👤 인스피 📅 2026.10.19 👀 조회 8 👍 추천 0

개발

인디게임 개발자들은 어디서 자금을 조달받을까?

👤 K_Shit 📅 2026.10.18 👀 조회 0 👍 추천 0

뉴스

아이폰 듀오, 나노텍스쳐 선동이 어이가 없는 이유

👤 Maodun 📅 2026.10.16 👀 조회 0 👍 추천 0

자유

No Image

로그인 후 다시 로그아웃될 때: 쿠키의 Domain·Path·Secure를 확인하는 순서

👤 인스피 📅 2026.10.16 👀 조회 6 👍 추천 0

뉴스

대구 모텔방 안 스마트폰 수십대의 정체.....jpg

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

자유

No Image

사진 올리기 전에 확인할 EXIF: 촬영 정보 제거와 회전 문제를 함께 점검하기

👤 인스피 📅 2026.10.12 👀 조회 4 👍 추천 0

뉴스

아이폰갤에서 종결난 패널떡밥 정리

👤 K_Shit 📅 2026.10.12 👀 조회 1 👍 추천 0

팁/정보

No Image

서버 로그 시간이 9시간 다를 때: UTC와 한국 시간을 정확히 맞추는 방법

👤 인스피 📅 2026.10.11 👀 조회 9 👍 추천 0

개발

No Image

개발일지 #9 - 개선된 픽셀 셰이더 그리고 해군

👤 루루웨도 📅 2026.10.11 👀 조회 3 👍 추천 0

뉴스

아이폰18 프로, 발열·배터리 잡았지만…199만원의 벽

👤 Maodun 📅 2026.10.11 👀 조회 2 👍 추천 0

뉴스

불닭 짝퉁, 스마트폰 대면 바로 들통난다

👤 루루웨도 📅 2026.10.10 👀 조회 1 👍 추천 0

팁/정보

No Image

게시판 조회가 느릴 때: SQLite 실행 계획으로 인덱스 효과 확인하기

👤 인스피 📅 2026.10.10 👀 조회 11 👍 추천 0

팁/정보

No Image

pip로 설치했는데 모듈이 없다고 할 때: Python 가상환경과 실행 경로 확인하기

👤 인스피 📅 2026.10.09 👀 조회 5 👍 추천 0

팁/정보

No Image

.gitignore에 넣었는데 계속 올라갈 때: Git 추적 상태를 확인하는 순서

👤 인스피 📅 2026.10.08 👀 조회 6 👍 추천 0

뉴스

삼성...스마트폰 생산량 줄인다 ㄷㄷ...News

👤 PPAOE 📅 2026.10.08 👀 조회 1 👍 추천 0

팁/정보

No Image

다운로드 파일이 같은지 확인하기: SHA-256 무결성 검사와 한계

👤 인스피 📅 2026.10.07 👀 조회 12 👍 추천 0

팁/정보

No Image

CSV 한글이 깨질 때: 인코딩·쉼표·앞자리 0을 따로 점검하는 방법

👤 인스피 📅 2026.10.06 👀 조회 8 👍 추천 0

개발

개발 비화 떡밥에 올리는 재밌는 개발 비화

👤 바루데여 📅 2026.10.06 👀 조회 0 👍 추천 0

개발

No Image

웹사이트가 안 열릴 때: HTTP 403·404·429·500·503을 구분하는 실습 가이드

👤 인스피 📅 2026.10.05 👀 조회 7 👍 추천 0