loose 사본으로 배포 실패하던 함정 문서화
목차
ops 라이브러리를 서버에 배포할 때 자주 겪는 일이 있다. git pull 로 최신 코드를 받아도 실제 스크립트는 예전 버전이 그대로 남아있는 상황이다. 결국 "어? 방금 고친 스크립트가 왜 작동 안 하는데?" 하면서 한참 헤매다가 수동으로 파일을 복사해야 하는 경험 말이다. 이번에는 이 함정을 배포 자동화 계획에 명시해서, 팀원들이 같은 실수를 반복하지 않도록 선제 조치를 했다.
문제: git pull 후에도 스크립트가 안 바뀐다
ops 라이브러리가 관리되는 방식이 일반적인 git 저장소와 좀 다르다. /opt/_lib 라는 공유 디렉토리에 스크립트들이 놓여있는데, 이 파일들이 모두 git 으로 추적되는 건 아니기 때문이다. 일부 스크립트는 "loose 사본"이라고 부르는데, 이건 git 에 등록되지 않은 채로 로컬 서버에만 존재하는 파일을 뜻한다.
왜 이런 구조가 생겼는가? 실제로 배포 환경마다 조금씩 다르게 설정돼야 하는 스크립트들이 있다. 예를 들어 인증 정보, 로컬 경로, 환경 변수 같은 것들이 서버마다 다르기 때문에, 이런 파일들은 git 에 올리지 않고 각 서버에서 수동으로 관리하는 방식을 선택한 것이다. 좋은 실천 방식이긴 하지만, 문제는 배포 프로세스가 이 점을 충분히 명시하지 않으면 자동화 스크립트나 신입 팀원 입장에서 "pull 받으면 다 됐겠지" 하고 놓치기 쉽다는 것이다.
왜 자주 빠지는가: 암묵적 절차의 위험성
git pull 이라는 명령은 그 자체로 완전한 동기화로 느껴진다. 하지만 loose 사본의 경우:
- git pull 은 git 추적 파일만 업데이트한다
- loose 사본은 그냥 남겨진다 (git 에 없으니까)
- cp 나 rsync 같은 별도 명령으로 수동 복사해야 한다
새 팀원이나 자동화 배포 스크립트 작성자 입장에서는 이걸 몰라서 "아, pull 하면 되겠네" 하고 끝낸다. 결과는 배포 실패 또는 예상치 못한 동작이다. 특히 CI/CD 파이프라인에서 이런 일이 생기면 "뭔가 이상한데 왜지?" 하고 한참을 헤매게 된다.
해결책: 배포 플랜에 함정 명시
이번에 GSC-AUTOMATION-PLAN.md 에 /opt/_lib 배포 단계를 다시 정리하면서, "pull 후에는 반드시 cp 로 loose 사본도 복사해야 한다"는 점을 명확하게 명시했다. 단순한 한두 문장이지만, 이게 문서에 없으면 나중에 온보딩하는 팀원이나 배포 스크립트 작성자가 삽질할 여지가 훨씬 크다.
배포 절차:
1. git pull
2. cp /opt/_lib/scripts/* /dest/ # loose 사본 포함
3. 권한 설정 (chmod)
이렇게 스텝별로 명시되면 "아, 두 단계를 다 해야 하는구나" 하고 자동화 스크립트도 그렇게 짜거나 체크리스트도 그렇게 따르게 된다.
회고: 문서화가 팀 효율을 좌우한다
지금 생각해 보니, 이런 류의 배포 함정이 왜 반복되는지는 명확하다. "다들 알겠지" 하는 암묵적 가정이 위험하다는 뜻이다. 특히 다음 경우에 심하다:
- 새로운 팀원의 온보딩: 선배들은 "loose 사본" 이 뭔지 알지만, 신입은 모른다. 입문서에 나와 있지 않으면 스스로 겪고 배운다.
- 자동화 도구 작성: 누군가 배포 도구를 짜려고 할 때, 문서가 없으면 git pull 만 한다.
- 사고 후 사후 처리: 배포 실패가 발생하고 나서야 "아, loose 사본 때문이네" 깨닫는다.
이걸 방지하려면 "모두가 알아야 할 것"이 명확하게 정리되고 접근 가능해야 한다. 배포 계획 문서는 정확히 그런 용도다. 코드와 달리 문서는 "왜"와 "함정"을 담을 수 있는 공간이고, 이게 팀 전체의 배포 신뢰도를 높인다.
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.