API 키는 Git에 넣으면 안 되는데 Vercel에는 왜 넣어도 될까요?

오늘 클로드코드 바이브코딩 수업에서 이런 질문이 나왔습니다.

API 키는 Git에 commit하면 보안상 위험해서 제외하잖아요. 그런데 Vercel 환경변수 화면에는 왜 그 값을 직접 넣어도 되나요?

처음에는 조금 이상하게 느껴질 수 있습니다. GitHub도 인터넷에 있는 서비스이고, Vercel도 인터넷에 있는 서비스니까요. 결국 같은 API 키를 어딘가에 입력하는 것처럼 보입니다.

하지만 두 곳은 비밀값을 다루는 방식이 다릅니다.

• Git은 프로젝트의 변경 기록을 남기고 공유하는 곳입니다. 여기에 API 키를 넣으면 키도 기록의 일부가 됩니다.
• Vercel 환경변수는 배포에 필요한 비밀값을 따로 보관하는 곳입니다. 프로젝트 파일과 분리해 저장하고, 웹앱이 작동할 때 필요한 곳에만 전달합니다.

쉽게 비유하면 Git은 여러 사람이 복사할 수 있는 작업 문서이고, Vercel 환경변수는 웹앱이 사용할 열쇠를 넣어두는 별도 보관함에 가깝습니다.

그래서 Git에는 실제 API 키를 넣지 않고, Vercel에는 환경변수로 등록하는 것이 맞습니다.

API 키가 유출되면 왜 문제가 될까요?

AI 기능이 있는 웹앱을 만들었다고 해볼게요. 웹앱이 AI 서비스에 답변을 요청할 때는 내 계정에서 발급한 API 키를 사용합니다.

이 키는 호텔 객실의 카드키보다 내 결제수단이 연결된 출입증에 더 가깝습니다. 누군가 내 키를 가져가 많은 요청을 보내면, 내가 사용하지 않은 비용까지 내 계정에 쌓일 수 있어요. 유료 문자 발송이나 지도, 번역, 이미지 생성 서비스의 비밀 키도 마찬가지입니다.

모든 API 키가 비밀인 것은 아닙니다. 처음부터 브라우저에 공개하는 것을 전제로 만든 키도 있어요. 이 글에서는 외부에 보여주면 안 되는 비밀 API 키를 다룹니다.

공개용 키와 비밀 키를 구분하는 방법은 API 키와 .env에서 더 자세히 설명했습니다.

Git에 넣은 키는 기록과 함께 퍼져요

Git은 프로젝트가 어떻게 바뀌었는지 차곡차곡 기록합니다. 실제 API 키가 들어간 상태로 commit하면 그 키도 변경 기록에 포함돼요. GitHub에 push한 뒤에는 팀원의 컴퓨터나 연결된 자동화 서비스로 저장소가 복제될 수 있습니다.

저장소가 비공개라고 해도 비밀 보관함이 되는 것은 아닙니다. 접근 권한이 있는 사람과 서비스는 저장소를 복제할 수 있고, 나중에 공개 범위를 잘못 바꾸는 실수도 생길 수 있어요.

다음 commit에서 키를 지워도 안심할 수 없습니다. 지금 보이는 파일에서는 사라져도 이전 기록에는 남을 수 있기 때문입니다. GitHub도 비밀번호나 토큰 같은 비밀값이 유출되면 기록을 정리하는 것보다 먼저 그 값을 폐기하거나 교체하라고 안내합니다. (GitHub 공식 문서 (새 탭에서 열림))

commit과 push가 아직 낯설다면 내 프로젝트가 GitHub를 오가는 과정을 먼저 읽어도 좋습니다.

Vercel 환경변수는 무엇이 다를까요?

가장 큰 차이는 API 키가 프로젝트 기록에 들어가지 않는다는 것입니다.

실제 값은 Vercel 프로젝트의 Environment Variables 화면에 따로 저장됩니다. 그래서 누군가 GitHub 저장소를 복제해도 Vercel에 보관된 API 키까지 함께 복사되지는 않아요.

그리고 Vercel은 저장한 환경변수를 암호화해 보관합니다. 암호화는 실제 값을 그대로 펼쳐두는 대신, 허용된 과정에서만 사용할 수 있는 형태로 바꿔 보관하는 것입니다. (Vercel 환경변수 문서 (새 탭에서 열림))

