배포 실패의 늪에서 탈출하기: 시니어의 로그 분석과 디버깅 철학
안녕하세요, 여러분. 15년 차 백엔드 개발자이자 데브옵스 엔지니어로 일하며, 여러분과 똑같이 수많은 '빨간색 X 표시(Red Cross)' 앞에서 좌절하고 밤을 지새웠던 동료로서 이 글을 씁니다. 금요일 오후 5시, 한 주간의 고된 스프린트를 마치고 모든 기능 구현을 끝낸 뒤 상쾌한 마음으로 git push를 날렸을 때를 상상해 보세요. 깃허브 액션(GitHub Actions) 탭에서 빙글빙글 돌던 노란색 원이 갑자기 싸늘한 빨간색으로 변하는 순간, 등줄기를 타고 흐르는 식은땀과 그 절망적인 기분은 개발자라면 누구나 한 번쯤 겪어보셨을 겁니다. 😱
솔직히 고백하자면, 저도 주니어 시절에는 이 로그를 제대로 읽을 줄 몰라 무작정 'Re-run jobs' 버튼만 다섯 번씩 누르곤 했습니다. 마치 "이번엔 제발 되어라, 컴퓨터야 부탁해"라고 기도하듯이 말이죠. 하지만 간헐적 성공은 있어도 이유 없는 실패는 없습니다. 15년의 경험과 수천 번의 배포 파이프라인 구축 경험이 제게 알려준 명확한 사실은, 로그는 결코 거짓말을 하지 않는다는 것입니다. 자동 배포가 실패했을 때, 그 원인의 90% 이상은 우리의 비즈니스 로직 코드가 아니라, 환경 변수(Environment Variables) 설정 누락, 불충분한 권한(Permission) 문제, 혹은 YAML 문법의 미세한 들여쓰기 오류와 같은 설정의 영역에 있습니다.
오늘은 단순히 "에러를 고치는 법"을 넘어, 깃허브 액션이라는 거대한 블랙박스 안에서 도대체 무슨 일이 벌어지는지 엑스레이를 찍듯 투시해보려 합니다. 워크플로우 로그를 현미경처럼 분석하여 숨겨진 단서를 찾고, 증발해버린 환경 변수를 끝까지 추적하며, 권한 문제라는 철옹성을 뚫는 방법을 아주 상세하게, 그리고 실전적으로 다루겠습니다. 단순히 해결책을 던져주는 것이 아니라, 문제를 바라보는 관점을 바꿔드리겠습니다. 커피 한 잔 진하게 타 오세요. 이제부터 우리는 셜록 홈즈가 되어 범인을 잡으러 갑니다. ☕️🔍
1. 워크플로우 로그 해부학: 빨간 줄 그 너머를 보는 법
로그는 위에서 아래로 읽는 게 아닙니다
많은 개발자분들이 배포가 실패하면 반사적으로 스크롤을 맨 아래로 휙 내립니다. 왜냐하면 터미널이나 일반적인 프로그램에서는 에러 메시지가 마지막에 출력되는 경우가 많기 때문이죠. 하지만 깃허브 액션과 같은 CI/CD 도구에서 이것은 반은 맞고 반은 틀린, 때로는 아주 위험한 접근입니다. 실제로 맨 마지막 줄에는 "Process completed with exit code 1"이라는, 아무런 정보가 없는 시스템 종료 메시지만 남아있는 경우가 허다합니다. 진짜 원인(Root Cause)은 그보다 훨씬 위, 수십 줄, 때로는 수백 줄 위에 숨어서 우리를 비웃고 있을지 모릅니다.
제가 겪었던 실제 사례를 하나 구체적으로 말씀드리죠. 한 번은 대규모 노드(Node.js) 프로젝트 빌드가 실패했는데, 맨 마지막 줄에는 단순히 "npm run build failed"라고만 적혀 있었습니다. 팀원 3명이 붙어서 3시간 동안 웹팩(Webpack) 설정 파일과 package.json만 샅샅이 뒤지고 있었죠. 하지만 제가 로그를 중간쯤으로 천천히 올려보니, 아주 작게 "Killed"라는 단 한 단어가 찍혀 있는 것을 발견했습니다. 이것은 리눅스 커널이 메모리 부족을 감지하고 프로세스를 강제 종료시킨 OOM(Out of Memory) 현상이었습니다. 원인은 코드가 아니라 깃허브 호스티드 러너(GitHub Hosted Runner)의 기본 메모리(7GB)를 초과한 것이었죠. 로그의 '맥락'을 파악하지 않고 마지막 줄만 봤다면 며칠을 허비했을지도 모릅니다.
접혀있는 그룹(Collapsed Groups)을 의심하세요
깃허브 액션 로그 UI는 사용자의 시각적 편의를 위해 성공한 단계나 지나치게 긴 출력 내용을 자동으로 접어(Collapse) 둡니다. 하지만 악마는 디테일에, 그리고 그 접힌 부분에 교묘하게 숨어 있습니다. 특히 setup-node, actions/checkout, gradle-build-action 같은 초기 설정 단계가 성공했다고 초록색 체크 표시가 떠 있어도, 절대 안심해서는 안 됩니다. 그 안을 열어보면 빨간색 에러는 아니지만, 노란색 경고(Warning) 메시지가 가득할 수 있기 때문입니다.
예를 들어, actions/checkout 단계에서 "Git submodules not updated" 같은 경고가 떴지만, 옵션 설정에 따라 단계 자체는 성공으로 처리될 수 있습니다. 이렇게 되면 이후 빌드 단계에서 특정 파일이 없다는 "File not found" 에러가 발생하게 됩니다. 우리는 당연히 빌드 스크립트가 잘못되었다고 생각하겠지만, 사실 원인은 훨씬 이전 단계인 체크아웃에 있었던 것이죠. 따라서 실패 분석 시에는 성공한 것처럼 보이는 이전 단계의 로그도 반드시 펼쳐서(Expand) Warning 메시지를 확인하는 습관을 들여야 합니다. 이것이 주니어와 시니어를 가르는 디버깅 습관의 차이입니다.
디버그 로깅 활성화: 숨겨진 정보를 찾는 치트키
로그를 아무리 봐도 원인을 알 수 없다면, 깃허브 액션이 숨기고 있는 더 상세한 정보를 꺼내야 합니다. 이때 사용하는 치트키가 바로 디버그 로깅(Debug Logging)입니다. 저장소의 Settings > Secrets and variables > Actions로 이동하여 ACTIONS_STEP_DEBUG라는 이름의 Secret을 생성하고, 값을 true로 설정해 보세요.
이렇게 설정하고 워크플로우를 다시 실행하면, 이전에는 보이지 않던 보라색 디버그 로그들이 쏟아져 나옵니다. 파일이 어떤 경로로 복사되는지, 환경 변수가 정확히 어떤 값으로 치환되었는지, 쉘 명령어가 실제로 어떻게 실행되었는지 낱낱이 보여줍니다. 마치 마술사가 트릭을 공개하는 것과 같죠. 평소에는 로그 양이 너무 많아져서 꺼두는 것이 좋지만, 원인 불명의 에러를 만났을 때는 이보다 강력한 도구는 없습니다.
2. 환경 변수(Environment Variables)의 미스터리 추적
💬 여러분의 경험을 들려주세요!
✨ 이 방법을 시도해보셨나요? 댓글로 공유해주세요!
📌 도움이 되셨다면 저장하고 주변에도 알려주세요.
🔔 더 많은 개발 팁을 받고 싶다면 구독해주세요!
댓글
댓글 쓰기