2026년 10월 말, 저희는 Laravel 보안 업데이트를 하면서(관련 글: Laravel 인증 우회 CVE-2026-114509 점검법) 저희가 만든 관리자 화면 제품도 함께 올렸습니다. 이 제품은 Laravel용 관리자 패널 도구인 Filament를 쓰는데, Filament를 4.11.7에서 4.15.3으로 올리는 과정에서 배포용 코드를 만드는 스크립트가 PHP 코드는 새 버전으로, 화면용 JS·CSS·글꼴 파일은 옛 버전으로 남기는 문제를 찾았습니다. 오류는 한 줄도 나오지 않았습니다. 실제 배포 저장소에 반영하기 전에 복사본으로 연습 실행을 하다가 발견했고, 고친 뒤에 반영했습니다.

패키지 업데이트 자체는 순조로웠습니다. Filament와 관련 패키지를 올린 뒤 composer audit의 보안 권고는 0건이 됐고, 기존 자동 시험 403건도 그대로 통과했습니다. 문제는 업데이트가 아니라 그 결과를 배포용 브랜치로 옮기는 스크립트에서 생겼습니다.

배경: 배포용 브랜치는 이렇게 만들어집니다

이 제품은 개발용 브랜치와 별개로, 서버에 올릴 파일만 모은 배포용 브랜치를 스크립트로 만듭니다. 스크립트는 개발용 브랜치의 변경을 옮겨 오고(cherry-pick), 문서 루트를 public 폴더로 지정할 수 없는 호스팅에서도 쓸 수 있도록 public 안의 파일을 저장소 루트로 펴며(평탄화), 운영용 vendor를 새로 만들어 함께 담습니다.