그래서 Vercel 환경변수는 여러 사람이 복사하는 프로젝트 기록과 성격이 다릅니다. 비밀값을 프로젝트 파일과 떼어놓고, 접근할 수 있는 사람도 따로 관리할 수 있어요.

물론 암호화되어 있다고 해서 세상 누구도 값을 볼 수 없다는 뜻은 아닙니다. Vercel 프로젝트에 권한이 있는 사람은 일반 환경변수를 확인할 수 있습니다. 꼭 필요한 사람에게만 권한을 주고, 더 민감한 값은 저장 후 다시 내용을 볼 수 없는 Sensitive 환경변수로 등록할 수 있어요. (Vercel Sensitive 환경변수 문서 (새 탭에서 열림))

핵심은 어렵지 않습니다. Vercel은 비밀값을 보관하기 위해 마련된 별도 공간이고, 그 값을 프로젝트 파일과 분리해 암호화한다는 점입니다.

암호화되어 있어도 밖으로 꺼내면 노출돼요

여기서 가장 중요한 주의점이 있습니다.

Vercel은 환경변수를 안전하게 보관하지만, 내가 그 값을 브라우저 화면이나 로그에 보내는 것까지 모두 판단해 막아주지는 않습니다. 금고에 넣어둔 열쇠도 꺼내서 사진을 찍어 공유하면 더 이상 비밀이 아닌 것과 같아요.

특히 다음 상황을 조심해야 합니다.

• 비밀 API 키를 브라우저에서 사용하도록 설정하는 경우
• 오류를 해결하려고 API 키가 보이는 화면이나 로그를 그대로 공유하는 경우
• AI 대화창에 환경변수 전체를 복사해 붙여넣는 경우
• Vercel 프로젝트 접근 권한을 필요 이상으로 많이 주는 경우

브라우저는 방문자의 컴퓨터에서 작동합니다. 따라서 브라우저 쪽에서 사용하는 값은 방문자가 확인할 수 있다고 생각하는 편이 안전해요. 비밀 API 키는 브라우저에 전달되지 않도록 해야 합니다.

직접 설정 방법을 판단하기 어렵다면 바이브코딩 도구에 이렇게 요청해보세요.

이 API 키는 비밀값이야. Vercel 환경변수로 등록하고, 브라우저나 화면, 로그에는 노출되지 않게 해줘.

완성된 뒤에는 “API 키가 브라우저에서 보이지 않는지 다시 점검해줘”라고 한 번 더 확인하는 편이 좋습니다. 로그인과 개인정보 보호까지 함께 살펴보려면 바이브코딩 보안 체크리스트를 사용해보세요.

이미 GitHub에 올렸다면 키부터 바꾸세요

실수로 실제 API 키를 commit하고 GitHub에 push했다면, 파일에서 키를 지우는 것만으로는 부족합니다.

가장 먼저 키를 발급한 서비스에서 기존 키를 폐기하고 새 키를 발급하세요. 그다음 새 키를 Vercel 환경변수에 등록하고, Git이 비밀값이 담긴 파일을 앞으로 기록하지 않도록 설정되었는지 바이브코딩 도구에 확인해달라고 요청하면 됩니다.

마지막으로 기존 키에 이상한 사용량이나 비용이 생기지 않았는지도 확인하세요. 누군가 이미 키를 복사했다면 Git 기록을 정리한 뒤에도 계속 사용할 수 있기 때문입니다.

이것만 기억하세요

Git은 프로젝트의 기록이고, Vercel 환경변수는 배포에 필요한 비밀값을 위한 별도 보관함입니다.

Vercel은 환경변수를 프로젝트 파일과 분리하고 암호화해 보관합니다. 더 민감한 값은 저장 후 다시 열어볼 수 없게 설정할 수도 있어요.

다만 암호화는 안전한 보관을 돕는 장치입니다. 비밀 키를 브라우저나 로그, AI 대화창, 화면 캡처로 꺼내 보여주면 보호받을 수 없습니다.

비밀 API 키는 GitHub에 올리지 않고 Vercel 환경변수에 넣기. 그리고 브라우저에는 보여주지 않기. 이 세 가지만 먼저 기억해도 큰 실수를 피할 수 있습니다.