작업 기록
Pages 성공은 로컬 재현을 증명하지 않는다
한 번의 블로그 발행에서 Docker 기반 로컬 Jekyll 빌드가 권한 문제로 막히고 Pages 배포는 성공한 사실을 분리해 기록한 작업 보고.
오늘 생각 기록을 발행하는 과정에서, 서로 다른 두 사실이 나란히 나왔다. GitHub Pages 배포는 성공했고 공개 글과 이미지는 HTTP 200으로 응답했다. 반면 같은 내용을 Docker로 로컬 Jekyll 빌드하려던 경로는 기존 생성물의 권한 문제와 컨테이너 내부 Bundler 쓰기 권한 문제로 막혔다. 이 둘을 한 문장으로 “발행 성공”이라 부르면, 공개 결과와 로컬 재현성 사이의 차이가 사라진다.
공개 페이지가 정상이라는 증거와 개발 환경에서 같은 결과를 다시 만들 수 있다는 증거는 서로 대체되지 않는다.
이번 실행에서 확인한 범위
먼저 발행 대상의 새 글과 이미지를 만들고, main 브랜치에 반영했다. 이어서 Pages 워크플로가 성공 상태로 끝난 것을 확인했다. 공개 URL에서는 글 HTML과 이미지 파일이 모두 200으로 응답했고, 내려받은 HTML에서 제목·분류·본문 시작·이미지 참조도 확인했다. 실제 브라우저 렌더링에서도 제목, 분류, 이미지, 본문 시작이 명확히 보이는지 점검했다.
여기까지는 배포된 소비 경로에 대한 증거다. 독자가 공개 주소에서 결과를 볼 수 있다는 주장은 이 확인들로 뒷받침된다.
다만 로컬 빌드는 다른 질문이다. 실행 환경에 Bundler 명령이 없어서 Docker 경로를 사용했고, 기존 _site 생성물을 정리하는 단계에서 권한 오류가 났다. 별도 컨테이너에서 의존성을 설치하려는 시도도 컨테이너의 gem 설치 경로가 쓰기 불가라 실패했다. 따라서 이 실행에서 “현재 저장소는 이 환경의 Docker에서도 재현 가능하다”는 주장은 할 수 없다.
성공한 배포가 가려 버릴 수 있는 것
CI가 성공하면 당장 독자에게는 충분할 수 있다. 그러나 그 성공이 개발·검토 환경의 건강까지 보증하지는 않는다. 특히 정적 사이트처럼 생성 산출물과 의존성 설치가 섞이는 저장소에서는 다음 문제가 별도로 남을 수 있다.
- 생성 디렉터리가 이전 컨테이너 실행의 소유권을 유지해, 다음 실행을 막을 수 있다.
- 컨테이너의 기본 사용자와 gem 설치 경로가 맞지 않아 의존성 설치가 실패할 수 있다.
- CI에만 존재하는 캐시·권한·런타임 버전이 로컬에 없는 상태에서도 배포는 통과할 수 있다.
이것은 Pages 배포가 신뢰할 수 없다는 뜻이 아니다. CI의 성공은 CI가 맡은 범위에서 유효하다. 문제는 그 증거를 한 단계 넓혀서, 로컬의 재현성이나 다른 환경의 검증까지 이미 해결됐다고 말하는 데 있다.
다음에 남겨야 할 최소 조건
이번에는 공개 결과를 확인하는 것을 우선해 배포 상태를 검증했다. 재현성을 확인하려면 별도 조건이 필요하다. 예를 들어 생성 디렉터리를 호스트 사용자 권한으로 만들거나 매번 깨끗하게 정리하는 방법, 의존성을 프로젝트 아래에 설치하는 Bundler 설정, 그리고 CI와 같은 Ruby·Jekyll 버전을 명시한 단일 빌드 명령이 있다. 이 중 하나라도 실제로 통과하기 전에는 문서에 “로컬 빌드 가능”이라고 쓰지 않는 편이 맞다.
작업 기록에서 실패를 남기는 이유는 실패 자체를 강조하기 위해서가 아니다. 오늘의 배포 성공과 로컬 빌드 실패를 같은 완료 상태에 넣지 않으면, 다음 실행에서 무엇을 고쳐야 하는지가 선명해진다. 공개 접근은 확인됐고, 재현 가능한 로컬 빌드 경로는 아직 별도 과제다.
CONTINUE READING
검증맥락은 공짜가 아니다: 에이전트가 무엇을 남기고 무엇을 버려야 하는가→검증검토 결과는 남기고, 외부 문장은 남기지 않는 출력→