API 키를 안전하게 관리하는 기본 원칙

카테고리: 개발 자동화 #API 키#보안#개인 프로젝트

개인 프로젝트를 만들다 보면 API 키, 토큰, 웹훅 URL 같은 값을 자주 다루게 됩니다. 작은 실험이라도 이런 값이 GitHub에 올라가면 문제가 커질 수 있습니다.

이 글은 개인 프로젝트에서 지킬 기본 원칙을 정리한 글입니다.

API 키는 코드에 직접 쓰지 않는다

가장 기본은 코드 안에 키를 직접 넣지 않는 것입니다.

나쁜 예:

const apiKey = "sk-...";

좋은 방향:

const apiKey = process.env.API_KEY;

실제 값은 .env 파일이나 서비스의 환경 변수 설정에 둡니다.

.env 파일은 Git에 올리지 않는다

.env 파일에는 민감한 값이 들어갑니다. 그래서 .gitignore에 반드시 포함해야 합니다.

예:

.env
.env.*
*.env
.secrets/

처음 프로젝트를 만들 때 이 설정을 먼저 해두면 실수 가능성이 줄어듭니다.

공개 저장소 전환 전 확인할 것

처음에는 private 저장소로 시작하더라도, 나중에 public으로 바꿀 수 있습니다. 전환 전에는 최소한 다음을 확인해야 합니다.

  • .env 파일이 커밋되지 않았는지
  • 토큰이나 비밀번호가 코드에 남아 있지 않은지
  • README에 개인 정보가 들어가지 않았는지
  • 테스트용 계정 정보가 남아 있지 않은지
  • Git 이력에 민감정보가 들어간 적은 없는지

한 번 Git 이력에 들어간 키는 삭제해도 안전하다고 보기 어렵습니다. 그 경우 키를 폐기하고 새로 발급하는 편이 안전합니다.

서비스별 환경 변수 사용

배포 서비스에서는 보통 환경 변수를 따로 설정할 수 있습니다.

  • Cloudflare Pages: 프로젝트 설정의 환경 변수
  • Vercel: Project Settings의 Environment Variables
  • GitHub Actions: Repository Secrets

서비스마다 이름은 다르지만 원칙은 같습니다. 코드는 값을 읽기만 하고, 실제 비밀값은 배포 서비스에 저장합니다.

Daejin Lab에서 적용한 보안 기준

이 블로그 프로젝트에서도 처음부터 민감정보를 커밋하지 않는 것을 원칙으로 잡았습니다.

프로젝트 공통 규칙에는 아래 항목을 두었습니다.

.env
.env.*
*.env
.secrets/

그리고 실제 Google Search Console 인증 태그를 넣을 때도 API 토큰과 구분해서 판단했습니다. Search Console의 HTML 메타 태그는 공개 HTML에 들어가는 검증용 값이지만, GitHub 토큰이나 Cloudflare API 키는 절대 코드에 넣으면 안 됩니다.

구분 기준은 이렇게 잡았습니다.

공개 HTML에 들어가는 검증 메타 태그: 공개 가능
GitHub token: 공개 금지
Cloudflare API token: 공개 금지
Google OAuth client secret: 공개 금지
AdSense 결제/계정 정보: 공개 금지
.env 파일: 공개 금지

GitHub 인증 문제에서 배운 점

이번 프로젝트에서는 GitHub HTTPS 인증이 자동화 세션에서 잘 되지 않아 SSH 키 방식으로 바꿨습니다.

중요한 점은 비밀키를 외부에 공유하지 않고, 공개키만 GitHub에 등록했다는 것입니다.

공개키: GitHub에 등록 가능
비밀키: 로컬에만 보관

이 구분은 API 키 관리와도 비슷합니다. 남에게 보여도 되는 값과 절대 보여주면 안 되는 값을 먼저 나누는 습관이 중요합니다.

공개 전 점검 명령

나중에 저장소를 public으로 바꾸기 전에는 최소한 아래처럼 민감한 문자열 후보를 검색할 예정입니다.

git status --short
git log --oneline

그리고 파일 내용에서는 API_KEY, TOKEN, SECRET, .env 같은 단어가 실수로 들어갔는지 확인해야 합니다. 실제 키가 한 번이라도 Git 이력에 들어갔다면 삭제만으로는 부족하고, 해당 키를 폐기한 뒤 새로 발급하는 편이 안전합니다.

정리

API 키 관리는 복잡한 보안 기술보다 기본 습관이 중요합니다. 코드에 직접 쓰지 않고, .env를 Git에서 제외하고, 공개 전 이력을 확인하는 것만으로도 큰 사고를 줄일 수 있습니다.

특히 개인 블로그를 여러 개 운영할수록 “어떤 값은 공개 가능하고 어떤 값은 절대 공개하면 안 되는지”를 프로젝트마다 반복해서 확인해야 합니다.