로컬 빌드 vs 깃허브 빌드: 환경변수는 어떻게 주입될까?
"왜 내 컴퓨터에서는 잘 되는데 깃허브 액션에서는 환경변수를 못 찾나요?" 로컬 개발 환경과 클라우드 CI/CD 환경에서의 빌드 파이프라인 차이점과 환경변수 주입 메커니즘을 알아봅니다.
Q: 왜 환경변수 셋팅을 로컬 따로, 깃허브 따로 두 번 하나요? 로컬에서도 빌드하고 깃에서도 빌드하는 건가요?
많은 개발자들이 "내 컴퓨터(로컬)에서 `pnpm build`가 잘 되니까 깃허브에서도 당연히 잘 되겠지?" 라고 착각합니다.
A: 내 컴퓨터의 빌드와 깃허브에서의 빌드는 완전히 독립적인 두 번의 별개 작업입니다.
상세 설명: 로컬과 CI/CD 클라우드는 남남이다
내 컴퓨터(로컬)에서 코드를 짜고 테스트하기 위해 빌드할 때는 폴더에 고이 모셔둔 `.env.local` 파일을 Next.js가 쏙쏙 읽어갑니다.
하지만 코드를 깃허브에 푸시(Push)하면, 지구 반대편 어딘가에 있는 깃허브 클라우드 서버가 코드를 내려받아서 새롭게 빌드를 시작합니다. 당연히 내 컴퓨터에만 있던 `.env.local` 파일은 거기로 가지 않았습니다.
Q: 그럼 깃허브 서버(CI/CD)에서는 어떻게 환경변수를 알아내나요?
파일이 없기 때문에, 우리는 깃허브 서버에게 "이 저장소 설정(Settings > Secrets)에 내가 변수들을 저장해 뒀으니까 빌드할 때 이걸 꺼내서 써"라고 워크플로우(`docker-build.yml`)에 적어줍니다.
핵심 주입 과정: GitHub Secrets ➡️ build-args ➡️ ARG ➡️ ENV
상세 설명: 복잡해 보이지만 안전한 주입 릴레이
1. `docker-build.yml`에서 깃허브 Secrets를 꺼내서 도커의 `build-args`로 전달합니다.
2. `Dockerfile` 안에서 `ARG` 명령어(매개변수 받기)로 그걸 받아냅니다.
3. 마지막으로 `ENV` 명령어를 통해 컨테이너 내부의 진짜 환경변수로 등록해 줍니다.
4. 이 과정이 모두 끝나야 비로소 `next build` 명령어가 실행되면서 환경변수를 정상적으로 읽어들여 프론트엔드 파일을 완성하게 됩니다.
이정마 에디터
Cloud Architect
개발자 노트북과 클라우드 빌드 서버는 완전히 남남입니다. 내 노트북에 있는 .env 파일이 깃허브 클라우드에 마법처럼 텔레파시로 넘어갈 수는 없습니다.