Filament의 화면용 파일(JS, CSS, 글꼴)은 vendor 안에 들어 있는 원본(vendor/filament/*/dist)을 php artisan filament:assets 명령이 public 폴더로 복사한 것입니다. Filament 문서도 이 명령이 등록된 에셋을 public 폴더로 복사한다고 설명합니다. 그런데 저희 배포 스크립트는 composer install을 --no-scripts로 돌립니다. Composer 문서에 따르면 이 옵션은 composer.json에 정의된 스크립트를 실행하지 않습니다. Filament 문서는 설치할 때 composer.json의 post-autoload-dump에 에셋을 최신으로 맞춰 주는 명령(filament:upgrade)을 넣어 둔다고 설명하는데, 저희 제품의 composer.json에도 이 명령이 들어 있어서 --no-scripts로 설치하면 이 자동 갱신은 일어나지 않습니다. 그래서 복사본을 저장소에 직접 커밋해 두어야 하고, vendor(PHP)와 복사본(JS·CSS)의 버전은 항상 같아야 합니다.

무슨 일이 있었나

Filament 업그레이드 커밋을 배포용 브랜치로 옮기자, git이 개발용 브랜치의 public/js/filament, public/fonts/filament 변경을 내용이 같은 vendor/filament/*/dist 파일의 이름 변경으로 잘못 짝지었습니다. 그 결과 변경이 vendor 쪽에만 반영되고, 평탄화된 배포용 브랜치 루트의 js·css·fonts/filament 파일은 옛 버전(4.11.7) 그대로 남았습니다. vendor의 PHP는 새 버전, 화면용 JS·CSS는 옛 버전인 조합이었고, 루트 에셋 대부분이 vendor 원본과 달랐습니다.

이 상태는 아무 오류도 내지 않았습니다. 스크립트의 자동 충돌 해결 규칙이 짝이 어긋난 자리를 조용히 통과시켰고, 스크립트는 정상 종료했습니다. 새 PHP 코드와 옛 JS가 섞이면 반복 입력이나 빌더 같은 일부 화면 요소가 오류를 낼 수 있다고 판단했습니다.

어떻게 찾았나

실제 배포 저장소를 건드리기 전에, 임시 복사본(원격 저장소까지 흉내 낸 사본)에서 이 스크립트를 세 번 연습 실행했습니다. 그 연습 실행에서 만들어진 배포용 브랜치의 에셋이 거의 전부 옛 버전이라는 것을 확인했습니다. 연습 없이 실제 저장소에서 처음 실행했다면 같은 일이 그대로 일어날 수 있었습니다.

어떻게 고쳤나

  1. 옮기지 말고 다시 만듭니다. 새 vendor를 만든 작업 폴더에서 php artisan filament:assets를 실행해 루트의 js·css·fonts/filament를 통째로 다시 만들고, 별도 커밋으로 담습니다. 매번 지우고 다시 만들기 때문에 같은 결과가 반복되고(두 번째 실행에서는 새 커밋이 생기지 않았습니다), 이름에 해시가 붙은 옛 글꼴 파일이 남지도 않습니다.
  2. 옛 복사본의 변경은 들이지 않습니다. cherry-pick이 가져온 개발용 브랜치의 public/…/filament 변경은 평탄화 전에 제거해, 평탄화 때 폴더가 겹겹이 중첩되는 일도 막습니다.
  3. 푸시 전에 스스로 점검합니다. 루트 에셋 파일의 내용(git blob)이 모두 vendor/filament/*/dist 안에 같은 내용으로 존재하는지, 개발용 에셋과 배포용 에셋의 파일 목록이 같은지, 배포용 브랜치에 있으면 안 되는 개발 전용 경로가 추적되고 있지 않은지 확인합니다. 하나라도 어긋나면 푸시하지 않고 중단합니다. 파일 목록 비교를 따로 넣은 것은, filament:assets가 일부 파일을 복사하지 못해도 성공으로 끝나는 것을 확인했기 때문입니다.

고친 뒤 연습 실행에서 불일치는 0건이 됐고, 같은 스크립트를 두 번째 돌렸을 때 새 커밋은 생기지 않았습니다. 그 뒤 실제 배포 저장소에서 같은 스크립트를 푸시 직전 단계까지 실행했을 때 점검이 통과했고, 루트 에셋 41개가 모두 vendor 원본과 내용까지 같았습니다. 이 결과를 확인한 다음에 반영했습니다.

아직 남은 한계

  • 두 브랜치가 같은 줄을 다르게 고친 진짜 내용 충돌은 여전히 사람이 직접 풀어야 합니다.
  • Filament 이외의 public 파일에도 같은 이름 변경 짝짓기가 생길 수 있습니다. 이번 점검은 Filament 에셋만 대조합니다.
  • 연습 실행에 쓴 환경이 실제 개발 환경과 완전히 같지는 않았습니다.

배운 것

  • 생성 파일은 옮기지 말고 원본에서 다시 만듭니다. 복사본의 변경 내역을 git이 따라 옮기게 두면, 이번처럼 변경이 엉뚱한 파일에 붙을 수 있습니다.
  • git은 병합할 때 파일 이름 변경을 자동으로 찾아냅니다. git 문서에 따르면 병합 전략은 이름 변경을 감지하고 처리하며, 이름 변경 감지는 기본으로 켜져 있고 유사도 기준을 정해 둘 수 있습니다. cherry-pick도 같은 병합 전략의 옵션을 받습니다. 내용이 같은 파일이 여러 곳에 있는 저장소(vendor 안 원본과 public의 복사본처럼)에서는 의도와 다른 짝이 지어질 수 있습니다.
  • 오류가 없다는 것과 맞다는 것은 다릅니다. 자동 충돌 해결이 조용히 지나간 자리는 결과를 직접 대조하는 점검이 필요합니다.
  • 점검이 실패하면 스크립트가 멈추게 합니다. 사람이 로그를 읽어 주기를 기대하는 것보다 스크립트가 푸시를 막는 편이 확실합니다.

Filament을 쓴다면 확인할 것

  • Filament 문서는 설치 때 들어가는 에셋 갱신 명령을 composer.json에 그대로 두라고 안내합니다. 지우면 운영에서 에셋이 없거나 옛 버전이 되는 문제를 만날 수 있고, 지워야 한다면 배포 과정에서 그 명령을 직접 실행해야 한다고 합니다.
  • 배포가 composer 스크립트를 건너뛰는 방식(--no-scripts)이라면 에셋을 맞추는 단계를 따로 넣습니다.
  • 배포 스크립트는 실제 저장소에 쓰기 전에 복사본에서 연습 실행하고, 결과물을 vendor 원본과 대조합니다.
  • 업그레이드 뒤에는 관리자 화면을 열어 브라우저 개발자도구 콘솔에 JS 오류나 파일을 못 찾는 요청이 없는지 확인합니다.

Laravel이나 Filament 같은 프레임워크 업데이트는 해 두었는데 배포 과정이 사람 손에 달려 있어 불안하다면, 포르본허가 배포 스크립트 점검부터 연습 실행, 푸시 전 자체 점검 구성까지 도와드릴 수 있습니다. 아래 문의 양식에 상황을 간단히 남겨 주세요.

참고 자료