배포 스크립트 경로를 모노레포 표준에 맞게 바로잡다

publish.sh의 환경 변수 경로가 개발 환경(BOT_DIR/venv) 중심으로 박혀있었고, 실제 프로덕션 배포 환경의 표준 경로(/opt/bots 모노레포)와 맞지 않던 부분을 교정했다. 작아 보이지만 배포 파이프라인 일관성과 팀 온보딩에 생각보다 큰 영향을 주는 작업이었다.

배포 스크립트가 마주한 경로의 혼란

처음 publish.sh를 세웠을 때는 로컬 개발 환경을 기준으로 만들어졌을 것 같다. BOT_DIR/venv라는 상대 경로는 개발자의 작업 디렉터리 구조(아마도 각 봇 프로젝트 안에 venv 가상환경을 두는 식)를 반영한 것인데, 이게 그대로 CI/CD나 운영 환경에 심어지면서 문제가 생긴다.

실제 문제는 두 가지였다.

첫째, 경로 해석의 모호성. publish.sh가 어느 디렉터리에서 실행되는지에 따라 BOT_DIR/venv가 가리키는 곳이 달라진다. CI 파이프라인에서 이 스크립트를 호출할 때, 현재 워킹 디렉터리가 애매했다면 스크립트는 엉뚱한 경로를 참조할 가능성이 크다.

둘째, 모노레포 구조와의 불일치. 팀이 여러 봇을 /opt/bots 아래 중앙집중식으로 관리하는 모노레포 구조로 정규화했는데, 배포 스크립트만 여전히 개별 프로젝트 단위의 레이아웃을 가정하고 있었다. 신입이 온보딩할 때 "publish.sh가 참조하는 venv는 어디에 있나요?" 같은 질문이 계속 나올 수밖에 없다.

절대 경로 vs 상대 경로의 선택

이번 교정은 단순히 상대 경로를 절대 경로로 바꾼 것으로 보인다.

이 선택이 생각보다 중요한 이유는, 배포 스크립트는 반드시 독립적이어야 한다는 원칙 때문이다. 누가 언제 어디서 호출하든 같은 결과를 내야 한다. 상대 경로는 그 실행 맥락에 종속되므로, 자동화된 배포 환경에서는 버그의 온상이 된다.

그렇다면 왜 처음부터 절대 경로를 안 썼을까

아마 네 가지 이유가 있었을 거다.

1. 개발 시 편의성: 로컬에서 각자의 프로젝트 디렉터리에서 테스트하기 쉽다. 그냥 ./publish.sh 실행하면 된다.
2. 마이그레이션 부담: 이미 여러 곳에서 호출되고 있던 스크립트를 바꾸려면 모든 호출처도 수정해야 한다.
3. 표준화 미결정: 초기에 모노레포로 완전히 이동할 계획이 없었거나, 구조가 아직 유동적이었을 수 있다.
4. 점진적 증축: publish.sh는 원래 개발 환경용으로 만들고, 나중에 배포 자동화로 확장한 후 경로 문제가 드러났을 가능성.

커밋하기 전 확인했던 것들

이 변경을 할 때 체크리스트는 아마 이랬을 거다.

• publish.sh를 호출하는 모든 자동화 파이프라인이 /opt/bots 경로에서 정상 작동하는가
• 로컬 개발 환경에서 여전히 동작하는가 (또는 별도 가이드 필요)
• 다른 스크립트/설정 파일에서 BOT_DIR/venv를 참조하는 곳은 없는가
• Git 히스토리에 이 경로가 하드코딩된 다른 곳은 없는가

특히 마지막 항목은 중요하다. 경로 일관성이 깨진 건 보통 한두 군데가 아니라, 프로젝트 전체에 퍼져 있는 경우가 많기 때문이다. Grep으로 BOT_DIR나 venv 참조를 전수조사 후, 이번 커밋과 함께 또는 별도 PR로 처리해야 한다.

배운 점: 스크립트 경로는 일찍 정규화하자

비슷한 상황을 또 마주쳤을 때의 대응 원칙을 정리했다.

개발 초기에 배포 스크립트를 고려하자. "나중에 바꿔도 되겠지"라고 미루면, 몇 달 뒤에는 이미 여러 파이프라인과 문서가 그 스크립트를 참조하고 있다.

모노레포로 이동 결정 후 경로부터 정규화하자. 로직을 다 마친 후 경로를 정정하면 회귀 테스트가 늘어난다. 구조 결정과 동시에 스크립트를 다시 쓰는 게 낫다.

절대 경로 vs 상대 경로는 용도에 맞게. 자동화/배포용 스크립트는 절대 경로, 개발자 편의용 로컬 스크립트는 상대 경로로 명확히 구분하자. 필요하면 두 버전을 유지하는 것도 방법이다.

코드 리뷰에서 경로를 주의깊게 본다. 스크립트 수정은 "파일 몇 줄 변경"으로 보이지만, 배포 환경에서 폭발할 수 있다. 경로, 권한, 환경변수 변경은 테스트 체크리스트를 더 엄격하게 본다.

이번 교정은 작은 변경처럼 보이지만, 배포 파이프라인의 안정성과 팀 온보딩의 명확성을 동시에 높인 작업이었다.

🛒 이 글과 어울리는 추천 상품

• 기계식키보드 쿠팡에서 보기 →
• 모니터암 쿠팡에서 보기 →
• 사무의자 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.