하루에 세 번 바꾼 배포 제외 규칙

2026년 10월 25일 · 도구·자동화 · English

이 사이트는 빌드 단계가 없는 정적 사이트다. 소스 파일이 그대로 사이트가 되고, 저장소 루트를 통째로 Firebase Hosting 에 올린다. 그러면 저장소에 있는 파일이 전부 사이트에 올라갈 수 있다. 도구, 문서, 그림 원본, 비공개 설정 같은 것은 올라가면 안 된다. 어떤 파일을 뺄지 정하는 방법을 하루 사이에 세 번 바꿨다.

Firebase Hosting 은 구글의 정적 사이트 호스팅이다. 설정 파일 firebase.json 의 ignore 목록에 적은 파일은 올라가지 않는다. 배포는 GitHub Actions 가 저장소를 새로 받아서 한다. 그러니 git 이 무시하는 파일은 배포 환경에 아예 없다. 문제는 git 에 들어 있는 파일 중 올라가면 안 되는 것을 어떻게 가려내느냐였다.

처음에는 *.md 같은 확장자와 인증 파일 이름(gha-creds-*) 같은 규칙으로 올리지 않을 파일을 걸렀다. 게임 상태를 적는 파일을 games 폴더 안의 list.json 에 두었는데, 이 폴더는 사이트에 공개되는 폴더였다. 그 파일만 이름으로 제외해 두었지만 이 방식은 빠졌는지 확인할 방법이 없었다. 규칙에 걸리지 않은 파일이 있어도 알 수 없고, 하나만 어긋나면 파일이 조용히 올라간다. 비공개로 두려던 파일이 사이트에서 열린 적도 있다.

상태 파일을 config/ 폴더로 옮기고 config/** 를 통째로 제외했다. 배포되는 파일 안에 이 파일의 경로를 적은 주석이 남아 있어서 그것도 지웠다. 배포 단계에는 두 가지 확인을 넣었다. config/** 가 제외 목록에 없으면 실패한다. 배포되는 파일이 상태 파일 이름을 말하고 있어도 실패한다. 폴더 단위로 바꾸어 이 파일은 확실히 막혔다. 그런데 *.md 같은 이름 규칙으로 걸러 내던 다른 파일들은 여전히 그대로였다.

같은 날 아예 기준을 하나로 통일했다. 사이트에 올리지 않는 것은 루트 바로 밑 폴더 이름과 점으로 시작하는 이름으로만 정한다. 도구는 tools/, 문서는 docs/, 운영 설정은 config/, 그림 원본은 art-src/, 기록은 logs/ 에 둔다. 확장자와 파일 이름 규칙은 모두 없앴다.

"ignore": ["config/**", "tools/**", "docs/**", "logs/**", "art-src/**",
           "**/.*", "**/.*/**", "firebase.json", "CLAUDE.md", "games/CLAUDE.md"]

그러려면 이름 규칙에 기대던 파일을 모두 제외 폴더로 옮겨야 했다. 문서(CREDITS, NOTES, TODO)는 docs/ 로, 보안 규칙 파일은 config/ 로, 새 게임 틀은 tools/game-template/ 로, 게임별 그림 원본은 art-src/ 로 옮겼다. 인증 파일은 배포 중 만들어지는데 이름 규칙으로 빼는 대신 작업 폴더 밖으로 옮기게 했다.

모르는 항목이 있으면 배포를 멈춘다

더 중요한 것은 확인이다. 배포본을 만드는 단계에서 루트에 있는 항목을 하나씩 본다. 각 항목은 제외 폴더, 점으로 시작하는 이름, 제외 목록에 적은 파일, 사이트 파일 목록 중 하나에 들어 있어야 한다. 어디에도 들어 있지 않은 항목이 있으면 배포를 실패시킨다.

const unknown = fs.readdirSync(ROOT).filter((f) => !f.startsWith('.')
  && !outDirs.includes(f) && !ignore.includes(f) && !SITE_ROOT.includes(f));
if (unknown.length) throw new Error(`unknown root entries: ${unknown.join(', ')}`);

설명을 위해 줄인 예시다. 핵심은 허용 목록 방식이라는 점이다. 새 파일을 루트에 만들면 사이트에 올릴 것인지 아닌지를 사람이 정해야 배포가 통과한다. 이 개발 이야기를 위해 만든 devlog/ 폴더도 사이트 파일 목록에 직접 추가해야 했다.

참고한 문서

• Firebase, Hosting 설정(ignore): https://firebase.google.com/docs/hosting/full-config